Barry's Universal Gronkulator

BUG uses the OpenZaurus operating system, rather than the one that came with the Z. In the course of installing it, the existing contents of the Z will be erased. If you have anything on there you want to keep, copy it off before you start.

If something goes wrong during this replacement it can render your Zaurus incapable of starting. Should this happen, don't panic. Repeat the installation from the beginning. If worse comes to worst, you can put the original operating system back. No harm no foul.

OS Layout

We are using the version of OZ that devotes all internal RAM to use as working memory, rather than setting half aside for program storage as usual. This gives us needed additional memory that will be used by the various daemons we'll be installing later. It also enhances ruggedness and security.

Boot Cards

Although the OS is installed on the Z's internal flash, and it can be run there (in fact, for certain operations you must run it that way), BUG actually runs from an OS image stored on the SD card. We call SD cards used this way "Boot Cards".

A boot card is created by cloning the OS image that exists in the Z's internal storage. When the Z is booted with a Boot Card in place, the image on the card is the one being executed. Changes made to the system apply only to the installation on the Boot Card. You can set up multiple Boot Cards, each of which have their own mix of installed applications and data. It's like having multiple "virtual BUGs".

To maximize available space, the internal storage is mounted read-only (on /mnt/root), and symbolic links are used on the Boot Card to point to much of the internal image. We have run occasional problems with this, when programs expect to be able to write to files in unexpected directories. If this happens to you, delete the relevent symbolic links on the Boot Card and copy the files they pointed to over, instead. Oh, and please tell us what you did so that we can adjust our scripts accordingly.

Robustness & Security

Since the OS runs entirely in nonvolatile memory, should there be a catastrophic power failure the Z will not forget any of your data or programs. When power comes back, so does the system.

New cards can be initialized in the field, away from the desktop or internet. Accomodating unexpected guests has never been easier.

Security is enhanced because your data is stored on a small, fragile card. It is trivial to quickly destroy or hide (even swallow!) it to prevent unwanted data disclosure. We store our private encryption keys on BUG instead of our desktop computer, for example. This prevents the theft of the keys through someone accessing our desktop, but still allows us to use the keys there through the use of an NFS or Samba mount.

Downsides

This scheme does come with a couple of downsides. Flash is significantly slower than RAM, and running the OS from flash will hurt performance. Also, flash memory wears out a little each time you write to it. Running the OS from flash will result in more than the normal rate of card wear, and so your cards will fail sooner. Neither of these problems are huge ones, as performance will remain acceptable and the cards will still last a long time (one of ours has been used as the primary OS card for two years now, and it's still going strong.)

Creating the Installation Card

You must use a compact flash memory card to install the new OS. The card must be formatted as FAT. Lucky for you, this is how they come from the factory so unless you've messed with it, everything's probably fine. If you have messed with it, you'll have to reformat it to FAT. Be sure this card is blank.

We permanently devote a 64MB card for this purpose. It's large enough to hold all the installation files and additional application packages so that the system can be rebuilt from nothing to a functional level in the field. Enough space is left over that the card is also sometimes useful to exchange files with systems that can only read FAT cards (such as Windows), since all our other cards are formatted ext2.

The installation files

We have assembled a collection of application, configuration, and whatnot files to make the process as easy as possible. All of our instructions assume various files from this collection at various times, so you gotta have it.

1. Download the installation files: bootcf.tar.gz
2. Unpack it into the card. The files initrd.bin and zImage must be in the root directory of the card.
3. Poke around the various files, particularly the configuration files in /config. There's stuff in those things you'll probably want to change.

The OS that came in the archive is OpenZaurus 3.5.2, the 64-0 memory configuration. If you want something different, just replace the initrd.bin and zImage files with the ones you want. But you really want the 64-0 one.

Installing the OS

1. If you do not have copies of your factory ROM, get the lastest ROM here. Download the "ROM upgrade".
2. If the Zaurus is the only way you have to write to CF, then get a second CF card ready, following the instructions for the "ROM Upgrade". You probably won't need it, but better safe than sorry. If you get into trouble, insert this second CF into your Z and follow the installation procedure in the intructions.
3. Remove the Zaurus from its docking bay.
4. Plug the docking bay's power cable directly into the Z. This is essential: your battery won't have enough juice to do this job.
5. Remove any SD card.
6. Insert the installation card.
7. Move the switch on the back of the Z to "replace battery".
8. Remove the battery cover.
9. Open the Z's keyboard cover.
10. While holding down both the "c" and "d" keys on the keyboard, use the Z's stylus to press the recessed reset switch under the battery cover. Yes, this takes dexterity!
11. Release the keys. If you did everything right, then both the email and battery LEDs on the front will light up and stay lit. If this doesn't happen, be sure that the CF card has the initrd.bin and zImage files on it (in the root directory), and it is inserted. Try it again.
12. Wait. This will take a while. Eventually, both LEDs will turn off, indicating that the procedure is complete.
13. Press the recessed reset switch again.
14. Put the battery cover back on.
15. Move the switch on the back to "Normal Operation".
16. Remove the Installation Card for the initial boot.
17. Turn on the Z.
18. The first boot takes longer than normal, so have patience. Eventually, the GUI will start and will walk you through a set of screens for you to fill in basic information. Do so. When you are asked whether or not to enable the Documents Tab, choose to keep it disabled.
19. Put the installation card back in (the rest of these pages assume it's there.)

Congratulations! You're now running OZ 3.5.2!

Finalizing the Installation

At this point, you have a nice, fresh OZ installation running. This installation is the one that will run whenever you boot the Z without an SD card installed. It's also the one that is copied when you initialize a new Boot SD card, which we'll be doing in a moment. Any changes you make now will also exist in all new boot cards you make, so now is the time to set any default configurations we want. All data entered now will be available to anyone in possession of the device (regardless of boot card), so you probably don't want to put any private keys or passwords on yet.

USB Networking

First, we set up the USB networking. This is mandatory, and allows for communication between the docked Zaurus and the desktop it's docked to. The desktop will also route TCP/IP traffic to your LAN and internet.

In our setup, the USB is subnetted as 192.168.129, and the desktop computer performs masquerading to route traffic to the LAN. You can find instructions for how to configure your desktop configuration here (You want the "<operating system> Connectivity" document that matches your OS.)

UPDATE: We have changed our desktop installation to Debian Sarge. The release we're using has a problem that prevents USB networking from happening easily. You can fix this by adding this line to /lib/modules/2.6.8-1-386/modules.usbmap:

usbnet 0x0003 0x04dd 0x9031 0x0000 0x0000 0x02 0x00 0x00 0x02 0x06 0x00 0x0

Since we have already done the desktop side of things, all we have to do is configure the Zaurus:

1. Turn on the Z and put in the cradle.
2. Run Network Settings, tap on usbd0, tap Configure
   
3. Select "Automatically bring up"; deselect DHCP; enter the IP address information. For us (and probably you), set the IP address to 192.168.129.201, subnet mask to 255.255.255.0, gateway to 192.168.129.1, and the DNS to the addresses of the DNS servers you use.
   
4. Confirm that everything is working by sending a ping from your desktop to 192.168.129.201. If that succeeds, then open a terminal on the Z and try pinging 192.168.129.1 and "google.com". If everything worked, then you're ready to move on.

Establishing an SSH connection

Now that you have the connection working, we suggest that you open an ssh session to the Z and do the majority of the rest of the installation procedures from the ssh command line. It's tons easier. We won't be putting a telnet server into place (for security reasons), so use ssh instead. From your desktop, ssh to 192.168.129.201 and log in as "root". You don't need to enter a password - just hit return (we'll fix this in a minute).

User settings and File System Tools

1. Make sure the Z is docked, can access the net, and has the Installation Card inserted.
2. Change the root password (use the passwd command)
3. Execute: sh /mnt/cf/bin/mkinternal.sh

Some tools were installed to the internal flash:

• Replaced opie-packagemanager with opie-aqpkg
• Installed missing timezone files
• Installed FAT tools (mkfs and fsck for FAT)
• Installed ext2 tools, and all the standard unix fs programs

You can now boot without a boot card and perform filesystem maintenance on SD cards. You should not have to repeat this process again. From this point on, if you mess up the installation process, then at worst you'll have to begin at "Creating the Boot Card" below.

Creating the Boot Card

This is the SD card that will hold the OS and many of the applications you'll be running. For BUG, we're using a 64MB card -- but bigger is always better. With a card this small, we don't have the space to install some superhuge applications such as Konqueror, Apache+php, XMMS, etc. We use a CF applications card to hold stuff that won't fit. If the SD card is big enough, it will ALL fit.

1. If the Z is running on an SD card, use the shutdown app to shut down the Z, remove the card, then turn the Z on again.
2. Make sure the Installation Card is inserted.
3. Insert the SD card that will become the new boot card.
4. Execute: sh /mnt/cf/bin/newsd.sh
5. Execute: sh /mnt/cf/bin/mkboot.sh
   (This will take a while)
6. Reboot the Z

Once the reboot is complete, you should be running on the SD card. You might get a new media screen that looks like this:

Deselect everything and it won't bother you again.

Start an ssh session (or Opie Terminal) and execute "mount". If this line is in the report, then call it a job well done:

/dev/mmcda1 on / type ext2 (rw)

1. Introduction
2. Installing OpenZaurus
   • OS Layout
   • Creating the Installation Card
   • Installing the OS
   • Finalizing the Installation
   • Creating the Boot Card
3. Basic Configuration
4. PDA Configuration
5. Internet Clients
6. Daemons
7. Internet Servers
8. Infrared Subsystem
9. 802.11 Subsystem
10. Bluetooth Subsystem
11. Other Networking
12. Other Software
13. Multimedia Cards
14. Application Cards