The Linux iPAQ HOWTO

Instructions for Familiar v0.5.3

Michel Stempin

Revision History
Revision v1.12002-08-30Revised by: ms
Corrections as suggested by Jamey Hicks
Revision v1.02002-08-11Revised by: ms
Initial version

Table of Contents
Preface
1. Introduction
2. Audience of this document
3. Organization of the material
4. Prerequisite
5. Versions
6. Sources of further information
7. Legal information
8. Online version
9. Conventions used in this document
10. Feedback
11. Acknowledgments
1. Connecting a PocketPC iPAQ to a GNU/Linux host
1.1. Creating a connection on the GNU/Linux host
1.2. Creating a connection on the iPAQ
1.3. Connecting the iPAQ to the PC
1.4. Transferring files between the iPAQ and the GNU/Linux host
2. Backing up the PocketPC iPAQ
2.1. Downloading the backup software
2.2. Backing up the Bootloader
2.3. Backing up PocketPC
3. Setting up a serial terminal connection to the iPAQ
3.1. Shutting down ppp
3.2. Setting up minicom
4. Installing the bootloader
4.1. Downloading the bootloader
4.2. Flashing the bootloader
4.3. Verifying the bootloader
4.4. Rebooting the iPAQ
5. Bootstrapping Familiar GNU/Linux
5.1. Downloading the root image
5.2. Performing bootloader configuration
5.3. Flashing the root filesystem
5.4. Booting GNU/Linux for the first time
6. Setting up an USB network
6.1. Connecting to the LAN
6.2. Connecting to the Internet
6.3. Shutting down USB networking
6.4. Automating the USB connection
7. Installing Familiar GNU/Linux
7.1. Upgrading packages definition
7.2. Running SSH
7.3. Installing additional Familiar packages
8. Installing Opie
8.1. Bootstrapping Opie
8.2. Finishing Opie installation
9. Reinstalling PocketPC
9.1. Restoring PocketPC
9.2. Checking PocketPC restoration
9.3. Restoring the original bootloader
A. GNU Free Documentation License
A.1. PREAMBLE
A.2. APPLICABILITY AND DEFINITIONS
A.3. VERBATIM COPYING
A.4. COPYING IN QUANTITY
A.5. MODIFICATIONS
A.6. COMBINING DOCUMENTS
A.7. COLLECTIONS OF DOCUMENTS
A.8. AGGREGATION WITH INDEPENDENT WORKS
A.9. TRANSLATION
A.10. TERMINATION
A.11. FUTURE REVISIONS OF THIS LICENSE
A.12. How to use this License for your documents

Preface

Today, Personal Digital Assistants (PDAs) are getting more and more popular, allowing the power of a 5-year old PC to fit in your hand, for the high-end models. Most of these PDAs come with an operating system and a set of softwares such as a contact management, a diary, a mail reader, a task manager, a calculator, a terminal emulator, a file explorer, a multimedia reader, a spreadsheet, a word processor, and of course, games.

Unfortunately, all these softwares are proprietary, and only licensed to the final user, who have no way to modify or improve them. Even worse, software development is difficult too, since proprietary development tools are required, which mean in turn that a programmer has to learn this tool and the provided Application Programming interface (API).

Hopefully, an alternative to this sad situation exists. Free Software, best represented by the GNU/Linux operating system, has proven its capability to provide quality tools through knowledge sharing, community support and good will. Moreover, the power of creativity is given back to the developers, allowing them to write programs using whatever API they prefer best, or even write their own if they want to.

This document proposes you to free your iPAQ from commercial software licenses by replacing the proprietary softwares by a GNU/Linux operating system and a set of application softwares that will provide the same (or even better...) tools than the original ones. Not only will it give you a taste of freedom, but it will also bring you back the joy of creativity, knowledge, and fun.

I hope you'll enjoy reading this document as much as I have enjoyed writing it.


1. Introduction

As an electronic engineer, I always enjoyed minimalistic systems. They always provide a kind of challenge to your accepted rules, as your dogmas tend to collapse when facing the crude reality. On minimal systems, this phenomenon tends to happen even quicker than on complex ones. One other interesting feature of this minimalistic approach is that it tends to keep things humanly manageable, which is comfortable, as today's computer science requires you to master a broad set of concepts, tools and computer languages...

Back in 1980, my first computer was a Goupil 2, quickly followed by an Apple II+, where I started programming. Having undergone dozens of computers, computer languages, and proprietary operating systems, I discovered Linux in 1994, when my company at that time (Lectra Systèmes), decided to take a Unix-like operating system on a PC platform as its base for application development. After careful evaluation and pushed by Pierre Ficheux and Daniel Roche, Linux was preferred to other commercial products, first because of its good performance but also because of its price. At that time, emails were not on everybody's computer, and the computer community was just emerging from the universities. We thus followed the growth of Free Software, and as an engineer, I found working like that was fun.

Since then, I tried to keep on working with GNU/Linux as much as possible, although I should not be considered as a Free Software activist. I am just pragmatic, and I still use commercial software whenever I don't find the corresponding free tools. I know, I should write my own, but sometimes, I am just too lazy, or focused on the more important goal that required this tool. I don't feel too guilty for that, as I try to participate to the Free Software movement whenever I can.

I got a first Uniden® PDA, but I should say that it belongs now to one of my brothers, since I was very disappointed by the fact that there was no (at least documented) way to change the software on it, or even to write programs for it without having to learn tons of things about DLL's major enhancement (I already played with shared libraries on my Amiga 500 in 1987...), and the virtues of Hungarian notation (I still find this is one of the silliest things ever invented, especially since polymorphisms in Object Oriented Programming).

I was a kind of shocked when I first saw my actual boss, Jean-Marc Lange, play with its iPAQ PDA. But what really stunt me is when I discovered by browsing on the Web that some crazy persons did it. Yes, thanks to what was formerly named Compaq® (now Hewlett Packard®), and a lot of good-willed persons, it was possible to put Free Software on this machine.

I took this as a challenge, and I think that writing this document on converting an iPAQ to GNU/Linux is my best effort to help the Free Software Community.

This document was also a good exercise to practice DocBook. If you read these lines, it means that I was able to master it!


7. Legal information


10. Feedback

I have tested and verified the information in this document to the best of my ability, but you may find that features have changed (or even that I have made mistakes!). Please let me know about any errors you find, as well as your suggestions for future editions, by writing to:

      
    

Feel free to send comments or ask technical questions about this document to the same address.

I also have a web page for the document, where I list errata, examples, or any additional information. You can access this page at:

      http://mstempin.free.fr/linux-ipaq
    


11. Acknowledgments

I would like to thank Sophie Calot for understanding the long hours I spent on writing this document, having confidence in me that I was doing something important, even if she is not the kind of girl that will use it...

I would like to thank also everybody at HandHelds.org. Without their first work, nothing would have been possible. This document is only another way of explaining what they discovered, I simply hope that I added some valuable information and a usefull approach of the subject.


Chapter 1. Connecting a PocketPC iPAQ to a GNU/Linux host

1.1. Creating a connection on the GNU/Linux host

Although the iPAQ's cradle has an USB cable, we will not be able to use it while the iPAQ is running PocketPC, as its use is limited to the proprietary ActiveSync program.

The only possibility will be to use the slower serial cable attached to the cradle and PPP (Point to Point protocol), which provides a way to use TCP/IP over a serial line. In Chapter 6, as GNU/Linux is installed, we will setup a faster USB network.

For now, we will have to setup PPP both on the PocketPC iPAQ and on the GNU/Linux host.


1.1.1. pppd configuration

On the GNU/Linux host, PPP is implemented by the pppd command, which uses either options specified after the name pppd on the command line, separated by space characters, or a configuration file. This method will be preferred, as it is tedious to type the same things over and over.

The configuration file can have any name, but is best if placed in the directory /etc/ppp/peers, where pppd will look for its configuration files. In this document, I will use a file named /etc/ppp/peers/PocketPC.

The content of this file is as follows:

# /etc/ppp/peers/PocketPC -*- sh -*- pppd options for direct iPAQ connection
# created 08-May-2002 Michel Stempin <michel.stempin@wanadoo.fr>
# autodate: 08-May-2002
# autotime: 16:38

# The serial line to use. Use either "/dev/ttyS0" for "COM1" or "/dev/ttyS1"
# for "COM2" PC ports.
/dev/ttyS1

# Set the speed to 115200 bps.
115200
# As PocketPC considers us as a modem ;-), we have to pretend by sending
# the expected answers.
# For this, we use the "chat" program and "expect/send" pairs. You can specify
# the "-v" option to /usr/sbin/chat if you want to debug the "modem" initial dialog.
# Basically, the chat is (\r means a <CR>, i.e. a Carriage Return character):
#     - expect ATZ<CR> (reset modem command)
#     - send OK<CR>
#     - expect AT<CR> (are you here? command)
#     - send OK<CR>
#     - expect ATE0V1&C1&D2<CR> (disable echo,
#                                 send ASCII result codes,
#                                 Carrier Detect pin is used,
#                                 Data Terminal Ready pins reflects online state),
#     - send OK<CR>
#     - expect AS7=120<CR> (timeout 120s waiting for Carrier)
#     - send OK<CR>
#     - expect ATX3<CR> (ignore dial tone, report BUSY)
#     - send OK<CR>
#     - expect ATDT<CR> (dial using tone modulation)
#     - send CONNECT<CR>
connect "/usr/sbin/chat 'ATZ\r' OK 'AT\r' OK 'ATE0V1&C1&D2\r' \
OK 'ATS7=120\r' OK 'ATX3\r' OK 'ATDT' CONNECT"

# async character map -- 32-bit hex; each bit is a character
# that needs to be escaped for pppd to receive it.  0x00000001
# represents '\x01', and 0x80000000 represents '\x1f'.
asyncmap 0

# Do not require PocketPC to authenticate itself before allowing network
# packets to be sent or received.
# NOTE: This option is only available to the "root" user.
noauth

# No hardware flow control (i.e. RTS/CTS) to control the flow of data
# on the serial port, as the iPAQ seems not to handle it.
nocrtscts

# Don't use the modem control lines
local

# Specifies that pppd should use a UUCP-style lock on the serial device
# to ensure exclusive access to the device.
lock
# Don't fork to become a background process (otherwise pppd will do so
# if a serial device is specified).
-detach

# Increase debugging level (same as -d).  If this option is given, pppd
# will log the contents of all control packets sent or received in a
# readable form.  The packets are logged through syslog with facility
# daemon and level debug. This information can be directed to a file by
# setting up /etc/syslog.conf appropriately (see syslog.conf(5)).  (If
# pppd is compiled with extra debugging enabled, it will log messages
# using facility local2 instead of daemon).
#debug

# Enable debugging code in the kernel-level PPP driver.  The argument n
# is a number which is the sum of the following values: 1 to enable
# general debug messages, 2 to request that the contents of received
# packets be printed, and 4 to request that the contents of transmitted
# packets be printed.
#kdebug 7

# Sets the IP addresses on both side of the link.
192.168.1.100:192.168.1.101

1.2. Creating a connection on the iPAQ


1.3. Connecting the iPAQ to the PC


1.4. Transferring files between the iPAQ and the GNU/Linux host

As is, PocketPC has only one tool that uses the standard TCP/IP protocols able to transfer files: it is the Internet Explorer Web browser. Although its usage is straightforward, it has two drawbacks:

  1. it requires a running Web server on the GNU/Linux host

  2. it is only able to transfer file in one direction (from the GNU/Linux host to the iPAQ)

That is, it does not fulfill our requirements: to be able to exchange files in both directions.

The workaround I have found is to use it initially to download a minimum FTP server on the PocketPC iPAQ, which will be used for all subsequent transfers.


1.4.1. Downloading and running the mini FTP server

As we will use a Web browser on the iPAQ, we need first to set up a Web server on the GNU/Linux host, place the mini FTP server so it can be accessed from the iPAQ, then download it and install it.


1.4.1.1. Setting up a Web server on the GNU/Linux host

Giving all the details required to set up a Web server on a GNU/Linux host is beyond the scope of this guide. Maybe you already have done it for another task, or your GNU/Linux distribution has already done it for you.

So, I will only describe what is required to set up the Apache Web server. I will assume that you already have installed the required package for it, using your distribution's packaging tool.

We first have to locate the Apache configuration file, by running the following command:

bash# find etc -name httpd.conf -print
/etc/httpd/conf/httpd.conf

This tells us that the file is located in the directory /etc/httpd/conf. In this directory, we will find where the root of the Web server is; that is, in which directory we will have to place files so they can be seen from the iPAQ. I search on the whole directory, as the information is not necessarily in the httpd.conf file in old Apache versions:

bash# grep DocumentRoot /etc/httpd/conf/*
/etc/httpd/conf/httpd.conf:# DocumentRoot: The directory out of which you will serve your
/etc/httpd/conf/httpd.conf:DocumentRoot "/var/www/html"
/etc/httpd/conf/httpd.conf:# This should be changed to whatever you set DocumentRoot to.
/etc/httpd/conf/httpd.conf:#    DocumentRoot /www/docs/dummy-host.example.com
/etc/httpd/conf/httpd.conf:#DocumentRoot "/etc/httpd/htdocs"

Some other lines that may list errors can be safely ignored. The only interesting thing here is the second line, saying that the DocumentRoot is located in the /var/www/html directory. This may be different for your system.

Using this information, we will create a directory where we will store the files for the iPAQ: let's call it iPAQ:

bash# cd /var/www/html
bash# mkdir iPAQ; cd iPAQ

We then have to launch the Apache Web server. On my Red Hat 7.2 distribution, I can issue either:

bash# service httpd start

or

bash# /etc/rc.d/init.d/httpd start

Depending on your GNU/Linux distribution, you may have to find the right way to do it...


1.4.1.2. Getting the PocketPC mini FTP server

Copy in this directory the FTPS006AP.ZIP file (aka, the ftpserv zipped file), downloaded from the following location:

http://www.oohito.com/wince/arm_j.htm

Unzip the archive using the following command:

bash# unzip FPS006AP.ZIP
Archive:  FTPS006AP.ZIP
  inflating: ftpsvr.exe
  inflating: ftpsvr.txt

We are interested in the ftpsvr.exe file.


1.4.1.3. Downloading the mini FTP server on the PocketPC iPAQ

If everything is OK, you should be able to download the ftpsvr.exe file by fetching the following URL in the Internet Explorer Web browser on the PocketPC iPAQ:

http://192.168.1.100/iPAQ/ftpsvr.exe

Note: You may have to go into the "Display" menu, and enable the "URL bar" option to be able to enter the URL.

A "Download" popup menu should open, asking you if you want to download the ftpsvr.exe file, giving you the option to open it after downloading. I suggest you to check this last option.

On the PocketPC iPAQ, you can now close Internet Explorer and go back to the main "Today" screen. In the lower right corner, you should have a small icon. When you tap on it, a window "FtpSvr for Windows® CE Ver 0.06" should open, that is a little too large on my iPAQ, so you may have to move it around to see it completely.

This window tells you that the FTP server is running, listening on port 21. You have the option to stop it, uninstall it (don't!), or exit.

Everything is ready now to be able to transfer files in both directions.

Whenever you want to restart the mini FTP server, you just have to click on the ftpsvr.exe icon where you saved it after downloading it (normally in the "My Documents" folder).


1.4.2. Transferring files using FTP

On the GNU/Linux host, you can either use the command line ftp, or your favorite graphical FTP client. I will show here the basic, command line option:

bash$ ftp ipaq
Connected to ipaq (192.168.1.101).
220 FtpSvr (Version 0.06).
Name (ipaq:root):
331 Password required for root.
Password:
230 User root logged in.
ftp> passive
Passive mode off.
ftp> 

Warning

The mini FTP server should not be used permanently, as it lacks some important security features. You should only turn it on whenever necessary.

You can now transfer files back and forth:

ftp> ls
200 PORT command successful.
150 Opening ASCII mode data connection for \467456.FTP(782 bytes).
drwxrwxrwx   1 owner    group      0          Jan  1  1998 iPAQ File Store
-rw-rw-rw-   1 owner    group      76         Sep  4  7:44 467456.FTP
-rw-rw-rw-   1 owner    group      282        Sep  4  7:16 mdmlog0.txt
-rw-rw-rw-   1 owner    group      72         Sep  4  7:14 mdmlog5.txt
-rw-rw-rw-   1 owner    group      10500      Sep  4  7:15 GCounterFile.mmf
-rw-rw-rw-   1 owner    group      56         Sep  3 20:00 CMMapP
-rw-rw-rw-   1 owner    group      60         Sep  3 20:00 CMMapG
drwxrwxrwx   1 owner    group      0          Sep  3 12:00 Program Files
drwxrwxrwx   1 owner    group      0          Sep  3 12:00 My Documents
drwxrwxrwx   1 owner    group      0          Sep  3 12:00 Temp
drwxrwxrwx   1 owner    group      0          Sep  3 12:00 Windows
226 Transfer complete.
ftp> put whatever
local: whatever remote: whatever
200 PORT command successful.
150 Opening BINARY mode data connection for \whatever.
226 Transfer complete.
6 bytes sent in 8.4e-05 secs (70 Kbytes/sec)
ftp> ls
200 PORT command successful.
150 Opening ASCII mode data connection for \467456.FTP(851 bytes).
drwxrwxrwx   1 owner    group      0          Jan  1  1998 iPAQ File Store
-rw-rw-rw-   1 owner    group      76         Sep  4  7:45 467456.FTP
-rw-rw-rw-   1 owner    group      6          Sep  4  7:45 whatever
-rw-rw-rw-   1 owner    group      282        Sep  4  7:16 mdmlog0.txt
-rw-rw-rw-   1 owner    group      72         Sep  4  7:14 mdmlog5.txt
-rw-rw-rw-   1 owner    group      10500      Sep  4  7:15 GCounterFile.mmf
-rw-rw-rw-   1 owner    group      56         Sep  3 20:00 CMMapP
-rw-rw-rw-   1 owner    group      60         Sep  3 20:00 CMMapG
drwxrwxrwx   1 owner    group      0          Sep  3 12:00 Program Files
drwxrwxrwx   1 owner    group      0          Sep  3 12:00 My Documents
drwxrwxrwx   1 owner    group      0          Sep  3 12:00 Temp
drwxrwxrwx   1 owner    group      0          Sep  3 12:00 Windows
226 Transfer complete.
ftp> get whatever
local: whatever remote: whatever
200 PORT command successful.
150 Opening BINARY mode data connection for \whatever(6 bytes).
226 Transfer complete.
6 bytes received in 1.01 secs (0.0058 Kbytes/sec)
ftp> bye
221 Goodbye

Chapter 2. Backing up the PocketPC iPAQ

There are several reasons why you should consider backing up the PocketPC iPAQ before proceeding to the GNU/Linux replacement:

This is why I urge you to backup your iPAQ. When it comes to safety procedure, it is better to have suspenders, a belt, and a parachute than nothing...


2.1. Downloading the backup software

The software that we will use to backup everything on the PocketPC iPAQ is included in the software that will be used in chapter Chapter 4 to replace the original bootloader. This software can be downloaded from:

ftp://handhelds.org/feeds/BootBlaster/BootBlaster_1.18.exe

I recommend you also download the corresponding md5sum file, so you can check BootBlaster's integrity. The md5sum can be downloaded from:

ftp://handhelds.org/feeds/BootBlaster/BootBlaster_1.18.exe.md5sum

Transfer the BootBlaster_1.18.exe file onto the iPAQ, by following the steps in Section 1.3 and Section 1.4.2.

You can check the integrity by running the following command:

bash$ md5sum -c BootBlaster_1.18.exe.md5sum
BootBlaster_1.18.exe: OK

Chapter 3. Setting up a serial terminal connection to the iPAQ

In this chapter, we will set up a serial terminal connection to the iPAQ that will be used later for:

On the GNU/Linux host, we will use minicom as a terminal emulator.


3.1. Shutting down ppp

If you followed the chapters in this book in a logical order, you should have an automatic ppp on the GNU/Linux host, waiting for connections from the iPAQ (see Section 1.3.1.2). You must disable it before proceeding. Comment out the following line in the /etc/inittab file by putting a "#" at the beginning of the line, using you favorite text editor:

#ppp:2345:respawn:/usr/sbin/pppd call PocketPC

You must tell the running init process to re-read its configuration by typing:

bash# init q

The serial line is now free, so we can use the terminal emulator.


Chapter 4. Installing the bootloader

This chapter covers the only dangerous step in the whole conversion process. By dangerous, I mean that this can really turn your iPAQ into a useless high-tech paperweight! Fortunately, this only happen very seldom, and the risk is close to zero if you follow the instructions carefully.

As a service, Compaq (now HP) Research ensures that it will fix your unit in case it was rendered nonbooting by a failed installation. Of course, this may take a while before you get it back, and this should only be seen as the last resort.

Warning

As this operation may erase everything on your unit, be sure to have a backup as described in Chapter 2 and md5sum-verified BootBlaster_1.18.exe and bootldr-2.18.01.bin files as described in Chapter 2 and Section 4.1.

Remember, THIS OPERATION IS PERFORMED AT YOUR OWN RISKS.


4.1. Downloading the bootloader

The default bootloader (code name Parrot) is quite sophisticated. It can be accessed by pushing the central "arrow pad" on the iPAQ and resetting by putting the stylus into the narrow hole at the bottom of the case (don't do it!). Then, using a terminal emulator as set up in the previous chapter, you can obtain a command line that allow you to do various things.

Unfortunately, this bootloader is only able to boot the pre-installed operating system, so we have to replace it in order to boot another OS, like GNU/Linux.

Compaq's (now HP's) Cambridge Research Laboratories developed such a bootloader. You can download it from:

ftp://handhelds.org/feeds/bootldr/bootldr-2.18.01.bin

You must download the corresponding md5sum file from:

ftp://handhelds.org/feeds/bootldr/bootldr-2.18.01.bin.md5sum

You must check the file integrity by running the following command:

bash$ md5sum -c bootldr-2.18.01.bin.md5sum
bootldr-2.18.01.bin: OK

Warning

Not checking the bootldr's integrity may be catastrophic, as if the file is damaged, you will not be able to boot your iPAQ anymore, transforming it into a brick.

Transfer the bootldr-2.18.01.bin file onto the iPAQ, by following the steps in Section 1.3 and Section 1.4.2.

Note: A good way to check bootldr's integrity on the iPAQ is to transfer it back onto the GNU/Linux host and check it again with md5sum.


4.2. Flashing the bootloader

If you followed the steps sequentially, you should have BootBlaster_1.18.exe and bootldr-2.18.01.bin on your PocketPC iPAQ. We will flash the new bootloader by doing the following:

  1. In the "Start" menu, tap on the "Programs" entry.

  2. Tap on the "File Explorer" icon to launch File Explorer.

  3. Locate the BootBlaster icon (probably somewhere in "My Documents") and tap on it to launch it.

  4. Tap on the "Flash" menu.

  5. Tap on the "Program" entry. A warning popup window will open, asking you to confirm.

  6. Tap on "Yes" to confirm.

  7. A File dialog will open, enabling you to choose the bootloader file you want to use. Select the one you downloaded in Section 4.1

  8. A dialog will ask you to confirm the file you want to flash. Tap on "Yes" to continue.

  9. Wait patiently. The process of flashing the new bootloader takes about 15 seconds. During this time, BootBlaster will display what it is doing:

    1. Erasing flash...
    2. Protecting Wince Partitions...

      BootBlaster protects the PocketPC partitions before proceeding to bootloader flashing. It looks like PocketPC is still able to boot the machine, even if the bootloader is erased, as long as it PocketPC is not touched.

      Warning

      It is not safe to erase the bootloader if GNU/Linux is installed in flash -- GNU/Linux depends on the bootloader to configure the machine before jumping into GNU/Linux.

      Up to and including this point, it is perfectly safe to reboot your iPAQ. If your machine takes more than 15 seconds to perform this operation, reboot the iPAQ by pushing the recessed reset button at the bottom right and repeat this step.

    3. Programming Flash...

      This is the sensitive point, as during this time, your bootloader is not in a consistent state. This operation is very short, so the chance that you get a power loss while doing it is small.

      Warning

      If your iPAQ hangs while programming, send e-mail to and/or get on the IRC and ask for help. Leave the iPAQ plugged in and do not reset it.

  10. Once flashing has been performed, a dialog will open, stating that you have a valid OHH (Open HandHeld) Boot loader 2.18.1 in flash, and how to access the serial console. Tap on "ok" to close this dialog.


4.4. Rebooting the iPAQ

If you reset your iPAQ by pushing the recessed reset button at the lower right of the unit, the bootloader will boot PocketPC if present, just as usual.

What is different, is that you can get a serial console onto the iPAQ and that you get the following splash screen:

To get this serial console, configure a terminal emulator as described in Chapter 3.

Then, reboot your iPAQ by pushing the recessed reset button at the lower right of the unit while holding the center of the joypad (you will have to remove the iPAQ from its cradle to access the reset button). Put it back into the cradle and press the space bar into the terminal emulator or press the Calendar button on the iPAQ. You should get bootldr's boot prompt "boot>".

It is now safe to unprotect PocketPC, by typing the following in the terminal emulator:

boot> pflash 0x40000 0xffff 0
  addr=00040000
  len=0000FFFF
  protect=00000000
Protect=00000000
boot>

Bootloader's installation is now complete.


Chapter 5. Bootstrapping Familiar GNU/Linux

In this chapter, we will install the Familiar GNU/Linux bootstrap onto the iPAQ. It will be used in next chapter to install the full-blown Familiar GNU/Linux onto the iPAQ.


5.3. Flashing the root filesystem

Issue the following commands:

boot> set ymodem 1
  setting param <ymodem> to value <1>
boot> load root
loading flash region root
using ymodem
ready for YMODEM transfer...

This command tells the iPAQ to be ready to receive the root image using the xmodem protocol. You just have to feed it from the running minicom window, by pressing Ctrl-A and S. A small popup window will appear, allowing you to choose the transfer protocol. Using the arrow down key, move down to the "ymodem" entry and press Enter.

A file selector window will open, where you need to specify the file to download. Using the arrow right key and pressing Enter, you can go to the directory containing the root image file transfered in Section 5.1. Using the arrow down key, move down to the correct file, and hit space to select the file, then press Enter.

A window will open, displaying the current transfer status. The transfer should take about 15 minutes, so be patient. When completed, a beep will awake you, so press Esc to close the window. The following lines should appear:

94208F6013CD23402361CC8905022946  task-bootstrap.jffs2
00600000 bytes loaded to C0000400

Erasing sector 00040000
Erasing sector 00080000
Erasing sector 000C0000
Erasing sector 00100000
Erasing sector 00140000
...
Erasing sector 01F40000
Erasing sector 01F80000
writing flash..
addr: 00040000 data: E0021985
addr: 00050000 data: 12512501
addr: 00060000 data: 8CF607FF
...
addr: 00610000 data: C8E314FE
addr: 00620000 data: 9B95ACF1
addr: 00630000 data: FFFFFFFF
verifying ...
formatting ... done.
boot> 

This mean that the bootloader first erases the flash memory, then writes to it the downloaded image, verifies it and finally formats it correctly.


5.4. Booting GNU/Linux for the first time

Simply issue the following command:

boot>boot

The familiar penguin should appear on the iPAQ's screen, as well as the following output in the terminal emulator:

booting jffs2...
booting boot/zImage from partition >root<
Scanning all of flash for your JFFS2 convenience. Est Time: 6-12 seconds!
build_list: max = 01F7FFBC

...

Generating SSH DSA host key (this is slow, please be patient)...
Generating DSA parameter and key.
Your identification has been saved in /etc/ssh/ssh_host_dsa_key.
Your public key has been saved in /etc/ssh/ssh_host_dsa_key.pub.
The key fingerprint is:
0f:45:15:0e:dd:b3:cf:10:a3:5e:89:27:d6:c7:f6:04 root@familiar
Done.
Starting OpenBSD Secure Shell server: sshd.

familiar login:

You can login as the "root" user by providing the default "rootme" password.


Chapter 6. Setting up an USB network

Setting up an USB network will allow us to speed up the installation by providing a faster, as well as an easier way to transfer files than the serial method used up to now.

There are two steps involved in setting up the network:

  1. Establish the iPAQ connection to the LAN (Local Area Network), if it exists. Anyway, if it does not exist, this connection will be used to access the Internet. We will use the mechanism known as proxy_arp, that will assign two IP addresses to the host, one for itself and one for the iPAQ.

  2. Establish the iPAQ connection to the Internet. If the GNU/Linux host is part of a LAN and already has access to it, then no further work is required, and the iPAQ should be able to access it too. However, if the host is directly connected to the Internet through a modem, then we will have to set a mechanism called NAT (Network Address Translation), in order to map iPAQ's address to the same IP address the GNU/Linux host uses to access the Internet. This is required, as your ISP (Internet Service Provider) probably supplied only a single address to you. Another consideration will be to declare the iPAQ to the firewall, so it gets proper authorizations to access the Internet.


6.1. Connecting to the LAN

For this step, work is needed both on the GNU/Linux host and on the iPAQ.


6.1.2. USB networking on the iPAQ

On the iPAQ side, the USB driver is included in the bootstrap image. However, we need to create all the files needed to start/stop/suspend/resume the USB network.

Download the following file onto your GNU/Linux host, and name it usbnet:

#!/bin/sh
# chkconfig: 2 45 96
# processname: usbnet
# pidfile: /var/run/usbnet.pid
# lockfile: /var/lock/subsys/usbnet

usage()
{
    echo "Usage: $0 {start|stop|status}"
}

PC_ADDR=192.168.1.100
IPAQ_ADDR=192.168.1.101
GW_ADDR=192.168.1.100
DRIVER=usb-eth
INTERFACE=usbf

if [ $# -lt 1 ]; then 
    usage
    break
fi
case "$1" in
    start)
	modprobe $DRIVER
	ifconfig $INTERFACE inet $IPAQ_ADDR up
	route add default gw $GW_ADDR
	;;
    stop)
	ifconfig $INTERFACE down
	modprobe -r $DRIVER
	;;
    status)
	ifconfig $INTERFACE
	;;
    *)
	usage
	;;
esac

Replace the IP addresses by the ones corresponding to your network, then transfer it using the zmodem protocol. When you have set up a terminal connection using minicom, as described in Chapter 3, issue the following commands on the iPAQ:

# cd /etc/init.d
# rz
.. waiting to receive.**B0100000023be50

This command tells the iPAQ to be ready to receive the package using the zmodem protocol. You just have to feed it from the running minicom window, by pressing Ctrl-A and S. A small popup window will appear, allowing you to choose the transfer protocol. Using the arrow down key, move down to the "zmodem" entry and press Enter.

A file selector window will open, where you need to specify the file to download. Using the arrow right key and pressing Enter, you can go to the directory containing the usbnet file. Using the arrow down key, move down to the correct file, and hit space to select the file, then press Enter.

A window will open, and minicom will beep. Press Esc to close the window. Press Enter to get back the shell prompt.

Make this script executable by issuing:

# chmod +x /etc/init.d/usbnet

Based on this file, we will create the necessary setup needed to launch USB networking automatically when you boot, so we have to create a symbolic link to this script into the /etc/rc2.d directory, which is the directory containing the scripts to launch when you go into runlevel 2 (the normal runlevel):

# cd /etc/rc2.d
# ln -s ../init.d/usbnet S45usbnet.sh

For this first time, we can just launch it manually by typing:

# /etc/init.d/usbnet start
SA1100 USB Controller Core Initialized
usbctl: Opened for usb-eth
usbctl: Started for usb-eth

We also need to create the files required to stop/start the USB network when going into suspend/resume mode. Using the previous script, they are easy to create:

# cat >/etc/suspend-scripts/S33usbnet
#!/bin/sh
/etc/init.d/usbnet stop
Ctrl-D
# cat >/etc/resume-scripts/R33usbnet
#!/bin/sh
/etc/init.d/usbnet start
Ctrl-D
# chmod +x /etc/*scripts/*usbnet

6.1.3. Bringing up the USB network

If you have not already done it, insert the usbnet module on the GNU/Linux host:

bash# modprobe usbnet

Make sure the cradle's USB and serial cables are connected to the host PC. Remove the iPAQ from the cradle and put it back. If you run minicom, you should see the following message in the terminal emulator window:

usbctl: zombie suspended --> [resume] --> zombie. Device in powered state.
usbctl: zombie --> [reset] --> default. Device in default state.
usbctl: Resetting
usbctl: default --> [address assigned] --> address. Device in address state.
usbep0: I have been assigned address: 14
usbctl: address --> [configure] --> configured. Device in configured state.
usbep0: Configured (OMP=00000040 IMP=00000040)
usbep0: fixme: set interface not supported

This means that our host's USB subsystem has correctly detected and configured the iPAQ. On the iPAQ, you can check that everything is working by issuing the following command:

# ifconfig
lo        Link encap:Local Loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          UP LOOPBACK RUNNING  MTU:16436  Metric:1
          RX packets:8 errors:0 dropped:0 overruns:0 frame:0
          TX packets:8 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:728 (728.0 b)  TX bytes:728 (728.0 b)

usbf      Link encap:Ethernet  HWaddr 9A:4D:0E:33:E7:01
          inet addr:192.168.1.101  Mask:255.255.255.0
          UP RUNNING  MTU:1500  Metric:1
          RX packets:4 errors:0 dropped:0 overruns:0 frame:0
          TX packets:4 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:100
          RX bytes:224 (224.0 b)  TX bytes:280 (280.0 b)

This last paragraph provides the necessary information about the USB network interface.

On the GNU/Linux host, a new network interface usbN (where N is a number starting from 0) will appear when the iPAQ is connected to the USB bus. You can then configure it like any other ethernet interface.

To save a lot of typing if you are going to use it on a regular basis, I suggest you to create the following ipaqnet script on your GNU/Linux host (please replace the addresses and UPLINK_IF with your appropriate values):

#!/bin/bash
#
# ipaqnet	Control script for iPAQ USBNet connection
#
# Author: Michel Stempin
# Creation: 11/08/2002

PC_ADDR=192.168.1.100
IPAQ_ADDR=192.168.1.101/32
IPAQ_NET=192.168.1.0/24
UPLINK_IF=ppp0

start() {
    modprobe usbnet
    ifconfig usb0 inet $PC_ADDR up
    if [ $? -ne 0 ]; then
        exit 1
    fi
    echo "1" >/proc/sys/net/ipv4/conf/usb0/proxy_arp
    UPLINK=`ifconfig $UPLINK_IF >/dev/null 2>&1`
    if [ $? -ne 0 ]; then
        exit 1
    fi
    echo "1" >/proc/sys/net/ipv4/conf/$UPLINK_IF/proxy_arp
    echo "1" >/proc/sys/net/ipv4/ip_forward
    ip route del $IPAQ_NET dev usb0
    ip route add $IPAQ_ADDR dev usb0
}

stop() {
    ifconfig usb0 down
    rmmod -r usbnet
}
case "$1" in
    start|add)
        start
        ;;
    stop|remove)
        stop
        ;;
    *)
        echo $"Usage: $0 {start|stop|add|remove}"
        exit 1
esac

Make this script executable by typing:

bash# chmod +x path_to_ipaqnet/ipaqnet

We should now be able to launch the connection by typing:

bash# path_to_ipaqnet/ipaqnet start

If some sort of error message appears at this point, it means that the iPAQ insertions was not correctly handled, try re-inserting it.

This script uses the proxy_arp mechanism introduced above to forward data to the iPAQ.

On the GNU/Linux host, you can check that everything is working by issuing the following command:

# ifconfig
lo        Link encap:Local loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          UP LOOPBACK RUNNING  MTU:16436  Metric:1
          RX packets:14 errors:0 dropped:0 overruns:0 frame:0
          TX packets:14 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 lg file transmission:0
          RX bytes:748 (748.0 b)  TX bytes:748 (748.0 b)
...
usb0      Link encap:Ethernet  HWaddr C0:E3:56:1A:B8:CD
          inet addr:192.168.1.100  Bcast:192.168.1.255  Mask:255.255.255.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 lg file transmission:100
          RX bytes:0 (0.0 b)  TX bytes:0 (0.0 b)

Again, this last paragraph provides the necessary information about the USB network interface.


6.2. Connecting to the Internet

If your GNU/Linux host is part of a local network, then no further work is required. If it is connected to the Internet directly through a modem, then we will have to configure the firewall to do both address translation and to accept the iPAQ connection.

Configuring a firewall is very configuration-dependent. As a guideline, I provide the following /etc/sysconfig/iptables script, which work for the RedHat distribution (it can be adapted to other distributions too):

# iptables config file used by /etc/init.d/iptables
# Authors: Benoit PAPILLAULT & Philippe LUCAS
# Creation: 11/07/2002
# Modified by Michel STEMPIN for USB network

# default policy are not reset before executing lines in this file
# by default a packet goes either to INPUT chain or FORWARD chain
#
*filter
# INPUT chain
-P INPUT	DROP
-A INPUT	-i lo -j ACCEPT
-A INPUT	-i usb0 -j ACCEPT
-A INPUT	-m state --state ESTABLISHED,RELATED -j ACCEPT
#
# list of port that are allowed by default
-A INPUT	-p tcp -m tcp --dport 22 -j ACCEPT
-A INPUT	-p tcp -m tcp --dport 80 -j ACCEPT
#
# send all other packets to syslog
-A INPUT	-j LOG --log-prefix "FIREWALL "
#
# FORWARD chain
-P FORWARD	DROP
-A FORWARD	-i usb0 -j ACCEPT
-A FORWARD	-m state --state ESTABLISHED,RELATED -j ACCEPT
#
# OUTPUT chain
-P OUTPUT	ACCEPT
COMMIT
#
*nat
# PREROUTING chain
-P PREROUTING	ACCEPT
#
# POSTROUTING chain
-P POSTROUTING	ACCEPT
-A POSTROUTING	-o lo -j ACCEPT
-A POSTROUTING	-o usb0 -j ACCEPT
# the SNAT line will be added by the right pppd
# (the one connected to the Internet)
-A POSTROUTING	-s 192.168.1.0/24 -d ! 192.168.1.0/24 -j MASQUERADE
#
# OUTPUT chain
-P OUTPUT	ACCEPT
COMMIT

You may have to adapt this simple script to your needs, as a firewall configuration is based on rule chains that are processed in order. The general idea is to allow traffic between the iPAQ and the GNU/Linux host, to forward traffic from the iPAQ to the external world, translating its address to appear to be the host's address. For more information, I suggest you read the Firewall and Proxy Server HOWTO and the Linux IP Masquerade HOWTO.

Warning

This firewall configuration is very basic and does not provide a bulletproof (although reasonable) setup for your machine. You should really consider writing your own, based on your particular needs.

On the RedHat distribution, You will need to restart the firewall by typing:

# service iptables restart

For other distributions, this is probably something close to:

# /etc/rc.d/init.d/iptables restart

When everything is fine, you should be able to "ping" the iPAQ from the GNU/Linux host, and the other way around. On the GNU/Linux host (press Ctrl-C to stop):

bash# ping 192.168.1.101
PING 192.168.1.101 (192.168.1.101) from 192.168.1.100 : 56(84) bytes of data.
64 bytes from 192.168.1.101: icmp_seq=0 ttl=255 time=2.187 msec
64 bytes from 192.168.1.101: icmp_seq=1 ttl=255 time=1.422 msec
64 bytes from 192.168.1.101: icmp_seq=2 ttl=255 time=1.236 msec
64 bytes from 192.168.1.101: icmp_seq=3 ttl=255 time=1.050 msec

--- 192.168.1.101 ping statistics ---
4 packets transmitted, 4 packets received, 0% packet loss
round-trip min/avg/max/mdev = 1.050/1.473/2.187/0.434 ms

On the iPAQ:

# ping 192.168.1.100
PING 192.168.1.100 (192.168.1.100): 56 data bytes
64 bytes from 192.168.1.100: icmp_seq=0 ttl=255 time=1.6 ms
64 bytes from 192.168.1.100: icmp_seq=1 ttl=255 time=0.8 ms
64 bytes from 192.168.1.100: icmp_seq=2 ttl=255 time=1.5 ms

--- 192.168.1.100 ping statistics ---
3 packets transmitted, 3 packets received, 0% packet loss
round-trip min/avg/max = 0.8/1.3/1.6 ms

One last thing to do is to declare your DNS (Domain Name Servers) on the iPAQ. The best way is probably to copy or mimic the /etc/resolv.conf file from your GNU/Linux host machine. I suggest to enter it on the iPAQ with:

# echo "nameserver first_name_server" >> /etc/resolv.conf
# echo "nameserver second_name_server" >> /etc/resolv.conf

You should now be able to "ping" by its name any machine on the Internet that you know is responding to such requests.

If you are able to "ping" the GNU/Linux host, but not the rest of the world, this may be due to the ip_forward mechanism not being enabled. Try re-inserting the iPAQ or re-launch the ipaqnet script.


Chapter 7. Installing Familiar GNU/Linux

In this chapter, we will install the Familiar GNU/Linux distribution onto the iPAQ.

Provided that the iPAQ is able to access the Internet as described in Chapter 6, it is quite easy, as the Familiar GNU/Linux distribution is made up of packages that can be downloaded and installed directly.

The first thing will be to update the package definitions to match the latest packages available.

We will then run SSH to definitively get rid of the serial terminal and work at full speed using USB.


7.1. Upgrading packages definition

I assume you still have the terminal emulation running, as described in Chapter 3, and that USB networking is working, as described in Chapter 6. In order to update the packages definitions, just issue the following command on the iPAQ:

# ipkg update
Downloading http://familiar.handhelds.org/familiar/feeds/unstable/packages/armv
4--14:14:56--  http://familiar.handhelds.org:80/familiar/feeds/unstable/package
s/           => `//tmp/ipkg/Packages'
Connecting to familiar.handhelds.org:80... connected!
HTTP request sent, awaiting response... 200 OK
Length: 212,734 [text/plain]

    0K -> .......... .......... .......... .......... .......... [ 24%]
   50K -> .......... .......... .......... .......... .......... [ 48%]
  100K -> .......... .......... .......... .......... .......... [ 72%]
  150K -> .......... .......... .......... .......... .......... [ 96%]
  200K -> .......                                                [100%]

14:15:00 (59.24 KB/s) - `//tmp/ipkg/Packages' saved [212734/212734]

Done.
Updated list of available packages in /usr/lib/ipkg/lists/familiar-unstable

Then, upgrade the installed packages to their latest version:

# ipkg upgrade
...
    N or O  : keep your currently-installed version
      D     : show the differences between the versions (if diff is installed)
 The default action is to keep your current version.
*** wlan.opts (Y/I/N/O/D) [default=N] ? y
Configuring pcmcia-cs...Done
Package mount (2.11h-1-fam1) installed in root is up to date
Package shellutils (2.0.11-5) installed in root is up to date
Package wvlan-modules-2.4.18-rmk3 (hh12) installed in root is up to date
Package libncurses5 (5.0-6.0potato1) installed in root is up to date
Package tar (1.13.19-1) installed in root is up to date
Package setserial (2.17-20) installed in root is up to date
Package orinoco-modules-2.4.18-rmk3 (hh12) installed in root is up to date

You may have to enter Y a couple of time to accept modifying some existing files.

One of the first useful package to install is the familiar-postint package, that will provide clock synchronization using the ntpdate command:

# ipkg install familiar-postinst
...
Unpacking familiar-postinst...Done.
Configuring familiar-postinst...Done.
# cd
# ./postinst
...
Familiar post-installation completed successfully.

7.2. Running SSH

You can now forget minicom and the serial line, as you can take control of the iPAQ using the SSHD daemon running on it. The only remaining usage for minicom would be to get a serial bootloader console. To access the iPAQ from your GNU/Linux host, issue:

bash# ssh 192.168.1.101

or

bash# ssh ipaq

if you still have the name definition set up in Section 1.1.2. The first time you use it, ssh will ask you if you want to save the new key: answer yes, then provide the default "rootme" password.

When you want to transfer files, you can issue an scp command from the iPAQ to the GNU/Linux host (or the other way around). One useful file to download will be the /etc/localtime from your GNU/Linux host:

# scp 192.168.1.100:/etc/localtime /etc/localtime

This should update the iPAQ's time to the correct timezone for you.


Chapter 8. Installing Opie

In this chapter, we will install the Opie environment onto the iPAQ.

Provided that the iPAQ is able to access the Internet as described in Chapter 6, it is quite easy, as Opie is made up of packages that can be downloaded and installed directly.


Chapter 9. Reinstalling PocketPC

This chapter is provided in case you are not satisfied with GNU/Linux on your iPAQ, or are forced to switch back to the original operating system. The steps of restoring the original PocketPC and bootloader images saved in Chapter 2 are covered here.


9.1. Restoring PocketPC

First, make sure you have set up a terminal connection, as described in Chapter 3.

You need to reboot the iPAQ. If you have GNU/Linux running on it, this can be achieved by typing:

# shutdown -r now

Another alternative is to push the recessed button at the lower right of the unit with a sharp object.

Warning

Make sure you have bootldr 2.18.01 or higher installed on the iPAQ before proceeding with the following instructions.

Compaq/HP Cambridge Research Labs will fix any units that fail to restore properly, but this should be seen as a last resort solution.

When the bootldr screen appears, press on the "Calendar" button at the lower left corner of the unit to get a serial bootloader console. At the boot prompt, type:

boot> set ymodem 1
boot> load root
loading flash region root
using ymodem
ready for YMODEM transfer...

This command tells the iPAQ to be ready to receive the root image using the xmodem protocol. You just have to feed it from the running minicom window, by pressing Ctrl-A and S. A small popup window will appear, allowing you to choose the transfer protocol. Using the arrow down key, move down to the "ymodem" entry and press Enter.

A file selector window will open, where you need to specify the file to download. Using the arrow right key and pressing Enter, you can go to the directory containing the wince_image.gz you created in Chapter 2. Using the arrow down key, move down to the correct file, and hit space to select the file, then press Enter.

A window will open, displaying the current transfer status. The transfer should take about 20 minutes (yes, it is much larger than GNU/Linux), so be patient. When completed, a beep will awake you, so press Esc to close the window. The following lines should appear:

Looks like a gzipped image, let's verify it...
Verifying gzipped image
......................................;
programming flash...erasing ...
Erasing sector 00040000
Erasing sector 00080000
Erasing sector 000C0000
...
Erasing sector 01F80000
writing flash..
addr: 00040000 data: EA0003FE
addr: 00050000 data: 0F6A0F6A
addr: 00060000 data: 11A0F003
...
addr: 01FA0000 data: FFFFFFFF
addr: 01FB0000 data: FFFFFFFF
verifying ...
calculated crc32 = 0x282F31FE
desired    crc32 = 0x282F31FE
formatting ... done.
boot> 

You can now boot PocketPC by typing:

boot> boot wince
booting wince...
Disabling LCD controller

The iPAQ will boot PocketPC automatically, unless you hold the center of the joypad while pushing the recessed reset button.


Appendix A. GNU Free Documentation License

Version 1.1, March 2000

Copyright (C) 200 Free Software Foundation, Inc. 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.


A.2. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you".

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. (For example, 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.

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 "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and 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 has been designed to thwart or discourage subsequent modification by readers is not Transparent. 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 designed for human modification. Opaque formats include PostScript, PDF, 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 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.4. COPYING IN QUANTITY

If you publish printed copies 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 publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. 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.


A.5. MODIFICATIONS

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:

  1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

  2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).

  3. State on the Title page the name of the publisher of the Modified Version, as the publisher.

  4. Preserve all the copyright notices of the Document.

  5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

  6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

  7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

  8. Include an unaltered copy of this License.

  9. Preserve the section entitled "History", and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

  10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

  11. In any section entitled "Acknowledgements" or "Dedications", preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

  12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

  13. Delete any section entitled "Endorsements". Such a section may not be included in the Modified Version.

  14. Do not retitle any existing section as "Endorsements" or to conflict in title with any Invariant Section.

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.


A.11. FUTURE REVISIONS OF THIS LICENSE

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.