The Pocket Linux Guide is for anyone interested in learning the techniques of building a GNU/Linux system from source code. The guide is structured as a project that builds a small diskette-based GNU/Linux system called Pocket Linux. Each chapter explores a small piece of the overall system explaining how it works, why it is needed and how to build it. After completing the Pocket Linux project, readers should possess an enhanced knowledge of what makes GNU/Linux systems work as well as the confidence to explore larger, more complex source-code-only projects.
This document, Pocket Linux Guide, is copyright (c) 2003 - 2005 by David Horton. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is available at the end of this document.
Linux is a registered trademark of Linus Torvalds.
This documentation is provided as-is with no warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. Use the concepts, examples and information at your own risk. The author(s) do not take any responsibility for damages that may arise from the use of this document.
All copyrights are held by their respective owners, unless specifically noted otherwise. Use of a term in this document should not be regarded as affecting the validity of any trademark or service mark. Naming of particular products or brands should not be seen as endorsements.
The Pocket Linux Guide demonstrates how to build a small console-based GNU/Linux system using only source code and a couple of diskettes. It is intended for Linux users who would like to gain a deeper understanding about how their system works beneath the shroud of distribution specific features and tools.
This guide is intended for intermediate to advanced Linux users. It is not intentionally obscure, but certain assumptions about the readers skill level are made. Success with this guide depends in part on being able to perform the following tasks:
The Pocket Linux Guide takes a hands-on approach to learning. The guide is written with each chapter building a piece of an overall project. Chapters are further broken into sections of Analysis, Design, Construction and Implementation. This format is derived from Rapid Application Development (RAD) methodology. Without going into detail about design methodologies, the sections may be summed up as follows.
Readers interested in learning more about RAD may want to consult a textbook covering systems analysis and design or visit the following University of California, Davis website on the subject: http://sysdev.ucdavis.edu/WEBADM/document/rad-stages.htm.
Readers are encouraged to visit the Pocket Linux Resource Site at http://pocket-linux.sourceforge.net/. The resource site is home to:
For technical questions about Pocket Linux please use the mailing list or the troubleshooting forum on the resource site. General comments and suggestions may be sent to the mailing list or emailed to the author directly.
In the early 90's GNU/Linux systems consisted of little more than a beta-quality Linux kernel and a small collection of software ported from the GNU project. It was a true hacker's operating system. There were no CD-ROM's or GUI installation tools; everything had to be compiled and configured by the end user. Being a Linux Expert meant knowing your system inside and out.
Toward the middle of the decade several GNU/Linux distributions began appearing. One of the first was Slackware in 1993 and since then there have been many others. Even though there are many "flavors" of Linux today, the main purpose of the distribution remains the same. The distribution automates many of the tasks involved in GNU/Linux installation and configuration taking the burden off of the system administrator. Being a Linux Expert now means knowing which button to click in the GUI administration tool.
Recently there has been a yearn for a return to the "good old days" of Linux when men were men, sysadmins were hardcore geeks and everything was compiled from source code. A notable indication of this movement was the publication of the Linux-From-Scratch-HOWTO version 1.0 by Gerard Beekmans in 1999. Being a Linux Expert once again means knowing how to do it yourself.
For more historical information, see Ragib Hasan's "History of Linux" at http://netfiles.uiuc.edu/rhasan/linux
The purpose of Pocket Linux is to support and encourage people who wish to explore Linux by building a GNU/Linux system from nothing but source code. Pocket Linux is not intended to be a full featured system, but rather to give the reader a taste of what is involved in building an operating system from source code. After completing the Pocket Linux system the reader should have enough knowledge to confidently build almost any project using only source code. Given this direction we can put a few constraints on the project.
The Pocket Linux project gets its name from the fact that the bulk of the project fits onto two diskettes making it possible to carry the entire, working system around in one's pocket. This has the advantage of not requiring any additional hardware since any PC can be booted from the diskettes without disrupting any OS that exists on the hard drive. Using diskettes also partially addresses the aspect of time commitment, because the project size and complexity is necessarily limited by the 1.44 Megabyte size of the installation media.
To further reduce the time commitment, the Pocket Linux project is divided into several phases, each one chapter in length. Each phase builds only a small piece of the overall project, but at the same time the conclusion of each chapter results in a self-contained, working system. This step-by-step approach should allow readers to pace themselves and not feel the need to rush to see results.
Chapters are further subdivided into four sections. The first two sections, analysis and design, focus on the theory of what is to be accomplished in each phase and why. The last two sections, construction and implementation, detail the steps needed to do the actual building. Advanced readers, who may be familiar with the theories laid out in a particular chapter are encouraged to gloss over the analysis and design sections in the interest of time. The separation of theory from hands-on exercises should allow readers of all skill levels to complete the project without feeling either completely lost or mired in too much detail.
Finally, the Pocket Linux project will strive to use GNU/GPL software when possible and other open-source licensed software when there is no GNU/GPL alternative. Also, Pocket Linux will never require any programming more complex than a BASH shell script.
Since this is the first phase of the project it will be kept very simple. The goal here is not to create the ultimate GNU/Linux system on the first try. Instead, we will be building a very minimal, working system to be used as a building block in subsequent phases of the project. Keeping this in mind, we can list a few goals for phase one.
Take a moment to skim through the Bootdisk-HOWTO or the From-PowerUp-to-BASH-Prompt-HOWTO. These HOWTO documents can be found online at http://www.tldp.org/docs.html#howto. Both documents offer an excellent view of what it takes to get a GNU/Linux system up and running. There is also a lot of information to digest. Remember that one of our goals is, "keep it simple to avoid stressing out," so we want to ignore everything but the absolutely critical pieces of a boot / root diskset.
Basically it boils down to the following required items:
We don't even need an init daemon. The kernel can be told to run the shell directly by passing it an option through the boot loader.
For easy construction we will build a two-disk boot / root set rather than trying to get everything onto a single diskette. The boot loader and kernel will go on the boot disk and the shell will reside on the root disk.
For the boot disk we simply need to install the GRUB bootloader and a Linux kernel. We will need to use a kernel that does not require modules for the hardware we need to access. Mainly, it should have compiled-in support for the floppy drive, ram disk, second extended filesystem, proc filesystem, ELF binaries, and a text-based console. If such a kernel is not available, it will need to be built from source code. Kwan Lowe's Kernel Rebuild Guide is a good reference for this task, however we can ignore the sections that deal with modules and the initial ramdisk.
For the root disk we will need a floppy that has been prepared with a filesystem. We will also need a BASH shell that is statically-linked so we can avoid the additional complexities of shared libraries. The configure program in the BASH source code recognizes the --enable-static-link option for this feature. We will also be using the --enable-minimal-config option to keep the BASH binary down to a manageable size. Additional requirements for the root disk are a /dev directory and a device file for the console. The console device is required for BASH to be able to communicate with the keyboard and video display.
There is one other, less obvious requirement to keep in mind and that is CPU compatibility. Each generation of CPU features a more complex architecture than its predecessor. Late generation chips have additional registers and instructions when compared to an older 486 or 386. So a kernel optimized for a new, fast 6x86 machine will not run on an older box. (See the README file in the Linux kernel source code for details.) A BASH shell built for a 6x86 will probably not run on an older processor either. To avoid this problem, we can choose the 386 as a lowest common denominator CPU and build all the code for that architecture.
In this section, we will be building the actual boot disk and root disk floppies. Lines preceded by bash# indicate a shell command and lines starting with grub> indicate a command typed within the grub shell.
Insert a blank diskette labeled "boot disk".
Get the GRUB source code from ftp://alpha.gnu.org/gnu/grub/ and unpack it into the /usr/src directory.
Configure and build the GRUB source code for an i386 processor by using the following commands:
Normally, after compiling source code, one would use the command make install to copy the finished files to their proper destinations in the filesystem. However, using make install does not work well with small media like the floppy disks we are using. The problem is that there are many files in a package besides the actual binaries that get the job done. For example, there are often man or info pages that provide documentation. These extra files can take up more space than we can spare on the diskette. We can work around this limitation by copying essential files manually rather than using make install.
For GRUB to boot we will need to copy the stage1 and stage2 bootloader files to the /boot/grub directory on the boot floppy.
Once the bootloader's files are copied to the boot disk we can enter the grub shell to finish the installation.
The steps for building the kernel were tested using Linux kernel version 2.4.26 and should work any 2.4.x or 2.6.x kernel. The latest version of the kernel source code may be downloaded from http://www.kernel.org/ or one of its mirrors.
Be sure to configure support for the following:
Insert a blank diskette labeled "root disk".
Get the bash-3.0 source code package from ftp://ftp.gnu.org/gnu/bash/ and untar it into the /usr/src directory.
Build BASH for an i386 CPU with the following commands:
Follow these steps to boot the system:
If all goes well the screen should look something like the example shown below.
Try out a few of BASH's built-in commands to see if things are working properly.
Try out a few other familiar commands.
Notice that only commands internal to BASH actually work and that external commands like ls and mkdir do not work at all. This shortcoming is something that can be addressed in a future phase of the project. For now we should just enjoy the fact that our prototype boot / root diskset works and that it was not all that hard to build.
One of the drawbacks in the prototype phase of the project was that the diskset was not all that useful. The only commands that worked were the ones built into the BASH shell. We could improve our root disk by installing commands like cat, ls, mv, rm and so on. Unfortunately, we are short on space. The current root disk has no shared libraries so each utility would have to be statically-linked just like the BASH shell. A lot of big binaries together with a static shell will rapidly exceed the tiny 1.44M of available disk space. So our main goal in this phase should be to maximize space savings on the root disk and pave the way for expanded functionality in the next phase.
Take another look at the Bootdisk-HOWTO and notice how many utilities can be squeezed onto a 1.44M floppy. There are three things that make this possible. One is the use of shared libraries. The second is stripped binaries. And the third is the use of a compressed filesystem. We can use all of these techniques to save space on our root disk.
First, in order to use shared libraries we will need to rebuild the BASH shell. This time we will configure it without using the --enable-static-link option. Once BASH is rebuilt we need to figure out which libraries it is linked with and be sure to include them on the root disk. The ldd command makes this job easy. By typing ldd bash on the command-line we can see a list of all the shared libraries that BASH uses. As long as all these libraries are copied to the root disk, the new BASH build should work fine.
Next, we should strip any binaries that get copied to the root disk. The manpage for strip does not give much description of what it does other than to say, "strip discards all symbols from the object files." It seems like removing pieces of a binary would render it useless, but this is not the case. The reason it works is because a large number of these discarded symbols are used for debugging. While debugging symbols are very helpful to programmers working to improve the code, they do not do much for the average end-user other than take up more disk space. And since space is at a premium, we should definitely remove as many symbols as possible from BASH and any other binaries before we copy over them to the ramdisk.
The process of stripping files to save space also works with shared library files. But when stripping libraries it is important to use the --strip-unneeded option so as not to break them. Using --strip-unneeded shrinks the file size, but leaves the symbols needed for relocation intact which is something that shared libraries need to function properly.
Finally, we can tackle the problem of how to build a compressed root filesystem. The Bootdisk-HOWTO suggests three ways of constructing a compressed root filesystem using either a ramdisk, a spare hard drive partition or a loopback device. This project will concentrate on using the ramdisk approach. It seems logical that if the root filesystem is going to be run from a ramdisk, it may as well be built on a ramdisk. All we have to do is create a second extended filesystem on a ramdisk device, mount it and copy files to it. Once the filesystem is populated with all the files that the root disk needs, we simply unmount it, compress it and write it out to floppy.
This section is written using ramdisk seven (/dev/ram7) to build the root image. There is nothing particularly special about ramdisk seven and it is possible to use any of the other available ramdisks provided they are not already in use.
View the output from the ldd command. It should look similar to the example below.
Successful implementation of this phase is probably the most difficult part of the Pocket Linux Guide. If you need help getting things to work please visit the Pocket Linux Guide Resource Site to browse the troubleshooting forum and subscribe to the mailing list.
Follow these steps to boot:
The screen output should be similar to the following example:
If the implementation was successful, this new root disk should behave exactly like the root disk from the previous chapter. The key difference is that this compressed root disk has much more room to grow and we will put this extra space to good use in the next phase of the project.
In the previous chapter it might seem like we did not accomplish very much. A lot of energy was expended redesigning the root disk, but the functionality is basically the same as in the initial prototype phase. The root disk still does not do very much. But we did make significant improvements when it comes to space savings. In this chapter we will put that extra space to good use and start cramming the root disk with as many utilities as it can hold.
The first two root disks we built only had shell built-in commands like echo and pwd. This time it would be nice to have some of the commonly used external commands like cat, ls, mkdir, rm and such on the root disk. Keeping this in mind we can define the goals for this phase as follows:
The first question that might come to mind is, "How do we know which commands are needed?" It is possible to just start with cat and ls then install other commands as we discover a need for them. But this is terribly inefficient. We need a plan or a blueprint to work from. For this we can turn to the Filesystem Hierarchy Standard (FHS) available from http://www.pathname.com/fhs/. The FHS dictates which commands should be present on a Linux system and where they should be placed in the directory structure.
The next logical question is, "Now that we know what we need, where do we get the source code?" One way to find the answer to this question is to check the manpages. We can either search the manpages included with one of the popular GNU/Linux distributions or use one of the manpage search engines listed at http://www.tldp.org/docs.html#man. One thing that should tip us off as to where to find the source code for a particular command is the email address listed for reporting bugs. For example the cat manpage lists firstname.lastname@example.org. From this email address we can deduce that cat is part of the textutils package from GNU.
So let's look at the FHS requirements for the /bin directory. The first few commands in the list are cat, chgrp, chmod, chown and cp. We already know that cat is part of GNU's textutils. Using the next few commands as keywords in a manpage search we discover that we need GNU's fileutils package for chmod, chgrp, chown and cp. In fact quite a few of the commands in /bin come from GNU's fileutils. The date command also comes from a GNU package called sh-utils. So a good way to tackle the problem of finding source code might be to group the commands together by package as shown below.
These four packages do not contain all of the commands in the /bin directory, but they do represent of over 70% of them. That should be enough to accomplish our goal of adding some of the commonly used external commands. We can worry about the other commands in later phases of the project.
To fetch the source code we simply need to connect to GNU's FTP site and navigate to the appropriate package directory.
When we get to the directory for textutils there are several versions available. There is also a note informing us that the package has been renamed to coreutils. The same message about coreutils appears in the fileutils and sh-utils directories as well. So instead of downloading three separate packages we can get everything in one convenient bundle in the coreutils directory.
Rather than copying files directly to the ramdisk, we can make things easier by setting up a staging area. The staging area will give us room to work without worrying about the space constraints of the ramdisk. It will also provide a way to save our work and make it easier to enhance the rootdisk in later phases of the project.
The staging procedure will work like this:
Download a recent version of coreutils from ftp://ftp.gnu.org/gnu/coreutils/
Check library requirements by using ldd on some of the new binaries.
Note the differences in the required libraries, as shown by the ldd command, and the libraries present in the staging area, as shown by the ls command, then copy any missing libraries to the staging area.
We will need to have a read-write filesystem in order for some of the commands to work. The kernel's normal behavior is to mount root as read-only, but we can change this using a kernel option. By passing the kernel the rw option before init=/bin/sh we will get a read-write root filesystem.
Follow these steps to get the system running.
The terminal display should look similar to the example below.
Now that the system is up and running, try using some of the new commands.
If everything goes well the commands like cat, ls and hostname should work now. Even mkdir should work since the root filesystem is mounted read-write. Of course since we are using a ramdisk, any changes will be lost once the PC is reset.
In the previous chapter we added many new commands by installing coreutils and as a result the root disk has a lot more functionality. But there are still a few things lacking. One thing that really stands out is that there was no way to mount disks. In order to get a read-write root filesystem we had to resort to passing the rw kernel parameter at the grub> prompt. This is fine for an emergency situation, but a normal system boot process should do things differently.
Most GNU/Linux distributions take several steps to mount filesystems. Watching the boot process or digging into the startup scripts on one of the popular Linux distributions reveals the following sequence of events:
So far our Pocket Linux system can do step one and that is it. If we want to have a professional looking boot / root diskset we will have to do better than one out of five. In this phase of the project we will work on steps two and three. Steps four and five can wait. Since this is a diskette-based system, there really are no other filesystems to mount besides root.
Taking into account all of the above information, the goals for this phase are defined as follows:
We can use the Filesystem Hierarchy Standard (FHS) document to help find the names of utilities we need and where they reside in the directory structure. The FHS /sbin directory lists fsck and something called fsck.* for checking filesystems. Since we are using a Second Extended (ext2) filesystem the fsck.* becomes fsck.ext2 for our purposes. Mounting filesystems is done using the commands mount and umount in the /bin directory. However, the name of a script to automatically mount local filesystems cannot be found. On most systems this type of script is in the /etc directory, but while FHS does list requirements for /etc, it does not currently make recommendations for startup scripts. Several GNU/Linux distributions use /etc/init.d as the place to hold startup scripts so we will put our filesystem mounting script there.
In the previous chapter we used manpages to help us find source code. In this chapter we will use a tool called the Linux Software Map (LSM). LSM is a database of GNU/Linux software that tracks such things as package name, author, names of binaries that make up the package and download sites. Using an LSM search engine we can locate packages using command names as keywords.
If we search Ibiblio's Linux Software Map (LSM) at http://www.ibiblio.org/pub/Linux/ for the keyword "fsck" we get a large number of matches. Since we are using a Second Extended filesystem, called ext2 for short, we can refine the search using "ext2" as a keyword. Supplying both keywords to the LSM search engine comes up with a package called e2fsprogs. Looking at the LSM entry for e2fsprogs we find out that this package contains the utilities e2fsck, mke2fs, dumpe2fs, fsck and more. We also find out that the LSM entry for e2fsprogs has not been updated for a while. There is almost certainly a newer version out there somewhere. Another good Internet resource for source code is SourceForge at http://sourceforge.net/. Using the keyword "e2fsprogs" in the SourceForge search engine results in a much newer version of e2fsprogs.
Finding fsck was quite an adventure, but now we can move on to finding mount and umount. A search on LSM comes up with a number of matches, but most of them point to various versions of a package called util-linux. All we have to do is scroll through and pick the most recent release. The LSM entry for util-linux lists a lot of utilities besides just mount and umount. We should definitely scan through the list to see if any of the other util-linux commands show up in the FHS requirements for /bin and /sbin.
Below is a list of packages we have gathered so far and the utilities that match up with FHS.
Now that we have fsck and mount commands we need to come up with a shell script to automate checking and mounting the local filesystems. An easy way to do this would be to write a short, two line script that calls fsck and then mount. But, what if the filesystems are not clean? The system should definitely not try to mount a corrupted filesystem. Therefore we need to devise a way of determining the status of the filesystems before mounting them. The manpage for fsck gives some insight into how this can be accomplished using return codes. Basically, if fsck returns a code of zero or one it means the filesystem is okay and a return code of two or greater means some kind of manual intervention is needed. A simple if-then statement could evaluate the fsck return code to determine whether or not the filesystem should be mounted. For help on writing shell scripts we can turn to the BASH(1) manpage and the Advanced-BASH-Scripting-Guide. Both references are freely available from the Linux Documentation Project web site at http://www.tldp.org/.
The last thing to do is to figure out if any other files besides the binaries are needed. We learned about using ldd to check for library dependencies in the last phase of the project and we will use it to check the utilities in this phase too. There are also some other files that fsck and mount will need and the fsck(8) and mount(8) manpages give some insight into what those files are. There is /etc/fstab that lists devices and their mount points, /etc/mtab that keeps track of what is mounted, and a number of /dev files that represent the various disks. We will need to include all of these to have everything work right.
The /etc/fstab file is just a simple text file that can be created with any editor. We will need an entry for the root filesystem and for the proc filesystem. Information about the format of this file can be found in the fstab(5) manpage or by looking at the /etc/fstab file on any of the popular GNU/Linux distributions.
The /etc/mtab file presents a unique challenge, because it does not contain static information like fstab. The mtab file tracks mounted filesystems and therefore its contents change from time to time. We are particularly interested in the state of mtab when the system first starts up, before any filesystems are mounted. At this point /etc/mtab should be empty so we will need to configure a startup script to create an empty /etc/mtab before any filesystems are mounted. But it is not possible to create any files in the /etc directory because / is read-only at startup. This creates a paradox. We cannot create an empty mtab, because the / filesystem is not mounted as writable and we should not mount any filesystems until we have created an empty mtab. In order to sidestep this problem we need to do the following:
Download the e2fsprogs source code package from http://sourceforge.net/projects/e2fsprogs/
Get the latest util-linux source from ftp://ftp.win.tue.nl/pub/linux-local/utils/util-linux/
Use a text editor to make the following changes to MCONFIG:
All of the dependencies revealed by the ldd command are for libraries already present in the staging area so there is no need to copy anything new.
Use an editor like vi, emacs or pico to create the following file and save it as ~/staging/etc/fstab.
Create an empty mtab file.
Use an editor to create the following shell script and save it as ~/staging/etc/init.d/local_fs:
Set execute permissions on the script.
Start the system using the following procedure:
The output should resemble the example below:
Run the script by typing the following commands at the shell prompt:
If everything is working properly, then the screen output should look something like the example below.
Procure a blank floppy disk and label it as "home". Remove the root disk floppy and insert the "home" diskette. Type the following commands:
The root disk from the last chapter is looking pretty good. It has about seventy percent of the commands that the Filesystem Hierarchy Standard (FHS) document requires for the root filesystem. Plus it has commands for checking and mounting filesystems. But even with all of this the root disk is far from perfect. The list below outlines three things that could use some improvement if the Pocket Linux system is to stand up next to the more professional looking distributions.
Taking the above list into consideration, the goals for this phase are defined as follows:
Loading the kernel without manually typing parameters is easy to do if we read the grub info page. According to the section entitled "configuration" all of the commands used for booting can be put in a file called menu.lst and placed in the /boot/grub directory.
To automate system start-up we will need an init daemon. We know this because the Bootdisk-HOWTO and From-Powerup-To-BASH-Prompt-HOWTO both make mention of init as the first program to start after the kernel loads. The latter HOWTO also goes into some detail about the /etc/inittab file and the organization of startup scripts. This could be helpful since FHS, the blueprint we have used so far, makes no recommendation for init scripts.
We will also need to find the shutdown command to fulfill the second goal of graceful shutdown capability.
Searching the Linux Software Map on Ibiblio for the keyword "init" gives a large number of results. From reading the From-Powerup-To-BASH-Prompt-HOWTO however, we know that most Linux systems use a System V style init daemon. Narrowing the search with the additional key phrase of "System V" gives much better results. The sysvinit package contains init, shutdown, halt and reboot which is everything we need. The version listed in the LSM entry looks to be pretty old, but there is a primary-site URL that will probably lead to the latest version.
The manpage for init mentions a FIFO called /dev/initctl that is required for init to communicate with other programs in the sysvinit package. We will have to create this file for init to function properly.
Using a GRUB configuration file is slightly more complex than specifying the bootloader commands manually. There are directives for features like menus, default selections and timeouts that need to be specified in the configuration file as well as the familiar kernel loading command. The info page for GRUB gives much of the necessary information. We may also be able to use the GRUB configuration file on the development system as a template. However, there is some inconsistency between vendors as to the name and location of the file. Regardless of what the path is on the development system it should be /boot/grub/menu.lst on the Pocket Linux System.
Many of the popular GNU/Linux distributions use System V style init scripts. Since we are using a "sysvinit" daemon it makes sense to use System V style scripts as well. The following documents all touch upon the System V style init scripts in some way and will serve as references when building the scripts for this project:
After glancing at one or two of the above references we should have a pretty good idea of how the System V style system initialization process works. We should also know what it takes to create System V style init scripts for the Pocket Linux project. Below is a brief list of what needs to be done:
As always, the BASH(1) manpage and the Advanced BASH Scripting Guide are very helpful for writing and understanding shell scripts.
There is a lot of typing to do in this section because of all of the start-up scripts that need to be created. Using a mouse to copy the text from this guide and paste it into a text editor can be a great time saving tool.
Insert and mount the floppy labeled "boot disk".
Use your favorite text editor to create the following file and save it as /mnt/boot/grub/menu.lst:
Download the latest sysvinit source from ftp://ftp.cistron.nl/pub/people/miquels/software/
Use a text editor to create the following file and save it as ~/staging/etc/inittab
Use a text editor to create the following file and save it as ~/staging/etc/init.d/rc
Make the file executable.
A case statement is added to allow the script to either mount or unmount local filesystems depending on the command-line argument given. The original script is contained inside the "start" portion of the case statement. The "stop" portion is new.
Use a text editor to create the following script and save it as ~/staging/etc/init.d/hostname
Use a text editor to create ~/staging/etc/init.d/halt as shown below.
Create the following script and save it as ~/staging/etc/init.d/reboot
Flag all script files as executable.
Boot the PC using the floppy labeled "boot disk". Place the recently created root disk in fd0 when prompted. The output should resemble the example below:
Use the mount command to check that local filesystems are mounted as read-write. The output should look like the example below.
Check the hostname.
Bring the system down gracefully with the shutdown command.
We should see the following output from init and the shutdown scripts:
Up to now the system has been operating in single-user mode. There is no login process and anyone who boots the system goes straight into a shell with root privileges. Obviously, this is not the normal operating mode for most GNU/Linux distributions. Most systems feature multi-user capability where many users can access the system simultaneously with different privilege levels. These multi-user systems also support virtual consoles so that the keyboard and video display can be multiplexed between several terminal sessions. So in this phase we would like to add the following enhancements to the system:
The From-Powerup-To-BASH-Prompt-HOWTO does a good job of outlining the steps in the login process. Basically it works like this.
The getty and login programs were already installed as part of the util-linux package so there is no need to download any new source code.
Details about virtual console device files can be found in the Linux kernel source code file called devices.txt in the Documentation directory. We will need to create tty1 through tty6 for each of the virtual consoles as well as tty0 and tty to represent the current virtual console.
The /etc/issue file is pretty easy to construct. It can contain any text we want displayed on the screen prior to the login prompt. It could be something friendly like "Welcome to Pocket Linux", something menacing like "Authorized users only!" or something informational like "Connected to tty1 at 9600bps". The agetty(8) manpage explains how to display information like tty line and baud rate using escape codes.
The format of /etc/passwd can be obtained by reading the passwd(5) manpage. We can easily create a user account by adding a line like "root::0:0:superuser:/root:/bin/sh" to the file.
Maintaining passwords will be somewhat challenging because of the system being loaded into ramdisk. Any changes to /etc/passwd will be lost when the system is shutdown. So to make things easy, we will create all users with null passwords.
The structure of /etc/group is available from the group(5) manpage. A line of "root::0:root" would define a group called "root" with no password, a group id of zero and the user root assigned to it as the only member.
User and group names and id's are generally not chosen at random. Most Linux systems have very similar looking /etc/passwd and /etc/group files. Definitions for commonly used user id and group id assignments may be found in one of several places:
Running ldd on the login program from util-linux will reveal that it is linked to the libraries libcrypt.so.1, libc.so.6 and ld-linux.so.2. In addition to these libraries there is another, unseen dependency on libnss_files.so.2 and the configuration file /etc/nsswitch.conf.
The name service switch library libnss_files.so.2 and nsswitch.conf are required for libc.so.6, and consequently the login program, to access the /etc/passwd file. Without libnss and its configuration file, all logins will mysteriously fail. More information about glibc's use of the name service switch libraries can be found at http://www.gnu.org/software/libc/manual/html_node/Name-Service-Switch.html.
Previously, with the single user system, there was no need to worry about permissions when installing directories, files and device nodes. The shell was effectively operating as root, so everything was accessible. Things become more complex with the addition of multiple user capability. Now we need to make sure that every user has access to what they need and at the same time gets blocked from what they do not need.
A good guideline for assigning ownership and permissions would be to give the minimum level of access required. Take the /bin directory as an example. The Filesystem Hierarchy (FHS) document says, "/bin contains commands that may be used by both the system administrator and by users". From that statement we can infer that /bin should have read and execute permission for everyone. On the other hand, the /boot directory contains files for the boot loader. Chances are good that regular users will not need to access anything in the /boot directory. So the minimum level of access would be read permission for the root user and other administrators who are members of the root group. Normal users would have no permissions assigned on the /boot directory.
Most of the time we can assign similar permissions to all the commands in a directory, but there are some programs that prove to be exceptions to the rule. The su command is a good example. Other commands in the /bin directory have a minimum requirement of read and execute, but the su command needs to be setuid root in order to run correctly. Since it is a setuid binary, it might not be a good idea to allow just anyone to run it. Ownership of 0:0 (root user, root group) and permissions of rwsr-x--- (octal 4750) would be a good fit for su.
The same logic can be applied to other directories and files in the root filesystem using the following steps:
Modify ~/staging/etc/inittab by changing the default runlevel and adding getty entries as shown below.
Create the file ~/staging/etc/issue using the example below or design a customized message.
Be sure that "\l" is a lowercase letter L and not the number one.
Use a text editor to create a minimal passwd file conforming to the Linux Standards Base (LSB) document. Save the file as ~/staging/etc/passwd
Use a text editor to create an LSB conforming group file and save it as ~/staging/etc/group
Set minimal privileges on all files and directories under ~/staging. Everything is owned by the root user and the root group. Permissions are read-write for the owner and read-only for the group. Exceptions to the blanket permissions are handled case by case.
Set execute permission on all directories. (Note the capital "X")
Files in /bin are read and execute for all, but su is an exception.
Files in /dev have various permissions. Disk devices should be accessible to administrators only. Other files like /dev/null should have full privileges granted to everyone.
The passwd and group files must be world readable.
The scripts in /etc/init.d are read and execute for administrators.
Libraries need read and execute permissions for everyone.
Only root should have access to the /root directory.
Make files in /sbin read and execute for administrators.
Temp should be read-write for all with the sticky bit set.
If everything goes well, the virtual console display should look similar to the following example:
Log in as root.
Create a new, unprivileged user and new group by appending a line to the /etc/passwd and /etc/group files, respectively. Be sure to use a double greater-than (>>) to avoid accidentally overwriting the files.
Switch to virtual terminal tty2 by pressing ALT+F2.
Log in as floyd.
Try the following commands and verify that they work.
Try the following commands and verify that they do not work.
The root disk has come a long way since its humble beginnings as a statically-linked shell. It now shares many features with the popular, ready-made distributions. For example it has:
As a final test, we can put the root disk up against the Filesystem Hierarchy Standard (FHS) requirements for the root filesystem. (We will ignore anything in the /usr hierarchy because of space constraints.) Compared to FHS requirement, the only files missing are a few commands in the /bin directory. Specifically, the root disk lacks the following commands:
In addition to the required commands, it might be nice to include the "ed" editor listed as an option by the FHS. It is not as robust as vi or emacs, but it works and it should fit onto the tiny root filesystem.
So in order to finish up this phase of the project, we need to accomplish the following goals:
There is a more command that comes with util-linux, but it will not work for this project. The reason is because of library dependencies and space constraints. The util-linux supplied more needs either the libncurses or libtermcap to work and there just is not enough space on the root disk floppy to fit everything in. So, in order to have a more command we will have to get creative.
The more command is used to display a file page by page. It's a little like having a cat command that pauses every twenty-five lines. The basic logic is outlined below.
Of course there are some details left out like what to do if the screen dimensions are not what we anticipated, but overall it is a fair representation of what more does. Given this simple program logic, it should not be hard to put together a short shell script that emulates the basic functionality of more. The BASH(1) manpage and Adv-BASH-Scripting-Guide will serve as references.
The more script will need access to device files that are not on the root disk yet. Specifically more needs to have stdin, stdout and stderr, but while we are at it we should check for any other missing /dev files. The Linux Standard Base requires null, zero and tty to be present in the /dev directory. Files for null and tty already exist from previous phases of the project, but we still need /dev/zero. We can refer to devices.txt in the Linux source code Documentation directory for major and minor numbers.
These three packages can be found by using the Internet resources we have used before plus one new site. The "sed" and "ed" packages can be found at the same place we found BASH, on the GNU FTP server. The procps package shows up in an Ibiblio LSM search, but it is an old version. In order to find the latest version we can go to the Freshmeat website at http://freshmeat.net and search for "procps" in projects.
Both "sed" and "ed" packages feature GNU's familiar configure script and are therefore very easy to build. There is no configure script for "procps" but this does not make things too difficult. We can just read the package's README file to find out about how to set various configuration options. We can use one of these options to avoid the complexity of using and installing libproc. Setting SHARED=0 makes libproc an integrated part of ps rather than a separate, shared library.
Create the following script with a text editor and save it as ~/staging/bin/more.sh
Create a symbolic link for more
Get the latest procps source package from http://procps.sourceforge.net/
Download GNU's sed from ftp://ftp.gnu.org/gnu/sed/
The ed package also comes from GNU at ftp://ftp.gnu.org/gnu/ed/
Display kernel messages by piping the output of dmesg to more.
Examine the local_fs script by using more with a command-line argument.
Display processes for the user currently logged in.
Display all available information about all running processes.
Use sed to display an alternate version of /etc/passwd.
Verify that sed did not make the changes permanent.
Use ed to change properties on the "daemon" user.
Verify that the changes are permanent (at least until the system is restarted.)
As the Pocket Linux Project draws to a close we should take a moment to celebrate all of our accomplishments. Some of the highlights are listed below:
The Pocket Linux system is nearly overflowing, so there really is no more room to expand the current root diskette to support any additional commands and features. This leaves us with a few choices of where to go next. We can:
Which ever path is chosen, we can move forward confidently, armed with the knowledge we need to be successful in our endeavors.
An operating system by itself is not much fun. What makes an OS great is the applications that can be run on top of it. Unfortunately, Pocket Linux currently does not have much room for anything other than system programs. Still, it would be nice to expand the system just enough to host some cool applications. Obviously a full-blown X-Windows GUI is out of the question, but running a small console based program should be within our reach.
Rather than doing a typical "hello world" program as an example, application hosting will be demonstrated using a console based audio player called mp3blaster. Building mp3blaster offers more technical challenge than "hello world" and the finished product should be a lot more fun. However, it should not be construed that a console-based jukebox is the only application for Pocket Linux. On the contrary, after completing this phase the reader should have the knowledge and tools to build almost any console-based program he or she desires.
So what will it take to turn a pocket-sized GNU/Linux system into a pocket-sized mp3 player? A few things are listed below.
There is a vast proliferation of audio hardware on the market and each sound card has its own particular configuration. For details on how to set up a particular sound card we can turn to the Sound-HOWTO available from The Linux Documentation Project. In a broader sense, however, we can treat a sound card like any other piece of new hardware. To add new hardware to a GNU/Linux system we will need configure the kernel to recognize it and configure /dev files on the root disk to access it.
In order to support sound cards, a new kernel will have to be built. It is very important that audio hardware support be configured as built-in, because Pocket Linux is not set up to handle kernel modules.
Probably the easiest way to create more space for the mp3blaster program is to mount an additional storage device. There are several choices for mount points. So far /usr, /home and /opt are all empty directories and any one of them could be used to mount a floppy, CD-ROM or additional compressed ramdisk image. The /usr directory is a logical choice for a place to put an application, but what about the choice of media? Mp3blaster and its required libraries are too big to fit on a 1.44M floppy and burning a CD-ROM seems like a lot of work for one little program. So given these constraints, the best choice would be to put the program on a compressed floppy.
Mounting CDs and uncompressed diskettes is easy, but what about loading compressed images from floppy into ramdisk? It will have to be done manually, because automatic mounting of compressed floppies only works for the root diskette. And using mount /dev/fd0 will not work because there is no filesystem on the diskette, there are only the contents of a gzip file. The actual filesystem is contained inside the gzip file. So how can we mount the filesystem buried beneath the gzip file? This puzzle can be solved by examining at the steps used to create the familiar compressed root disk floppy.
If that is how the compressed image makes its way from ramdisk to compressed floppy, then going from compressed floppy to ramdisk should be as simple as running through the steps in reverse.
We can cut out the intermediate image file by using a pipe to combine dd and gunzip like this: dd if=/dev/fd0 | gunzip -cq > /dev/ram1. Now the compressed floppy goes straight into ramdisk, decompressing on the fly.
We already have kernel support for ramdisks, because we are using a compressed root disk, but we will need to create more ramdisks in /dev. Typically the kernel supports eight ramdisks on /dev/ram0 through /dev/ram7 with ram0 being used for the rootdisk. The devices.txt file included in the Linux source code documentation will be helpful for matching devices to their major and minor numbers.
The sample mp3 file that we will be using in our example is small enough to fit on an uncompressed floppy disk so that there is no need to burn a CD. However, serious music lovers may want to have the capability to mount a custom CD-ROM full of tunes and that option will require support for additional hardware.
Most modern CD-ROM drives will use IDE devices like /dev/hdc or /dev/hdd. To support these CD-ROM drives we will have to configure IDE support in the kernel and create the appropriate device files on the root disk.
CD-ROMs have different filesystems than hard disks and floppies. Most CD burning applications use a filesystem called ISO-9660 and have the capability to support Joliet or Rockridge extensions. We will have to include support for these filesystems in the kernel in order to mount CD-ROMs.
We will want to have all of mp3blaster's required libraries and other supporting files available as part of the compressed /usr image so that mp3blaster can run correctly. The familiar ldd command can be used to determine which libraries mp3blaster requires. Any additional libraries can be placed in /usr/lib. Even though some of the libraries may appear in /lib on the development system, they can still go in /usr/lib on the Pocket Linux system. The dynamic linker, ld-linux.so, is smart enough to look in both places when loading libraries.
Because mp3blaster uses the curses (or ncurses) screen control library there is one additional file we need. The curses library needs to know the characteristics of the terminal it is controlling and it gets that information from the terminfo database. The terminfo database consists of all the files under the /usr/share/terminfo directory and is very large compared to our available disk space. But, since Pocket Linux only supports the PC console, we only have one terminal type to worry about and therefore need only one file. The piece of the terminfo database we need is the file /usr/share/terminfo/l/linux, because we are using a "Linux" terminal. For more information about the subject of curses, see John Strang's book entitled "Programming with Curses" available from O'Reilly publishing.
Between sound cards, ramdisks, CD-ROMs and terminfo there is quite a bit to keep track of. So let's take a moment to organize and summarize the tasks necessary to make the pocket jukebox a reality.
Be sure to configure support for the following:
Place the boot disk in drive fd0
Optionally create additional IDE devices.
Don't forget to verify library requirements, check the ownership and check permissions on the gzip binary.
Use a text editor to create the following script and save it as ~/staging/etc/init.d/usr_image
Configure the script to run right after root is mounted.
Insert the diskette labeled "root disk" into drive fd0.
The compressed /usr diskette will be created in using the same process that is used to create the compressed root disk. We will copy files to a staging area, copy the staging area to ramdisk, compress the ramdisk and write it to diskette.
Download the latest version of mp3blaster source code from its home at http://www.stack.nl/~brama/mp3blaster/.
Use ldd to find out which libraries are needed for mp3blaster.
Insert the diskette labeled "mp3blaster" into drive fd0.
Go to the Internet site http://www.paul.sladen.org and download the mp3 file of Linus Torvalds pronouncing "Linux." The direct link is: http://www.paul.sladen.org/pronunciation/torvalds-says-linux.mp3. Create a Second Extended (ext2) filesystem on a floppy and copy the mp3 file onto the diskette.
If everything worked there should be a line or two indicating that the kernel found the audio hardware. The example below shows how the kernel might report a Yamaha integrated sound system.
A short burst of static coming from the PC speakers indicates that sound is working.
Insert the diskette containing the sample audio file.
Use mp3blaster to select and play the file /home/torvalds-says-linux.mp3. Use mp3blaster's mixer controls to adjust the volume as needed.
The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.
This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.
We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.
This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.
A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.
A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.
The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.
The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".
Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.
The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.
A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.
You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and you may publicly display copies.
If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.
If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.
It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.
You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:
If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.
You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.
You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".
You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.
A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.
Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.
You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.
The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.
To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:
If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.
If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.