1 | <!--#include file="header.html" -->
|
---|
2 |
|
---|
3 | <h3>Frequently Asked Questions</h3>
|
---|
4 |
|
---|
5 | This is a collection of some of the more frequently asked questions
|
---|
6 | about BusyBox. Some of the questions even have answers. If you
|
---|
7 | have additions to this FAQ document, we would love to add them,
|
---|
8 |
|
---|
9 | <h2>General questions</h2>
|
---|
10 | <ol>
|
---|
11 | <li><a href="#getting_started">How can I get started using BusyBox?</a></li>
|
---|
12 | <li><a href="#configure">How do I configure busybox?</a></li>
|
---|
13 | <li><a href="#build">How do I build BusyBox with a cross-compiler?</a></li>
|
---|
14 | <li><a href="#build_system">How do I build a BusyBox-based system?</a></li>
|
---|
15 | <li><a href="#kernel">Which Linux kernel versions are supported?</a></li>
|
---|
16 | <li><a href="#arch">Which architectures does BusyBox run on?</a></li>
|
---|
17 | <li><a href="#libc">Which C libraries are supported?</a></li>
|
---|
18 | <li><a href="#commercial">Can I include BusyBox as part of the software on my device?</a></li>
|
---|
19 | <li><a href="#external">Where can I find other small utilities since busybox does not include the features I want?</a></li></li>
|
---|
20 | <li><a href="#demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></li>
|
---|
21 | <li><a href="#helpme">I need help with BusyBox! What should I do?</a></li>
|
---|
22 | <li><a href="#contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></li>
|
---|
23 | </ol>
|
---|
24 |
|
---|
25 | <h2>Troubleshooting</h2>
|
---|
26 | <ol>
|
---|
27 | <li><a href="#bugs">I think I found a bug in BusyBox! What should I do?!</a></li>
|
---|
28 | <li><a href="#backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</a></li>
|
---|
29 | <li><a href="#init">Busybox init isn't working!</a></li>
|
---|
30 | <li><a href="#sed">I can't configure busybox on my system.</a></li>
|
---|
31 | <li><a href="#job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></li>
|
---|
32 | </ol>
|
---|
33 |
|
---|
34 | <h2>Misc. questions</h2>
|
---|
35 | <ol>
|
---|
36 | <li><a href="#tz">How do I change the time zone in busybox?</a></li>
|
---|
37 | </ol>
|
---|
38 |
|
---|
39 | <h2>Programming questions</h2>
|
---|
40 | <ol>
|
---|
41 | <li><a href="#goals">What are the goals of busybox?</a></li>
|
---|
42 | <li><a href="#design">What is the design of busybox?</a></li>
|
---|
43 | <li><a href="#source">How is the source code organized?</a></li>
|
---|
44 | <ul>
|
---|
45 | <li><a href="#source_applets">The applet directories.</a></li>
|
---|
46 | <li><a href="#source_libbb">The busybox shared library (libbb)</a></li>
|
---|
47 | </ul>
|
---|
48 | <li><a href="#optimize">I want to make busybox even smaller, how do I go about it?</a></li>
|
---|
49 | <li><a href="#adding">Adding an applet to busybox</a></li>
|
---|
50 | <li><a href="#standards">What standards does busybox adhere to?</a></li>
|
---|
51 | <li><a href="#portability">Portability.</a></li>
|
---|
52 | <li><a href="#tips">Tips and tricks.</a></li>
|
---|
53 | <ul>
|
---|
54 | <li><a href="#tips_encrypted_passwords">Encrypted Passwords</a></li>
|
---|
55 | <li><a href="#tips_vfork">Fork and vfork</a></li>
|
---|
56 | <li><a href="#tips_short_read">Short reads and writes</a></li>
|
---|
57 | <li><a href="#tips_memory">Memory used by relocatable code, PIC, and static linking.</a></li>
|
---|
58 | <li><a href="#tips_kernel_headers">Including Linux kernel headers.</a></li>
|
---|
59 | </ul>
|
---|
60 | <li><a href="#who">Who are the BusyBox developers?</a></li>
|
---|
61 | </ul>
|
---|
62 | </ol>
|
---|
63 |
|
---|
64 |
|
---|
65 | <hr />
|
---|
66 | <h1>General questions</h1>
|
---|
67 |
|
---|
68 | <hr />
|
---|
69 | <h2><a name="getting_started">How can I get started using BusyBox?</a></h2>
|
---|
70 |
|
---|
71 | <p> If you just want to try out busybox without installing it, download the
|
---|
72 | tarball, extract it, run "make defconfig", and then run "make".
|
---|
73 | </p>
|
---|
74 | <p>
|
---|
75 | This will create a busybox binary with almost all features enabled. To try
|
---|
76 | out a busybox applet, type "./busybox [appletname] [options]", for
|
---|
77 | example "./busybox ls -l" or "./busybox cat LICENSE". Type "./busybox"
|
---|
78 | to see a command list, and "busybox appletname --help" to see a brief
|
---|
79 | usage message for a given applet.
|
---|
80 | </p>
|
---|
81 | <p>
|
---|
82 | BusyBox uses the name it was invoked under to determine which applet is
|
---|
83 | being invoked. (Try "mv busybox ls" and then "./ls -l".) Installing
|
---|
84 | busybox consists of creating symlinks (or hardlinks) to the busybox
|
---|
85 | binary for each applet in busybox, and making sure these links are in
|
---|
86 | the shell's command $PATH. The special applet name "busybox" (or with
|
---|
87 | any optional suffix, such as "busybox-static") uses the first argument
|
---|
88 | to determine which applet to run, as shown above.
|
---|
89 | </p>
|
---|
90 | <p>
|
---|
91 | BusyBox also has a feature called the
|
---|
92 | <a name="standalone_shell">"standalone shell"</a>, where the busybox
|
---|
93 | shell runs any built-in applets before checking the command path. This
|
---|
94 | feature is also enabled by "make allyesconfig", and to try it out run
|
---|
95 | the command line "PATH= ./busybox ash". This will blank your command path
|
---|
96 | and run busybox as your command shell, so the only commands it can find
|
---|
97 | (without an explicit path such as /bin/ls) are the built-in busybox ones.
|
---|
98 | This is another good way to see what's built into busybox.
|
---|
99 | Note that the standalone shell requires CONFIG_BUSYBOX_EXEC_PATH
|
---|
100 | to be set appropriately, depending on whether or not /proc/self/exe is
|
---|
101 | available or not. If you do not have /proc, then point that config option
|
---|
102 | to the location of your busybox binary, usually /bin/busybox.
|
---|
103 | (So if you set it to /proc/self/exe, and happen to be able to chroot into
|
---|
104 | your rootfs, you must mount /proc beforehand.)
|
---|
105 | </p>
|
---|
106 | <p>
|
---|
107 | A typical indication that you set CONFIG_BUSYBOX_EXEC_PATH to proc but
|
---|
108 | forgot to mount proc is:
|
---|
109 | <pre>
|
---|
110 | $ /bin/echo $PATH
|
---|
111 | /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/bin/X11
|
---|
112 | $ echo $PATH
|
---|
113 | /bin/sh: echo: not found
|
---|
114 | </pre>
|
---|
115 |
|
---|
116 | <hr />
|
---|
117 | <h2><a name="configure">How do I configure busybox?</a></h2>
|
---|
118 |
|
---|
119 | <p> Busybox is configured similarly to the linux kernel. Create a default
|
---|
120 | configuration and then run "make menuconfig" to modify it. The end
|
---|
121 | result is a .config file that tells the busybox build process what features
|
---|
122 | to include. So instead of "./configure; make; make install" the equivalent
|
---|
123 | busybox build would be "make defconfig; make; make install".
|
---|
124 | </p>
|
---|
125 |
|
---|
126 | <p> Busybox configured with all features enabled is a little under a megabyte
|
---|
127 | dynamically linked on x86. To create a smaller busybox, configure it with
|
---|
128 | fewer features. Individual busybox applets cost anywhere from a few
|
---|
129 | hundred bytes to tens of kilobytes. Disable unneeded applets to save,
|
---|
130 | space, using menuconfig.
|
---|
131 | </p>
|
---|
132 |
|
---|
133 | <p>The most important busybox configurators are:</p>
|
---|
134 |
|
---|
135 | <ul>
|
---|
136 | <li><p>make <b>defconfig</b> - Create the maximum "sane" configuration. This
|
---|
137 | enables almost all features, minus things like debugging options and features
|
---|
138 | that require changes to the rest of the system to work (such as selinux or
|
---|
139 | devfs device names). Use this if you want to start from a full-featured
|
---|
140 | busybox and remove features until it's small enough.</p></li>
|
---|
141 | <li><p>make <b>allnoconfig</b> - Disable everything. This creates a tiny version
|
---|
142 | of busybox that doesn't do anything. Start here if you know exactly what
|
---|
143 | you want and would like to select only those features.</p></li>
|
---|
144 | <li><p>make <b>menuconfig</b> - Interactively modify a .config file through a
|
---|
145 | multi-level menu interface. Use this after one of the previous two.</p></li>
|
---|
146 | </ul>
|
---|
147 |
|
---|
148 | <p>Some other configuration options are:</p>
|
---|
149 | <ul>
|
---|
150 | <li><p>make <b>oldconfig</b> - Update an old .config file for a newer version
|
---|
151 | of busybox.</p></li>
|
---|
152 | <li><p>make <b>allyesconfig</b> - Select absolutely everything. This creates
|
---|
153 | a statically linked version of busybox full of debug code, with dependencies on
|
---|
154 | selinux, using devfs names... This makes sure everything compiles. Whether
|
---|
155 | or not the result would do anything useful is an open question.</p></li>
|
---|
156 | <li><p>make <b>allbareconfig</b> - Select all applets but disable all sub-features
|
---|
157 | within each applet. More build coverage testing.</p></li>
|
---|
158 | <li><p>make <b>randconfig</b> - Create a random configuration for test purposes.</p></li>
|
---|
159 | </ul>
|
---|
160 |
|
---|
161 | <p> Menuconfig modifies your .config file through an interactive menu where you can enable or disable
|
---|
162 | busybox features, and get help about each feature.
|
---|
163 |
|
---|
164 | <p>
|
---|
165 | To build a smaller busybox binary, run "make menuconfig" and disable the
|
---|
166 | features you don't need. (Or run "make allnoconfig" and then use
|
---|
167 | menuconfig to add just the features you need. Don't forget to recompile
|
---|
168 | with "make" once you've finished configuring.)
|
---|
169 | </p>
|
---|
170 |
|
---|
171 | <hr />
|
---|
172 | <h2><a name="build">How do I build BusyBox with a cross-compiler?</a></h2>
|
---|
173 |
|
---|
174 | <p>
|
---|
175 | To build busybox with a cross-compiler, specify CROSS_COMPILE=<prefix>.
|
---|
176 | </p>
|
---|
177 | <p>
|
---|
178 | CROSS_COMPILE specifies the prefix used for all executables used
|
---|
179 | during compilation. Only gcc and related binutils executables
|
---|
180 | are prefixed with $(CROSS_COMPILE) in the makefiles.
|
---|
181 | CROSS_COMPILE can be set on the command line:
|
---|
182 | <pre>
|
---|
183 | make CROSS_COMPILE=arm-linux-uclibcgnueabi-
|
---|
184 | </pre>
|
---|
185 | Alternatively CROSS_COMPILE can be set in the environment.
|
---|
186 | Default value for CROSS_COMPILE is not to prefix executables.
|
---|
187 | </p>
|
---|
188 |
|
---|
189 | <hr />
|
---|
190 | <h2><a name="build_system">How do I build a BusyBox-based system?</a></h2>
|
---|
191 |
|
---|
192 | <p>
|
---|
193 | BusyBox is a package that replaces a dozen standard packages, but it is
|
---|
194 | not by itself a complete bootable system. Building an entire Linux
|
---|
195 | distribution from source is a bit beyond the scope of this FAQ, but it
|
---|
196 | understandably keeps cropping up on the mailing list, so here are some
|
---|
197 | pointers.
|
---|
198 | </p>
|
---|
199 | <p>
|
---|
200 | Start by learning how to strip a working system down to the bare essentials
|
---|
201 | needed to run one or two commands, so you know what it is you actually
|
---|
202 | need. An excellent practical place to do
|
---|
203 | this is the <a href="http://www.tldp.org/HOWTO/Bootdisk-HOWTO/">Linux
|
---|
204 | BootDisk Howto</a>, or for a more theoretical approach try
|
---|
205 | <a href="http://www.tldp.org/HOWTO/From-PowerUp-To-Bash-Prompt-HOWTO.html">From
|
---|
206 | PowerUp to Bash Prompt</a>.
|
---|
207 | </p>
|
---|
208 | <p>
|
---|
209 | To learn how to build a working Linux system entirely from source code,
|
---|
210 | the place to go is the <a href="http://www.linuxfromscratch.org">Linux
|
---|
211 | From Scratch</a> project. They have an entire book of step-by-step
|
---|
212 | instructions you can
|
---|
213 | <a href="http://www.linuxfromscratch.org/lfs/view/stable/">read online</a>
|
---|
214 | or
|
---|
215 | <a href="http://www.linuxfromscratch.org/lfs/downloads/stable/">download</a>.
|
---|
216 | Be sure to check out the other sections of their main page, including
|
---|
217 | Beyond Linux From Scratch, Hardened Linux From Scratch, their Hints
|
---|
218 | directory, and their LiveCD project. (They also have mailing lists which
|
---|
219 | are better sources of answers to Linux-system building questions than
|
---|
220 | the busybox list.)
|
---|
221 | </p>
|
---|
222 | <p>
|
---|
223 | If you want an automated yet customizable system builder which produces
|
---|
224 | a BusyBox and uClibc based system, try
|
---|
225 | <a href="http://buildroot.uclibc.org">buildroot</a>, which is
|
---|
226 | another project by the maintainer of the uClibc (Erik Andersen).
|
---|
227 | Download the tarball, extract it, unset CC, make.
|
---|
228 | For more instructions, see the website.
|
---|
229 | </p>
|
---|
230 |
|
---|
231 | <hr />
|
---|
232 | <h2><a name="kernel">Which Linux kernel versions are supported?</a></h2>
|
---|
233 |
|
---|
234 | <p>
|
---|
235 | Full functionality requires Linux 2.4.x or better. (Earlier versions may
|
---|
236 | still work, but are no longer regularly tested.) A large fraction of the
|
---|
237 | code should run on just about anything. While the current code is fairly
|
---|
238 | Linux specific, it should be fairly easy to port the majority of the code
|
---|
239 | to support, say, FreeBSD or Solaris, or Mac OS X, or even Windows (if you
|
---|
240 | are into that sort of thing).
|
---|
241 | </p>
|
---|
242 |
|
---|
243 | <hr />
|
---|
244 | <h2><a name="arch">Which architectures does BusyBox run on?</a></h2>
|
---|
245 |
|
---|
246 | <p>
|
---|
247 | BusyBox in general will build on any architecture supported by gcc.
|
---|
248 | Kernel module loading for 2.4 Linux kernels is currently
|
---|
249 | limited to ARM, CRIS, H8/300, x86, ia64, x86_64, m68k, MIPS, PowerPC,
|
---|
250 | S390, SH3/4/5, Sparc, v850e, and x86_64 for 2.4.x kernels.
|
---|
251 | </p>
|
---|
252 | <p>
|
---|
253 | With 2.6.x kernels, module loading support should work on all architectures.
|
---|
254 | </p>
|
---|
255 |
|
---|
256 | <hr />
|
---|
257 | <h2><a name="libc">Which C libraries are supported?</a></h2>
|
---|
258 |
|
---|
259 | <p>
|
---|
260 | On Linux, BusyBox releases are tested against uClibc (0.9.27 or later) and
|
---|
261 | glibc (2.2 or later). Both should provide full functionality with busybox,
|
---|
262 | and if you find a bug we want to hear about it.
|
---|
263 | </p>
|
---|
264 | <p>
|
---|
265 | Linux-libc5 is no longer maintained (and has no known advantages over
|
---|
266 | uClibc), dietlibc is known to have numerous unfixed bugs, and klibc is
|
---|
267 | missing too many features to build BusyBox. If you require a small C
|
---|
268 | library for Linux, the busybox developers recommend uClibc.
|
---|
269 | </p>
|
---|
270 | <p>
|
---|
271 | Some BusyBox applets have been built and run under a combination
|
---|
272 | of newlib and libgloss (see
|
---|
273 | <a href="http://www.busybox.net/lists/busybox/2005-March/013759.html">this thread</a>).
|
---|
274 | This is still experimental, but may be supported in a future release.
|
---|
275 | </p>
|
---|
276 |
|
---|
277 | <hr />
|
---|
278 | <h2><a name="commercial">Can I include BusyBox as part of the software on my device?</a></h2>
|
---|
279 |
|
---|
280 | <p>
|
---|
281 | Yes. As long as you <a href="http://busybox.net/license.html">fully comply
|
---|
282 | with the generous terms of the GPL BusyBox license</a> you can ship BusyBox
|
---|
283 | as part of the software on your device.
|
---|
284 | </p>
|
---|
285 |
|
---|
286 | <hr />
|
---|
287 | <h2><a name="external">Where can I find other small utilities since busybox
|
---|
288 | does not include the features i want?</a></h2>
|
---|
289 |
|
---|
290 | <p>
|
---|
291 | we maintain such a <a href="tinyutils.html">list</a> on this site!
|
---|
292 | </p>
|
---|
293 |
|
---|
294 | <hr />
|
---|
295 | <h2><a name="demanding">I demand that you to add <favorite feature> right now! How come you don't answer all my questions on the mailing list instantly? I demand that you help me with all of my problems <em>Right Now</em>!</a></h2>
|
---|
296 |
|
---|
297 | <p>
|
---|
298 | You have not paid us a single cent and yet you still have the product of
|
---|
299 | many years of our work. We are not your slaves! We work on BusyBox
|
---|
300 | because we find it useful and interesting. If you go off flaming us, we
|
---|
301 | will ignore you.
|
---|
302 |
|
---|
303 | <hr />
|
---|
304 | <h2><a name="helpme">I need help with BusyBox! What should I do?</a></h2>
|
---|
305 |
|
---|
306 | <p>
|
---|
307 | If you find that you need help with BusyBox, you can ask for help on the
|
---|
308 | BusyBox mailing list at busybox@busybox.net.</p>
|
---|
309 |
|
---|
310 | <p> In addition to the mailing list, Erik Andersen (andersee), Manuel Nova
|
---|
311 | (mjn3), Rob Landley (landley), Mike Frysinger (SpanKY), Bernhard Fischer
|
---|
312 | (blindvt), and other long-time BusyBox developers are known to hang out
|
---|
313 | on the uClibc IRC channel: #uclibc on irc.freenode.net. There is a
|
---|
314 | <a href="http://ibot.Rikers.org/%23uclibc/">web archive of
|
---|
315 | daily logs of the #uclibc IRC channel</a> going back to 2002.
|
---|
316 | </p>
|
---|
317 |
|
---|
318 | <p>
|
---|
319 | <b>Please do not send private email to Rob, Erik, Manuel, or the other
|
---|
320 | BusyBox contributors asking for private help unless you are planning on
|
---|
321 | paying for consulting services.</b>
|
---|
322 | </p>
|
---|
323 |
|
---|
324 | <p>
|
---|
325 | When we answer questions on the BusyBox mailing list, it helps everyone
|
---|
326 | since people with similar problems in the future will be able to get help
|
---|
327 | by searching the mailing list archives. Private help is reserved as a paid
|
---|
328 | service. If you need to use private communication, or if you are serious
|
---|
329 | about getting timely assistance with BusyBox, you should seriously consider
|
---|
330 | paying for consulting services.
|
---|
331 | </p>
|
---|
332 |
|
---|
333 | <hr />
|
---|
334 | <h2><a name="contracts">I need you to add <favorite feature>! Are the BusyBox developers willing to be paid in order to fix bugs or add in <favorite feature>? Are you willing to provide support contracts?</a></h2>
|
---|
335 |
|
---|
336 | <p>
|
---|
337 | Yes we are. The easy way to sponsor a new feature is to post an offer on
|
---|
338 | the mailing list to see who's interested. You can also email the project's
|
---|
339 | maintainer and ask them to recommend someone.
|
---|
340 | </p>
|
---|
341 |
|
---|
342 | <p> If you prefer to deal with an organization rather than an individual, Rob
|
---|
343 | Landley (the current BusyBox maintainer) works for
|
---|
344 | <a http://www.timesys.com>TimeSys</a>, and Eric Andersen (the previous
|
---|
345 | busybox maintainer and current uClibc maintainer) owns
|
---|
346 | <a href="http://codepoet-consulting.com/">CodePoet Consulting</a>. Both
|
---|
347 | companies offer support contracts and handle new development, and there
|
---|
348 | are plenty of other companies that do the same.
|
---|
349 | </p>
|
---|
350 |
|
---|
351 |
|
---|
352 | <hr />
|
---|
353 | <h1>Troubleshooting</h1>
|
---|
354 |
|
---|
355 | <hr />
|
---|
356 | <h2><a name="bugs">I think I found a bug in BusyBox! What should I do?</a></h2>
|
---|
357 |
|
---|
358 | <p>
|
---|
359 | If you simply need help with using or configuring BusyBox, please submit a
|
---|
360 | detailed description of your problem to the BusyBox mailing list at <a
|
---|
361 | href="mailto:busybox@busybox.net"> busybox@busybox.net</a>.
|
---|
362 | Please do not send email to individual developers asking
|
---|
363 | for private help unless you are planning on paying for consulting services.
|
---|
364 | When we answer questions on the BusyBox mailing list, it helps everyone,
|
---|
365 | while private answers help only you...
|
---|
366 | </p>
|
---|
367 |
|
---|
368 | <p>
|
---|
369 | Bug reports and new feature patches sometimes get lost when posted to the
|
---|
370 | mailing list, because the developers of BusyBox are busy people and have
|
---|
371 | only so much they can keep in their brains at a time. You can post a
|
---|
372 | polite reminder after 2-3 days without offending anybody. If that doesn't
|
---|
373 | result in a solution, please use the
|
---|
374 | <a href="http://bugs.busybox.net/">BusyBox Bug
|
---|
375 | and Patch Tracking System</a> to submit a detailed explanation and we'll
|
---|
376 | get to it as soon as we can.
|
---|
377 | </p>
|
---|
378 |
|
---|
379 | <p>
|
---|
380 | Note that bugs entered into the bug system without being mentioned on the
|
---|
381 | mailing list first may languish there for months before anyone even notices
|
---|
382 | them. We generally go through the bug system when preparing for new
|
---|
383 | development releases, to see what fell through the cracks while we were
|
---|
384 | off writing new features. (It's a fast/unreliable vs slow/reliable thing.
|
---|
385 | Saves retransits, but the latency sucks.)
|
---|
386 | </p>
|
---|
387 |
|
---|
388 | <hr />
|
---|
389 | <h2><a name="backporting">I'm using an ancient version from the dawn of time and something's broken. Can you backport fixes for free?</h2>
|
---|
390 |
|
---|
391 | <p>Variants of this one get asked a lot.</p>
|
---|
392 |
|
---|
393 | <p>The purpose of the BusyBox mailing list is to develop and improve BusyBox,
|
---|
394 | and we're happy to respond to our users' needs. But if you're coming to the
|
---|
395 | list for free tech support we're going to ask you to upgrade to a current
|
---|
396 | version before we try to diagnose your problem.</p>
|
---|
397 |
|
---|
398 | <p>If you're building BusyBox 0.50 with uClibc 0.9.19 and gcc 0.9.26 there's a
|
---|
399 | fairly large chance that whatever problem you're seeing has already been fixed.
|
---|
400 | To get that fix, all you have to do is upgrade to a newer version. If you
|
---|
401 | don't at least _try_ that, you're wasting our time.</p>
|
---|
402 |
|
---|
403 | <p>The volunteers are happy to fix any bugs you point out in the current
|
---|
404 | versions because doing so helps everybody and makes the project better. We
|
---|
405 | want to make the current version work for you. But diagnosing, debugging, and
|
---|
406 | backporting fixes to old versions isn't something we do for free, because it
|
---|
407 | doesn't help anybody but you. The cost of volunteer tech support is using a
|
---|
408 | reasonably current version of the project.</p>
|
---|
409 |
|
---|
410 | <p>If you don't want to upgrade, you have the complete source code and thus
|
---|
411 | the ability to fix it yourself, or hire a consultant to do it for you. If you
|
---|
412 | got your version from a vendor who still supports the older version, they can
|
---|
413 | help you. But there are limits as to what the volunteers will feel obliged to
|
---|
414 | do for you.</p>
|
---|
415 |
|
---|
416 | <p>As a rule of thumb, volunteers will generally answer polite questions about
|
---|
417 | a given version for about three years after its release before it's so old
|
---|
418 | we don't remember the answer off the top of our head. And if you want us to
|
---|
419 | put any _effort_ into tracking it down, we want you to put in a little effort
|
---|
420 | of your own by confirming it's still a problem with the current version. It's
|
---|
421 | also hard for us to fix a problem of yours if we can't reproduce it because
|
---|
422 | we don't have any systems running an environment that old.</p>
|
---|
423 |
|
---|
424 | <p>A consultant will happily set up a special environment just to reproduce
|
---|
425 | your problem, and you can always ask on the list if any of the developers
|
---|
426 | have consulting rates.</p>
|
---|
427 |
|
---|
428 | <hr />
|
---|
429 | <h2><a name="init">Busybox init isn't working!</a></h2>
|
---|
430 |
|
---|
431 | <p>
|
---|
432 | Init is the first program that runs, so it might be that no programs are
|
---|
433 | working on your new system because of a problem with your cross-compiler,
|
---|
434 | kernel, console settings, shared libraries, root filesystem... To rule all
|
---|
435 | that out, first build a statically linked version of the following "hello
|
---|
436 | world" program with your cross compiler toolchain:
|
---|
437 | </p>
|
---|
438 | <pre>
|
---|
439 | #include <stdio.h>
|
---|
440 |
|
---|
441 | int main(int argc, char *argv)
|
---|
442 | {
|
---|
443 | printf("Hello world!\n");
|
---|
444 | sleep(999999999);
|
---|
445 | }
|
---|
446 | </pre>
|
---|
447 |
|
---|
448 | <p>
|
---|
449 | Now try to boot your device with an "init=" argument pointing to your
|
---|
450 | hello world program. Did you see the hello world message? Until you
|
---|
451 | do, don't bother messing with busybox init.
|
---|
452 | </p>
|
---|
453 |
|
---|
454 | <p>
|
---|
455 | Once you've got it working statically linked, try getting it to work
|
---|
456 | dynamically linked. Then read the FAQ entry <a href="#build_system">How
|
---|
457 | do I build a BusyBox-based system?</a>, and the
|
---|
458 | <a href="/downloads/BusyBox.html#item_init">documentation for BusyBox
|
---|
459 | init</a>.
|
---|
460 | </p>
|
---|
461 |
|
---|
462 | <hr />
|
---|
463 | <h2><a name="sed">I can't configure busybox on my system.</a></h2>
|
---|
464 |
|
---|
465 | <p>
|
---|
466 | Configuring Busybox depends on a recent version of sed. Older
|
---|
467 | distributions (Red Hat 7.2, Debian 3.0) may not come with a
|
---|
468 | usable version. Luckily BusyBox can use its own sed to configure itself,
|
---|
469 | although this leads to a bit of a chicken and egg problem.
|
---|
470 | You can work around this by hand-configuring busybox to build with just
|
---|
471 | sed, then putting that sed in your path to configure the rest of busybox
|
---|
472 | with, like so:
|
---|
473 | </p>
|
---|
474 |
|
---|
475 | <pre>
|
---|
476 | tar xvjf sources/busybox-x.x.x.tar.bz2
|
---|
477 | cd busybox-x.x.x
|
---|
478 | make allnoconfig
|
---|
479 | make include/bb_config.h
|
---|
480 | echo "CONFIG_SED=y" >> .config
|
---|
481 | echo "#undef ENABLE_SED" >> include/bb_config.h
|
---|
482 | echo "#define ENABLE_SED 1" >> include/bb_config.h
|
---|
483 | make
|
---|
484 | mv busybox sed
|
---|
485 | export PATH=`pwd`:"$PATH"
|
---|
486 | </pre>
|
---|
487 |
|
---|
488 | <p>Then you can run "make defconfig" or "make menuconfig" normally.</p>
|
---|
489 |
|
---|
490 | <hr />
|
---|
491 | <h2><a name="job_control">Why do I keep getting "sh: can't access tty; job control turned off" errors? Why doesn't Control-C work within my shell?</a></h2>
|
---|
492 |
|
---|
493 | <p>
|
---|
494 | Job control will be turned off since your shell can not obtain a controlling
|
---|
495 | terminal. This typically happens when you run your shell on /dev/console.
|
---|
496 | The kernel will not provide a controlling terminal on the /dev/console
|
---|
497 | device. Your should run your shell on a normal tty such as tty1 or ttyS0
|
---|
498 | and everything will work perfectly. If you <em>REALLY</em> want your shell
|
---|
499 | to run on /dev/console, then you can hack your kernel (if you are into that
|
---|
500 | sortof thing) by changing drivers/char/tty_io.c to change the lines where
|
---|
501 | it sets "noctty = 1;" to instead set it to "0". I recommend you instead
|
---|
502 | run your shell on a real console...
|
---|
503 | </p>
|
---|
504 |
|
---|
505 | <hr />
|
---|
506 | <h1>Misc. questions</h1>
|
---|
507 |
|
---|
508 | <hr />
|
---|
509 | <h2><a name="tz">How do I change the time zone in busybox?</a></h2>
|
---|
510 |
|
---|
511 | <p>Busybox has nothing to do with the timezone. Please consult your libc
|
---|
512 | documentation. (<a href='http://google.com/search?q=uclibc+glibc+timezone'>http://google.com/search?q=uclibc+glibc+timezone</a>).</p>
|
---|
513 |
|
---|
514 | <hr />
|
---|
515 | <h1>Development</h1>
|
---|
516 |
|
---|
517 | <hr />
|
---|
518 | <h2><a name="goals">What are the goals of busybox?</a></h2>
|
---|
519 |
|
---|
520 | <p>Busybox aims to be the smallest and simplest correct implementation of the
|
---|
521 | standard Linux command line tools. First and foremost, this means the
|
---|
522 | smallest executable size we can manage. We also want to have the simplest
|
---|
523 | and cleanest implementation we can manage, be <a href="#standards">standards
|
---|
524 | compliant</a>, minimize run-time memory usage (heap and stack), run fast, and
|
---|
525 | take over the world.</p>
|
---|
526 |
|
---|
527 | <hr />
|
---|
528 | <h2><a name="design">What is the design of busybox?</a></h2>
|
---|
529 |
|
---|
530 | <p>Busybox is like a swiss army knife: one thing with many functions.
|
---|
531 | The busybox executable can act like many different programs depending on
|
---|
532 | the name used to invoke it. Normal practice is to create a bunch of symlinks
|
---|
533 | pointing to the busybox binary, each of which triggers a different busybox
|
---|
534 | function. (See <a href="FAQ.html#getting_started">getting started</a> in the
|
---|
535 | FAQ for more information on usage, and <a href="BusyBox.html">the
|
---|
536 | busybox documentation</a> for a list of symlink names and what they do.)
|
---|
537 |
|
---|
538 | <p>The "one binary to rule them all" approach is primarily for size reasons: a
|
---|
539 | single multi-purpose executable is smaller then many small files could be.
|
---|
540 | This way busybox only has one set of ELF headers, it can easily share code
|
---|
541 | between different apps even when statically linked, it has better packing
|
---|
542 | efficiency by avoding gaps between files or compression dictionary resets,
|
---|
543 | and so on.</p>
|
---|
544 |
|
---|
545 | <p>Work is underway on new options such as "make standalone" to build separate
|
---|
546 | binaries for each applet, and a "libbb.so" to make the busybox common code
|
---|
547 | available as a shared library. Neither is ready yet at the time of this
|
---|
548 | writing.</p>
|
---|
549 |
|
---|
550 | <a name="source"></a>
|
---|
551 |
|
---|
552 | <hr />
|
---|
553 | <h2><a name="source_applets">The applet directories</a></h2>
|
---|
554 |
|
---|
555 | <p>The directory "applets" contains the busybox startup code (applets.c and
|
---|
556 | busybox.c), and several subdirectories containing the code for the individual
|
---|
557 | applets.</p>
|
---|
558 |
|
---|
559 | <p>Busybox execution starts with the main() function in applets/busybox.c,
|
---|
560 | which sets the global variable applet_name to argv[0] and calls
|
---|
561 | run_applet_and_exit() in applets/applets.c. That uses the applets[] array
|
---|
562 | (defined in include/busybox.h and filled out in include/applets.h) to
|
---|
563 | transfer control to the appropriate APPLET_main() function (such as
|
---|
564 | cat_main() or sed_main()). The individual applet takes it from there.</p>
|
---|
565 |
|
---|
566 | <p>This is why calling busybox under a different name triggers different
|
---|
567 | functionality: main() looks up argv[0] in applets[] to get a function pointer
|
---|
568 | to APPLET_main().</p>
|
---|
569 |
|
---|
570 | <p>Busybox applets may also be invoked through the multiplexor applet
|
---|
571 | "busybox" (see busybox_main() in applets/busybox.c), and through the
|
---|
572 | standalone shell (grep for STANDALONE_SHELL in applets/shell/*.c).
|
---|
573 | See <a href="FAQ.html#getting_started">getting started</a> in the
|
---|
574 | FAQ for more information on these alternate usage mechanisms, which are
|
---|
575 | just different ways to reach the relevant APPLET_main() function.</p>
|
---|
576 |
|
---|
577 | <p>The applet subdirectories (archival, console-tools, coreutils,
|
---|
578 | debianutils, e2fsprogs, editors, findutils, init, loginutils, miscutils,
|
---|
579 | modutils, networking, procps, shell, sysklogd, and util-linux) correspond
|
---|
580 | to the configuration sub-menus in menuconfig. Each subdirectory contains the
|
---|
581 | code to implement the applets in that sub-menu, as well as a Config.in
|
---|
582 | file defining that configuration sub-menu (with dependencies and help text
|
---|
583 | for each applet), and the makefile segment (Makefile.in) for that
|
---|
584 | subdirectory.</p>
|
---|
585 |
|
---|
586 | <p>The run-time --help is stored in usage_messages[], which is initialized at
|
---|
587 | the start of applets/applets.c and gets its help text from usage.h. During the
|
---|
588 | build this help text is also used to generate the BusyBox documentation (in
|
---|
589 | html, txt, and man page formats) in the docs directory. See
|
---|
590 | <a href="#adding">adding an applet to busybox</a> for more
|
---|
591 | information.</p>
|
---|
592 |
|
---|
593 | <hr />
|
---|
594 | <h2><a name="source_libbb"><b>libbb</b></a></h2>
|
---|
595 |
|
---|
596 | <p>Most non-setup code shared between busybox applets lives in the libbb
|
---|
597 | directory. It's a mess that evolved over the years without much auditing
|
---|
598 | or cleanup. For anybody looking for a great project to break into busybox
|
---|
599 | development with, documenting libbb would be both incredibly useful and good
|
---|
600 | experience.</p>
|
---|
601 |
|
---|
602 | <p>Common themes in libbb include allocation functions that test
|
---|
603 | for failure and abort the program with an error message so the caller doesn't
|
---|
604 | have to test the return value (xmalloc(), xstrdup(), etc), wrapped versions
|
---|
605 | of open(), close(), read(), and write() that test for their own failures
|
---|
606 | and/or retry automatically, linked list management functions (llist.c),
|
---|
607 | command line argument parsing (getopt32.c), and a whole lot more.</p>
|
---|
608 |
|
---|
609 | <hr />
|
---|
610 | <h2><a name="optimize">I want to make busybox even smaller, how do I go about it?</a></h2>
|
---|
611 |
|
---|
612 | <p>
|
---|
613 | To conserve bytes it's good to know where they're being used, and the
|
---|
614 | size of the final executable isn't always a reliable indicator of
|
---|
615 | the size of the components (since various structures are rounded up,
|
---|
616 | so a small change may not even be visible by itself, but many small
|
---|
617 | savings add up).
|
---|
618 | </p>
|
---|
619 |
|
---|
620 | <p> The busybox Makefile builds two versions of busybox, one of which
|
---|
621 | (busybox_unstripped) has extra information that various analysis tools
|
---|
622 | can use. (This has nothing to do with CONFIG_DEBUG, leave that off
|
---|
623 | when trying to optimize for size.)
|
---|
624 | </p>
|
---|
625 |
|
---|
626 | <p> The <b>"make bloatcheck"</b> option uses Matt Mackall's bloat-o-meter
|
---|
627 | script to compare two versions of busybox (busybox_unstripped vs
|
---|
628 | busybox_old), and report which symbols changed size and by how much.
|
---|
629 | To use it, first build a base version with <b>"make baseline"</b>.
|
---|
630 | (This creates busybox_old, which should have the original sizes for
|
---|
631 | comparison purposes.) Then build the new version with your changes
|
---|
632 | and run "make bloatcheck" to see the size differences from the old
|
---|
633 | version.
|
---|
634 | </p>
|
---|
635 | <p>
|
---|
636 | The first line of output has totals: how many symbols were added or
|
---|
637 | removed, how many symbols grew or shrank, the number of bytes added
|
---|
638 | and number of bytes removed by these changes, and finally the total
|
---|
639 | number of bytes difference between the two files. The remaining
|
---|
640 | lines show each individual symbol, the old and new sizes, and the
|
---|
641 | increase or decrease in size (which results are sorted by).
|
---|
642 | </p>
|
---|
643 | <p>
|
---|
644 | The <b>"make sizes"</b> option produces raw symbol size information for
|
---|
645 | busybox_unstripped. This is the output from the "nm --size-sort"
|
---|
646 | command (see "man nm" for more information), and is the information
|
---|
647 | bloat-o-meter parses to produce the comparison report above. For
|
---|
648 | defconfig, this is a good way to find the largest symbols in the tree
|
---|
649 | (which is a good place to start when trying to shrink the code). To
|
---|
650 | take a closer look at individual applets, configure busybox with just
|
---|
651 | one applet (run "make allnoconfig" and then switch on a single applet
|
---|
652 | with menuconfig), and then use "make sizes" to see the size of that
|
---|
653 | applet's components.
|
---|
654 | </p>
|
---|
655 | <p>
|
---|
656 | The "showasm" command (in the scripts directory) produces an assembly
|
---|
657 | dump of a function, providing a closer look at what changed. Try
|
---|
658 | "scripts/showasm busybox_unstripped" to list available symbols, and
|
---|
659 | "scripts/showasm busybox_unstripped symbolname" to see the assembly
|
---|
660 | for a sepecific symbol.
|
---|
661 | </p>
|
---|
662 |
|
---|
663 | <hr />
|
---|
664 | <h2><a name="adding">Adding an applet to busybox</a></h2>
|
---|
665 |
|
---|
666 | <p>To add a new applet to busybox, first pick a name for the applet and
|
---|
667 | a corresponding CONFIG_NAME. Then do this:</p>
|
---|
668 |
|
---|
669 | <ul>
|
---|
670 | <li>Figure out where in the busybox source tree your applet best fits,
|
---|
671 | and put your source code there. Be sure to use APPLET_main() instead
|
---|
672 | of main(), where APPLET is the name of your applet.</li>
|
---|
673 |
|
---|
674 | <li>Add your applet to the relevant Config.in file (which file you add
|
---|
675 | it to determines where it shows up in "make menuconfig"). This uses
|
---|
676 | the same general format as the linux kernel's configuration system.</li>
|
---|
677 |
|
---|
678 | <li>Add your applet to the relevant Makefile.in file (in the same
|
---|
679 | directory as the Config.in you chose), using the existing entries as a
|
---|
680 | template and the same CONFIG symbol as you used for Config.in. (Don't
|
---|
681 | forget "needlibm" or "needcrypt" if your applet needs libm or
|
---|
682 | libcrypt.)</li>
|
---|
683 |
|
---|
684 | <li>Add your applet to "include/applets.h", using one of the existing
|
---|
685 | entries as a template. (Note: this is in alphabetical order. Applets
|
---|
686 | are found via binary search, and if you add an applet out of order it
|
---|
687 | won't work.)</li>
|
---|
688 |
|
---|
689 | <li>Add your applet's runtime help text to "include/usage.h". You need
|
---|
690 | at least appname_trivial_usage (the minimal help text, always included
|
---|
691 | in the busybox binary when this applet is enabled) and appname_full_usage
|
---|
692 | (extra help text included in the busybox binary with
|
---|
693 | CONFIG_FEATURE_VERBOSE_USAGE is enabled), or it won't compile.
|
---|
694 | The other two help entry types (appname_example_usage and
|
---|
695 | appname_notes_usage) are optional. They don't take up space in the binary,
|
---|
696 | but instead show up in the generated documentation (BusyBox.html,
|
---|
697 | BusyBox.txt, and the man page BusyBox.1).</li>
|
---|
698 |
|
---|
699 | <li>Run menuconfig, switch your applet on, compile, test, and fix the
|
---|
700 | bugs. Be sure to try both "allyesconfig" and "allnoconfig" (and
|
---|
701 | "allbareconfig" if relevant).</li>
|
---|
702 |
|
---|
703 | </ul>
|
---|
704 |
|
---|
705 | <hr />
|
---|
706 | <h2><a name="standards">What standards does busybox adhere to?</a></h2>
|
---|
707 |
|
---|
708 | <p>The standard we're paying attention to is the "Shell and Utilities"
|
---|
709 | portion of the <a href="http://www.opengroup.org/onlinepubs/009695399/">Open
|
---|
710 | Group Base Standards</a> (also known as the Single Unix Specification version
|
---|
711 | 3 or SUSv3). Note that paying attention isn't necessarily the same thing as
|
---|
712 | following it.</p>
|
---|
713 |
|
---|
714 | <p>SUSv3 doesn't even mention things like init, mount, tar, or losetup, nor
|
---|
715 | commonly used options like echo's '-e' and '-n', or sed's '-i'. Busybox is
|
---|
716 | driven by what real users actually need, not the fact the standard believes
|
---|
717 | we should implement ed or sccs. For size reasons, we're unlikely to include
|
---|
718 | much internationalization support beyond UTF-8, and on top of all that, our
|
---|
719 | configuration menu lets developers chop out features to produce smaller but
|
---|
720 | very non-standard utilities.</p>
|
---|
721 |
|
---|
722 | <p>Also, Busybox is aimed primarily at Linux. Unix standards are interesting
|
---|
723 | because Linux tries to adhere to them, but portability to dozens of platforms
|
---|
724 | is only interesting in terms of offering a restricted feature set that works
|
---|
725 | everywhere, not growing dozens of platform-specific extensions. Busybox
|
---|
726 | should be portable to all hardware platforms Linux supports, and any other
|
---|
727 | similar operating systems that are easy to do and won't require much
|
---|
728 | maintenance.</p>
|
---|
729 |
|
---|
730 | <p>In practice, standards compliance tends to be a clean-up step once an
|
---|
731 | applet is otherwise finished. When polishing and testing a busybox applet,
|
---|
732 | we ensure we have at least the option of full standards compliance, or else
|
---|
733 | document where we (intentionally) fall short.</p>
|
---|
734 |
|
---|
735 | <hr />
|
---|
736 | <h2><a name="portability">Portability.</a></h2>
|
---|
737 |
|
---|
738 | <p>Busybox is a Linux project, but that doesn't mean we don't have to worry
|
---|
739 | about portability. First of all, there are different hardware platforms,
|
---|
740 | different C library implementations, different versions of the kernel and
|
---|
741 | build toolchain... The file "include/platform.h" exists to centralize and
|
---|
742 | encapsulate various platform-specific things in one place, so most busybox
|
---|
743 | code doesn't have to care where it's running.</p>
|
---|
744 |
|
---|
745 | <p>To start with, Linux runs on dozens of hardware platforms. We try to test
|
---|
746 | each release on x86, x86-64, arm, power pc, and mips. (Since qemu can handle
|
---|
747 | all of these, this isn't that hard.) This means we have to care about a number
|
---|
748 | of portability issues like endianness, word size, and alignment, all of which
|
---|
749 | belong in platform.h. That header handles conditional #includes and gives
|
---|
750 | us macros we can use in the rest of our code. At some point in the future
|
---|
751 | we might grow a platform.c, possibly even a platform subdirectory. As long
|
---|
752 | as the applets themselves don't have to care.</p>
|
---|
753 |
|
---|
754 | <p>On a related note, we made the "default signedness of char varies" problem
|
---|
755 | go away by feeding the compiler -funsigned-char. This gives us consistent
|
---|
756 | behavior on all platforms, and defaults to 8-bit clean text processing (which
|
---|
757 | gets us halfway to UTF-8 support). NOMMU support is less easily separated
|
---|
758 | (see the tips section later in this document), but we're working on it.</p>
|
---|
759 |
|
---|
760 | <p>Another type of portability is build environments: we unapologetically use
|
---|
761 | a number of gcc and glibc extensions (as does the Linux kernel), but these have
|
---|
762 | been picked up by packages like uClibc, TCC, and Intel's C Compiler. As for
|
---|
763 | gcc, we take advantage of newer compiler optimizations to get the smallest
|
---|
764 | possible size, but we also regression test against an older build environment
|
---|
765 | using the Red Hat 9 image at "http://busybox.net/downloads/qemu". This has a
|
---|
766 | 2.4 kernel, gcc 3.2, make 3.79.1, and glibc 2.3, and is the oldest
|
---|
767 | build/deployment environment we still put any effort into maintaining. (If
|
---|
768 | anyone takes an interest in older kernels you're welcome to submit patches,
|
---|
769 | but the effort would probably be better spent
|
---|
770 | <a href="http://www.selenic.com/linux-tiny/">trimming
|
---|
771 | down the 2.6 kernel</a>.) Older gcc versions than that are uninteresting since
|
---|
772 | we now use c99 features, although
|
---|
773 | <a href="http://fabrice.bellard.free.fr/tcc/">tcc</a> might be worth a
|
---|
774 | look.</p>
|
---|
775 |
|
---|
776 | <p>We also test busybox against the current release of uClibc. Older versions
|
---|
777 | of uClibc aren't very interesting (they were buggy, and uClibc wasn't really
|
---|
778 | usable as a general-purpose C library before version 0.9.26 anyway).</p>
|
---|
779 |
|
---|
780 | <p>Other unix implementations are mostly uninteresting, since Linux binaries
|
---|
781 | have become the new standard for portable Unix programs. Specifically,
|
---|
782 | the ubiquity of Linux was cited as the main reason the Intel Binary
|
---|
783 | Compatability Standard 2 died, by the standards group organized to name a
|
---|
784 | successor to ibcs2: <a href="http://www.telly.org/86open/">the 86open
|
---|
785 | project</a>. That project disbanded in 1999 with the endorsement of an
|
---|
786 | existing standard: Linux ELF binaries. Since then, the major players at the
|
---|
787 | time (such as <a
|
---|
788 | href=http://www-03.ibm.com/servers/aix/products/aixos/linux/index.html>AIX</a>, <a
|
---|
789 | href=http://www.sun.com/software/solaris/ds/linux_interop.jsp#3>Solaris</a>, and
|
---|
790 | <a href=http://www.onlamp.com/pub/a/bsd/2000/03/17/linuxapps.html>FreeBSD</a>)
|
---|
791 | have all either grown Linux support or folded.</p>
|
---|
792 |
|
---|
793 | <p>The major exceptions are newcomer MacOS X, some embedded environments
|
---|
794 | (such as newlib+libgloss) which provide a posix environment but not a full
|
---|
795 | Linux environment, and environments like Cygwin that provide only partial Linux
|
---|
796 | emulation. Also, some embedded Linux systems run a Linux kernel but amputate
|
---|
797 | things like the /proc directory to save space.</p>
|
---|
798 |
|
---|
799 | <p>Supporting these systems is largely a question of providing a clean subset
|
---|
800 | of BusyBox's functionality -- whichever applets can easily be made to
|
---|
801 | work in that environment. Annotating the configuration system to
|
---|
802 | indicate which applets require which prerequisites (such as procfs) is
|
---|
803 | also welcome. Other efforts to support these systems (swapping #include
|
---|
804 | files to build in different environments, adding adapter code to platform.h,
|
---|
805 | adding more extensive special-case supporting infrastructure such as mount's
|
---|
806 | legacy mtab support) are handled on a case-by-case basis. Support that can be
|
---|
807 | cleanly hidden in platform.h is reasonably attractive, and failing that
|
---|
808 | support that can be cleanly separated into a separate conditionally compiled
|
---|
809 | file is at least worth a look. Special-case code in the body of an applet is
|
---|
810 | something we're trying to avoid.</p>
|
---|
811 |
|
---|
812 | <hr />
|
---|
813 | <h2><a name="tips" />Programming tips and tricks.</a></h2>
|
---|
814 |
|
---|
815 | <p>Various things busybox uses that aren't particularly well documented
|
---|
816 | elsewhere.</p>
|
---|
817 |
|
---|
818 | <hr />
|
---|
819 | <h2><a name="tips_encrypted_passwords">Encrypted Passwords</a></h2>
|
---|
820 |
|
---|
821 | <p>Password fields in /etc/passwd and /etc/shadow are in a special format.
|
---|
822 | If the first character isn't '$', then it's an old DES style password. If
|
---|
823 | the first character is '$' then the password is actually three fields
|
---|
824 | separated by '$' characters:</p>
|
---|
825 | <pre>
|
---|
826 | <b>$type$salt$encrypted_password</b>
|
---|
827 | </pre>
|
---|
828 |
|
---|
829 | <p>The "type" indicates which encryption algorithm to use: 1 for MD5 and 2 for SHA1.</p>
|
---|
830 |
|
---|
831 | <p>The "salt" is a bunch of ramdom characters (generally 8) the encryption
|
---|
832 | algorithm uses to perturb the password in a known and reproducible way (such
|
---|
833 | as by appending the random data to the unencrypted password, or combining
|
---|
834 | them with exclusive or). Salt is randomly generated when setting a password,
|
---|
835 | and then the same salt value is re-used when checking the password. (Salt is
|
---|
836 | thus stored unencrypted.)</p>
|
---|
837 |
|
---|
838 | <p>The advantage of using salt is that the same cleartext password encrypted
|
---|
839 | with a different salt value produces a different encrypted value.
|
---|
840 | If each encrypted password uses a different salt value, an attacker is forced
|
---|
841 | to do the cryptographic math all over again for each password they want to
|
---|
842 | check. Without salt, they could simply produce a big dictionary of commonly
|
---|
843 | used passwords ahead of time, and look up each password in a stolen password
|
---|
844 | file to see if it's a known value. (Even if there are billions of possible
|
---|
845 | passwords in the dictionary, checking each one is just a binary search against
|
---|
846 | a file only a few gigabytes long.) With salt they can't even tell if two
|
---|
847 | different users share the same password without guessing what that password
|
---|
848 | is and decrypting it. They also can't precompute the attack dictionary for
|
---|
849 | a specific password until they know what the salt value is.</p>
|
---|
850 |
|
---|
851 | <p>The third field is the encrypted password (plus the salt). For md5 this
|
---|
852 | is 22 bytes.</p>
|
---|
853 |
|
---|
854 | <p>The busybox function to handle all this is pw_encrypt(clear, salt) in
|
---|
855 | "libbb/pw_encrypt.c". The first argument is the clear text password to be
|
---|
856 | encrypted, and the second is a string in "$type$salt$password" format, from
|
---|
857 | which the "type" and "salt" fields will be extracted to produce an encrypted
|
---|
858 | value. (Only the first two fields are needed, the third $ is equivalent to
|
---|
859 | the end of the string.) The return value is an encrypted password in
|
---|
860 | /etc/passwd format, with all three $ separated fields. It's stored in
|
---|
861 | a static buffer, 128 bytes long.</p>
|
---|
862 |
|
---|
863 | <p>So when checking an existing password, if pw_encrypt(text,
|
---|
864 | old_encrypted_password) returns a string that compares identical to
|
---|
865 | old_encrypted_password, you've got the right password. When setting a new
|
---|
866 | password, generate a random 8 character salt string, put it in the right
|
---|
867 | format with sprintf(buffer, "$%c$%s", type, salt), and feed buffer as the
|
---|
868 | second argument to pw_encrypt(text,buffer).</p>
|
---|
869 |
|
---|
870 | <hr />
|
---|
871 | <h2><a name="tips_vfork">Fork and vfork</a></h2>
|
---|
872 |
|
---|
873 | <p>On systems that haven't got a Memory Management Unit, fork() is unreasonably
|
---|
874 | expensive to implement (and sometimes even impossible), so a less capable
|
---|
875 | function called vfork() is used instead. (Using vfork() on a system with an
|
---|
876 | MMU is like pounding a nail with a wrench. Not the best tool for the job, but
|
---|
877 | it works.)</p>
|
---|
878 |
|
---|
879 | <p>Busybox hides the difference between fork() and vfork() in
|
---|
880 | libbb/bb_fork_exec.c. If you ever want to fork and exec, use bb_fork_exec()
|
---|
881 | (which returns a pid and takes the same arguments as execve(), although in
|
---|
882 | this case envp can be NULL) and don't worry about it. This description is
|
---|
883 | here in case you want to know why that does what it does.</p>
|
---|
884 |
|
---|
885 | <p>Implementing fork() depends on having a Memory Management Unit. With an
|
---|
886 | MMU then you can simply set up a second set of page tables and share the
|
---|
887 | physical memory via copy-on-write. So a fork() followed quickly by exec()
|
---|
888 | only copies a few pages of the parent's memory, just the ones it changes
|
---|
889 | before freeing them.</p>
|
---|
890 |
|
---|
891 | <p>With a very primitive MMU (using a base pointer plus length instead of page
|
---|
892 | tables, which can provide virtual addresses and protect processes from each
|
---|
893 | other, but no copy on write) you can still implement fork. But it's
|
---|
894 | unreasonably expensive, because you have to copy all the parent process'
|
---|
895 | memory into the new process (which could easily be several megabytes per fork).
|
---|
896 | And you have to do this even though that memory gets freed again as soon as the
|
---|
897 | exec happens. (This is not just slow and a waste of space but causes memory
|
---|
898 | usage spikes that can easily cause the system to run out of memory.)</p>
|
---|
899 |
|
---|
900 | <p>Without even a primitive MMU, you have no virtual addresses. Every process
|
---|
901 | can reach out and touch any other process' memory, because all pointers are to
|
---|
902 | physical addresses with no protection. Even if you copy a process' memory to
|
---|
903 | new physical addresses, all of its pointers point to the old objects in the
|
---|
904 | old process. (Searching through the new copy's memory for pointers and
|
---|
905 | redirect them to the new locations is not an easy problem.)</p>
|
---|
906 |
|
---|
907 | <p>So with a primitive or missing MMU, fork() is just not a good idea.</p>
|
---|
908 |
|
---|
909 | <p>In theory, vfork() is just a fork() that writeably shares the heap and stack
|
---|
910 | rather than copying it (so what one process writes the other one sees). In
|
---|
911 | practice, vfork() has to suspend the parent process until the child does exec,
|
---|
912 | at which point the parent wakes up and resumes by returning from the call to
|
---|
913 | vfork(). All modern kernel/libc combinations implement vfork() to put the
|
---|
914 | parent to sleep until the child does its exec. There's just no other way to
|
---|
915 | make it work: the parent has to know the child has done its exec() or exit()
|
---|
916 | before it's safe to return from the function it's in, so it has to block
|
---|
917 | until that happens. In fact without suspending the parent there's no way to
|
---|
918 | even store separate copies of the return value (the pid) from the vfork() call
|
---|
919 | itself: both assignments write into the same memory location.</p>
|
---|
920 |
|
---|
921 | <p>One way to understand (and in fact implement) vfork() is this: imagine
|
---|
922 | the parent does a setjmp and then continues on (pretending to be the child)
|
---|
923 | until the exec() comes around, then the _exec_ does the actual fork, and the
|
---|
924 | parent does a longjmp back to the original vfork call and continues on from
|
---|
925 | there. (It thus becomes obvious why the child can't return, or modify
|
---|
926 | local variables it doesn't want the parent to see changed when it resumes.)
|
---|
927 |
|
---|
928 | <p>Note a common mistake: the need for vfork doesn't mean you can't have two
|
---|
929 | processes running at the same time. It means you can't have two processes
|
---|
930 | sharing the same memory without stomping all over each other. As soon as
|
---|
931 | the child calls exec(), the parent resumes.</p>
|
---|
932 |
|
---|
933 | <p>If the child's attempt to call exec() fails, the child should call _exit()
|
---|
934 | rather than a normal exit(). This avoids any atexit() code that might confuse
|
---|
935 | the parent. (The parent should never call _exit(), only a vforked child that
|
---|
936 | failed to exec.)</p>
|
---|
937 |
|
---|
938 | <p>(Now in theory, a nommu system could just copy the _stack_ when it forks
|
---|
939 | (which presumably is much shorter than the heap), and leave the heap shared.
|
---|
940 | Even with no MMU at all
|
---|
941 | In practice, you've just wound up in a multi-threaded situation and you can't
|
---|
942 | do a malloc() or free() on your heap without freeing the other process' memory
|
---|
943 | (and if you don't have the proper locking for being threaded, corrupting the
|
---|
944 | heap if both of you try to do it at the same time and wind up stomping on
|
---|
945 | each other while traversing the free memory lists). The thing about vfork is
|
---|
946 | that it's a big red flag warning "there be dragons here" rather than
|
---|
947 | something subtle and thus even more dangerous.)</p>
|
---|
948 |
|
---|
949 | <hr />
|
---|
950 | <h2><a name="tips_sort_read">Short reads and writes</a></h2>
|
---|
951 |
|
---|
952 | <p>Busybox has special functions, bb_full_read() and bb_full_write(), to
|
---|
953 | check that all the data we asked for got read or written. Is this a real
|
---|
954 | world consideration? Try the following:</p>
|
---|
955 |
|
---|
956 | <pre>while true; do echo hello; sleep 1; done | tee out.txt</pre>
|
---|
957 |
|
---|
958 | <p>If tee is implemented with bb_full_read(), tee doesn't display output
|
---|
959 | in real time but blocks until its entire input buffer (generally a couple
|
---|
960 | kilobytes) is read, then displays it all at once. In that case, we _want_
|
---|
961 | the short read, for user interface reasons. (Note that read() should never
|
---|
962 | return 0 unless it has hit the end of input, and an attempt to write 0
|
---|
963 | bytes should be ignored by the OS.)</p>
|
---|
964 |
|
---|
965 | <p>As for short writes, play around with two processes piping data to each
|
---|
966 | other on the command line (cat bigfile | gzip > out.gz) and suspend and
|
---|
967 | resume a few times (ctrl-z to suspend, "fg" to resume). The writer can
|
---|
968 | experience short writes, which are especially dangerous because if you don't
|
---|
969 | notice them you'll discard data. They can also happen when a system is under
|
---|
970 | load and a fast process is piping to a slower one. (Such as an xterm waiting
|
---|
971 | on x11 when the scheduler decides X is being a CPU hog with all that
|
---|
972 | text console scrolling...)</p>
|
---|
973 |
|
---|
974 | <p>So will data always be read from the far end of a pipe at the
|
---|
975 | same chunk sizes it was written in? Nope. Don't rely on that. For one
|
---|
976 | counterexample, see <a href="http://www.faqs.org/rfcs/rfc896.html">rfc 896
|
---|
977 | for Nagle's algorithm</a>, which waits a fraction of a second or so before
|
---|
978 | sending out small amounts of data through a TCP/IP connection in case more
|
---|
979 | data comes in that can be merged into the same packet. (In case you were
|
---|
980 | wondering why action games that use TCP/IP set TCP_NODELAY to lower the latency
|
---|
981 | on their their sockets, now you know.)</p>
|
---|
982 |
|
---|
983 | <hr />
|
---|
984 | <h2><a name="tips_memory">Memory used by relocatable code, PIC, and static linking.</a></h2>
|
---|
985 |
|
---|
986 | <p>The downside of standard dynamic linking is that it results in self-modifying
|
---|
987 | code. Although each executable's pages are mmaped() into a process' address
|
---|
988 | space from the executable file and are thus naturally shared between processes
|
---|
989 | out of the page cache, the library loader (ld-linux.so.2 or ld-uClibc.so.0)
|
---|
990 | writes to these pages to supply addresses for relocatable symbols. This
|
---|
991 | dirties the pages, triggering copy-on-write allocation of new memory for each
|
---|
992 | processes' dirtied pages.</p>
|
---|
993 |
|
---|
994 | <p>One solution to this is Position Independent Code (PIC), a way of linking
|
---|
995 | a file so all the relocations are grouped together. This dirties fewer
|
---|
996 | pages (often just a single page) for each process' relocations. The down
|
---|
997 | side is this results in larger executables, which take up more space on disk
|
---|
998 | (and a correspondingly larger space in memory). But when many copies of the
|
---|
999 | same program are running, PIC dynamic linking trades a larger disk footprint
|
---|
1000 | for a smaller memory footprint, by sharing more pages.</p>
|
---|
1001 |
|
---|
1002 | <p>A third solution is static linking. A statically linked program has no
|
---|
1003 | relocations, and thus the entire executable is shared between all running
|
---|
1004 | instances. This tends to have a significantly larger disk footprint, but
|
---|
1005 | on a system with only one or two executables, shared libraries aren't much
|
---|
1006 | of a win anyway.</p>
|
---|
1007 |
|
---|
1008 | <p>You can tell the glibc linker to display debugging information about its
|
---|
1009 | relocations with the environment variable "LD_DEBUG". Try
|
---|
1010 | "LD_DEBUG=help /bin/true" for a list of commands. Learning to interpret
|
---|
1011 | "LD_DEBUG=statistics cat /proc/self/statm" could be interesting.</p>
|
---|
1012 |
|
---|
1013 | <p>For more on this topic, here's Rich Felker:</p>
|
---|
1014 | <blockquote>
|
---|
1015 | <p>Dynamic linking (without fixed load addresses) fundamentally requires
|
---|
1016 | at least one dirty page per dso that uses symbols. Making calls (but
|
---|
1017 | never taking the address explicitly) to functions within the same dso
|
---|
1018 | does not require a dirty page by itself, but will with ELF unless you
|
---|
1019 | use -Bsymbolic or hidden symbols when linking.</p>
|
---|
1020 |
|
---|
1021 | <p>ELF uses significant additional stack space for the kernel to pass all
|
---|
1022 | the ELF data structures to the newly created process image. These are
|
---|
1023 | located above the argument list and environment. This normally adds 1
|
---|
1024 | dirty page to the process size.</p>
|
---|
1025 |
|
---|
1026 | <p>The ELF dynamic linker has its own data segment, adding one or more
|
---|
1027 | dirty pages. I believe it also performs relocations on itself.</p>
|
---|
1028 |
|
---|
1029 | <p>The ELF dynamic linker makes significant dynamic allocations to manage
|
---|
1030 | the global symbol table and the loaded dso's. This data is never
|
---|
1031 | freed. It will be needed again if libdl is used, so unconditionally
|
---|
1032 | freeing it is not possible, but normal programs do not use libdl. Of
|
---|
1033 | course with glibc all programs use libdl (due to nsswitch) so the
|
---|
1034 | issue was never addressed.</p>
|
---|
1035 |
|
---|
1036 | <p>ELF also has the issue that segments are not page-aligned on disk.
|
---|
1037 | This saves up to 4k on disk, but at the expense of using an additional
|
---|
1038 | dirty page in most cases, due to a large portion of the first data
|
---|
1039 | page being filled with a duplicate copy of the last text page.</p>
|
---|
1040 |
|
---|
1041 | <p>The above is just a partial list of the tiny memory penalties of ELF
|
---|
1042 | dynamic linking, which eventually add up to quite a bit. The smallest
|
---|
1043 | I've been able to get a process down to is 8 dirty pages, and the
|
---|
1044 | above factors seem to mostly account for it (but some were difficult
|
---|
1045 | to measure).</p>
|
---|
1046 | </blockquote>
|
---|
1047 |
|
---|
1048 | <hr />
|
---|
1049 | <h2><a name="tips_kernel_headers"></a>Including kernel headers</h2>
|
---|
1050 |
|
---|
1051 | <p>The "linux" or "asm" directories of /usr/include contain Linux kernel
|
---|
1052 | headers, so that the C library can talk directly to the Linux kernel. In
|
---|
1053 | a perfect world, applications shouldn't include these headers directly, but
|
---|
1054 | we don't live in a perfect world.</p>
|
---|
1055 |
|
---|
1056 | <p>For example, Busybox's losetup code wants linux/loop.c because nothing else
|
---|
1057 | #defines the structures to call the kernel's loopback device setup ioctls.
|
---|
1058 | Attempts to cut and paste the information into a local busybox header file
|
---|
1059 | proved incredibly painful, because portions of the loop_info structure vary by
|
---|
1060 | architecture, namely the type __kernel_dev_t has different sizes on alpha,
|
---|
1061 | arm, x86, and so on. Meaning we either #include <linux/posix_types.h> or
|
---|
1062 | we hardwire #ifdefs to check what platform we're building on and define this
|
---|
1063 | type appropriately for every single hardware architecture supported by
|
---|
1064 | Linux, which is simply unworkable.</p>
|
---|
1065 |
|
---|
1066 | <p>This is aside from the fact that the relevant type defined in
|
---|
1067 | posix_types.h was renamed to __kernel_old_dev_t during the 2.5 series, so
|
---|
1068 | to cut and paste the structure into our header we have to #include
|
---|
1069 | <linux/version.h> to figure out which name to use. (What we actually do is
|
---|
1070 | check if we're building on 2.6, and if so just use the new 64 bit structure
|
---|
1071 | instead to avoid the rename entirely.) But we still need the version
|
---|
1072 | check, since 2.4 didn't have the 64 bit structure.</p>
|
---|
1073 |
|
---|
1074 | <p>The BusyBox developers spent <u>two years</u> trying to figure
|
---|
1075 | out a clean way to do all this. There isn't one. The losetup in the
|
---|
1076 | util-linux package from kernel.org isn't doing it cleanly either, they just
|
---|
1077 | hide the ugliness by nesting #include files. Their mount/loop.h
|
---|
1078 | #includes "my_dev_t.h", which #includes <linux/posix_types.h> and
|
---|
1079 | <linux/version.h> just like we do. There simply is no alternative.</p>
|
---|
1080 |
|
---|
1081 | <p>Just because directly #including kernel headers is sometimes
|
---|
1082 | unavoidable doesn't me we should include them when there's a better
|
---|
1083 | way to do it. However, block copying information out of the kernel headers
|
---|
1084 | is not a better way.</p>
|
---|
1085 |
|
---|
1086 | <hr />
|
---|
1087 | <h2><a name="who">Who are the BusyBox developers?</a></h2>
|
---|
1088 |
|
---|
1089 | <p>The following login accounts currently exist on busybox.net. (I.E. these
|
---|
1090 | people can commit <a href="http://busybox.net/downloads/patches">patches</a>
|
---|
1091 | into subversion for the BusyBox, uClibc, and buildroot projects.)</p>
|
---|
1092 |
|
---|
1093 | <pre>
|
---|
1094 | aldot :Bernhard Fischer
|
---|
1095 | andersen :Erik Andersen - uClibc and BuildRoot maintainer.
|
---|
1096 | bug1 :Glenn McGrath
|
---|
1097 | davidm :David McCullough
|
---|
1098 | gkajmowi :Garrett Kajmowicz - uClibc++ maintainer
|
---|
1099 | jbglaw :Jan-Benedict Glaw
|
---|
1100 | jocke :Joakim Tjernlund
|
---|
1101 | landley :Rob Landley - BusyBox maintainer
|
---|
1102 | lethal :Paul Mundt
|
---|
1103 | mjn3 :Manuel Novoa III
|
---|
1104 | osuadmin :osuadmin
|
---|
1105 | pgf :Paul Fox
|
---|
1106 | pkj :Peter Kjellerstedt
|
---|
1107 | prpplague :David Anders
|
---|
1108 | psm :Peter S. Mazinger
|
---|
1109 | russ :Russ Dill
|
---|
1110 | sandman :Robert Griebl
|
---|
1111 | sjhill :Steven J. Hill
|
---|
1112 | solar :Ned Ludd
|
---|
1113 | timr :Tim Riker
|
---|
1114 | tobiasa :Tobias Anderberg
|
---|
1115 | vapier :Mike Frysinger
|
---|
1116 | </pre>
|
---|
1117 |
|
---|
1118 | <p>The following accounts used to exist on busybox.net, but don't anymore so
|
---|
1119 | I can't ask /etc/passwd for their names. Rob Wentworth <robwen@gmail.com>
|
---|
1120 | asked Google and recovered the names:</p>
|
---|
1121 |
|
---|
1122 | <pre>
|
---|
1123 | aaronl :Aaron Lehmann
|
---|
1124 | beppu :John Beppu
|
---|
1125 | dwhedon :David Whedon
|
---|
1126 | erik :Erik Andersen
|
---|
1127 | gfeldman :Gennady Feldman
|
---|
1128 | jimg :Jim Gleason
|
---|
1129 | kraai :Matt Kraai
|
---|
1130 | markw :Mark Whitley
|
---|
1131 | miles :Miles Bader
|
---|
1132 | proski :Pavel Roskin
|
---|
1133 | rjune :Richard June
|
---|
1134 | tausq :Randolph Chung
|
---|
1135 | vodz :Vladimir N. Oleynik
|
---|
1136 | </pre>
|
---|
1137 |
|
---|
1138 |
|
---|
1139 | <br>
|
---|
1140 | <br>
|
---|
1141 | <br>
|
---|
1142 |
|
---|
1143 | <!--#include file="footer.html" -->
|
---|