docs/busybox_header.pod

   1 # vi: set sw=4 ts=4:
   2
   3 =head1 NAME
   4
   5 BusyBox - The Swiss Army Knife of Embedded Linux
   6
   7 =head1 SYNTAX
   8
   9  BusyBox <function> [arguments...]  # or
  10
  11  <function> [arguments...]          # if symlinked
  12
  13 =head1 DESCRIPTION
  14
  15 BusyBox combines tiny versions of many common UNIX utilities into a single
  16 small executable. It provides minimalist replacements for most of the utilities
  17 you usually find in GNU coreutils, util-linux, etc. The utilities in BusyBox
  18 generally have fewer options than their full-featured GNU cousins; however, the
  19 options that are included provide the expected functionality and behave very
  20 much like their GNU counterparts. BusyBox provides a fairly complete POSIX
  21 environment for any small or embedded system.
  22
  23 BusyBox has been written with size-optimization and limited resources in mind.
  24 It is also extremely modular so you can easily include or exclude commands (or
  25 features) at compile time. This makes it easy to customize your embedded
  26 systems. To create a working system, just add /dev, /etc, and a Linux kernel.
  27
  28 BusyBox is extremely configurable.  This allows you to include only the
  29 components you need, thereby reducing binary size. Run 'make config' or 'make
  30 menuconfig' for select the functionality that you wish to enable.  The run
  31 'make' to compile BusyBox using your configuration.
  32
  33 After the compile has finished, you should use 'make install' to install
  34 BusyBox.  This will install the '/bin/busybox' binary, and will also create
  35 symlinks pointing to the '/bin/busybox' binary for each utility that you
  36 compile into BusyBox.  By default, 'make install' will place these symlinks
  37 into the './_install' directory, unless you have defined 'PREFIX', thereby
  38 specifying some alternative location (i.e., 'make PREFIX=/tmp/foo install').
  39 If you wish to install using hardlinks, rather than the default of using
  40 symlinks, you can use 'make PREFIX=/tmp/foo install-hardlinks' instead.
  41
  42 =head1 USAGE
  43
  44 BusyBox is a multi-call binary.  A multi-call binary is an executable program
  45 that performs the same job as more than one utility program.  That means there
  46 is just a single BusyBox binary, but that single binary acts like a large
  47 number of utilities.  This allows BusyBox to be smaller since all the built-in
  48 utility programs (we call them applets) can share code for many common operations.
  49
  50 You can also invoke BusyBox by issuing the command as an argument on the
  51 command line.  For example, entering
  52
  53         /bin/busybox ls
  54
  55 will also cause BusyBox to behave as 'ls'.
  56
  57 Of course, adding '/bin/busybox' into every command would be painful.  So most
  58 people will invoke BusyBox using links to the BusyBox binary.
  59
  60 For example, entering
  61
  62         ln -s /bin/busybox ls
  63         ./ls
  64
  65 will cause BusyBox to behave as 'ls' (if the 'ls' command has been compiled
  66 into BusyBox).  Generally speaking, you should never need to make all these
  67 links yourself, as the BusyBox build system will do this for you when you run
  68 the 'make install' command.
  69
  70 If you invoke BusyBox with no arguments, it will provide you with a list of the
  71 applets that have been compiled into your BusyBox binary.
  72
  73 =head1 COMMON OPTIONS
  74
  75 Most BusyBox commands support the B<--help> argument to provide a terse runtime
  76 description of their behavior.  If the CONFIG_FEATURE_VERBOSE_USAGE option has
  77 been enabled, more detailed usage information will also be available.
  78
  79 =head1 COMMANDS
  80
  81 Currently defined functions include:
  82
  83         addgroup, adduser, adjtimex, ar, arping, ash, awk, basename, bunzip2,
  84         busybox, bzcat, cal, cat, chgrp, chmod, chown, chroot, chvt, clear,
  85         cmp, cp, cpio, crond, crontab, cut, date, dc, dd, deallocvt, delgroup,
  86         deluser, df, dirname, dmesg, dos2unix, dpkg, dpkg-deb, du, dumpkmap,
  87         dumpleases, dutmp, echo, egrep, env, expr, false, fbset, fdflush,
  88         fdformat, fgrep, find, fold, free, freeramdisk, fsck.minix, ftpget,
  89         ftpput, getopt, getty, grep, gunzip, gzip, halt, hdparm, head, hexdump,
  90         hostid, hostname, httpd, hush, hwclock, id, ifconfig, ifdown, ifup,
  91         inetd, init, insmod, ip, ipcalc, iplink, iproute, iptunnel, kill,
  92         killall, klogd, lash, length, linuxrc, ln, loadfont, loadkmap, logger,
  93         login, logname, logread, losetup, ls, lsmod, makedevs, md5sum, mesg,
  94         minit, mkdir, mkfifo, mkfs.minix, mknod, mkswap, mktemp, modprobe,
  95         more, mount, msh, msvc, mt, mv, nameif, nc, netstat, nslookup, od,
  96         openvt, passwd, patch, pidfilehack, pidof, ping, ping6, pivot_root,
  97         poweroff, printf, ps, pwd, rdate, readlink, realpath, reboot, renice,
  98         reset, rm, rmdir, rmmod, route, rpm, rpm2cpio, run-parts, sed,
  99         setkeycodes, sha1sum, sleep, sort, start-stop-daemon, strings, stty,
 100         su, sulogin, swapoff, swapon, sync, syslogd, tail, tar, tee, telnet,
 101         telnetd, test, tftp, time, top, touch, tr, traceroute, true, tty,
 102         udhcpc, udhcpd, umount, uname, uncompress, uniq, unix2dos, unzip,
 103         uptime, usleep, uudecode, uuencode, vconfig, vi, vlock, watch,
 104         watchdog, wc, wget, which, who, whoami, xargs, yes, zcat, [
 105
 106 =head1 LIBC NSS
 107
 108 GNU Libc (glibc) uses the Name Service Switch (NSS) to configure the behavior
 109 of the C library for the local environment, and to configure how it reads
 110 system data, such as passwords and group information.  This is implemented
 111 using an /etc/nsswitch.conf configuration file, and using one or more of the
 112 /lib/libnss_* libraries.  BusyBox tries to avoid using any libc calls that make
 113 use of NSS.  Some applets, such as login and su, will use libc functions that
 114 usually require NSS.
 115
 116 If you enable CONFIG_USE_BB_PWD_GRP, BusyBox will use internal functions to
 117 directly access the /etc/passwd, /etc/group, and /etc/shadow files without
 118 using NSS.  This may allow you to run your system without the need for
 119 installing any of the NSS configuration files and libraries.
 120
 121 When used with glibc, the BusyBox 'networking' applets will similarly require
 122 that you install at least some of the glibc NSS stuff (in particular,
 123 /etc/nsswitch.conf, /lib/libnss_dns*, /lib/libnss_files*, and /lib/libresolv*).
 124
 125 Shameless Plug: As an alternative one could use a C library such as uClibc.  In
 126 addition to making your system significantly smaller, uClibc does not need or
 127 use any NSS support files or libraries.
 128
 129 =over 4
 130
 131