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