Notes on configuring Puppy

Updated: 5 Nov. 2003

I built Puppy for myself. I have standalone PCs and I connect to the Internet via dialup through a conventional analog telephone line. I am just getting into experimenting with LAN configurations, and v0.7.4 has DHCP and Samba clients.

When I compiled the kernel, I got a big folder of driver modules, but I only put some of them into Puppy. A general selection, that I thought would work on a wide range of hardware. However, I do have the original modules (a whopping big 24M uncompressed) for anyone who wants it.

I have written a web page that explains the steps that Puppy goes through when booting up. Read this and you should be able to see where any changes are required for your system. The most relevant configuration file is /etc/rc.d/rc.local0*, that loads the appropriate kernel drivers.

In the case of Ethernet, I have included the 8139 driver, as that's what I've got, but I also threw in the ne2000 driver, which will work with any Ethernet card. I put in a reasonable selection of sound drivers, not just my own chip, as sound is something that you will want to have working.

You can see all of the loadable drivers that are available: go into /lib/modules/2.4.18-14custom/ and there they are. You will see also in /lib/modules/ that I have included the file "config_<date>" -- this is the configuration file that I used to compile the kernel. It is very helpful to look through this to see what is built in to the kernel and what is a loadable module.
For example, the kernel has the minix, ext2, umsdos, msdos, vfat and iso9660 filesystems built-in, so no need to load any modules to mount partitions with these filesystems.

Here is my Puppy Startup page (out-of-date!).

If you want to fiddle with the configuration settings for the Fvwm95 window manager, you'll find it at /root/.fvwm95rc.

Configuration files for other apps are also to be found in /root.

Documentation for all applications is to be found in /usr/share/doc, but you can get to it very easily from the "Start" button then click "Help".

All configuration files are inside the /root folder. As the home device is mounted as /root, any changes you make will be permanent.

Boot customisation

Puppy now has a "Remaster live-Puppy CD" program. This is a script that enables you to customise Puppy and burn another live-Puppy CD.

"Remaster live-Puppy CD" is very easy to use:

  1. When you boot the PC with the live-Puppy CD inserted, make sure that a blank floppy is also inserted in the floppy drive, and be sure that your PC BIOS is setup to boot from the CD drive first.
  2. Go to the "Start" button, choose "Utilities" and click on "Remaster live-Puppy CD" menu item.
  3. Follow the easy steps of the script.

...a new live-Puppy CD will be burnt.

Live-Puppy has a file called "isolinux.cfg" that can be customised. The "Remaster live-Puppy CD" program will guide you through this, but you may also like to read about it here.

For booting from a USB Flash card, the configuration file is "syslinux.cfg" and these notes apply to that as well.

Before you go ahead and create a CD, there is some very simple customisation that can be done. The file isolinux.cfg looks like this:

default vmlinuz root=/dev/ram0 initrd=image.gz
append ramdisk_size=49152 initrd_archive=minix PHOME=fd0

These are commandline arguments that Isolinux will pass to the Linux kernel when it boots, however there are five, PHOME, PSLEEP, PKEYS, PROOTFS and PFILE that get passed right through to the Puppy startup scripts as environment variables.

PHOME This specifies the device/partition that will be mounted at /root, that is, will be your home folder where all your data can permanently reside. The default is the floppy disk (fd0).
PSLEEP This specifies a sleep time, in seconds. This is required if your home device is a USB device, typically 25 seconds is needed. Note that if you define this variable and do not define PHOME, Puppy will automatically search for sda1 and sda2.
PKEYS The keyboard layout for a country. Default is "us". Choices are: be br cf de dk es fi fr gr hu it jp no pl ru se uk us
PROOTFS Filesystem to be mounted on /root. Default "umsdos". Allowed choices are umsdos, minix, ext2, ext3. With v0.7.6, reiserfs may also work (untested).
PFILE A file will be mounted on /root. If PHOME not specified, Puppy will automatically search for a vfat, ext2/3 or reiserfs partition (in that order) to use, that is, to create the file on. The format is "PFILE=name-password-size", for example "PFILE=pup0-none-131072". A password of "none" means no password and the filesystem is not encrypted. The size of the filesystem in this example is 131072K, which is 128M.
The example for PFILE shown above is the setting for the live-Puppy v0.7.6 CD.
The filesystem for the file ("pup0" in example) will be ext2 unless PROOTFS is specified. If you want a password, that is, an encrypted filesystem, do not use a journalled filesystem (ext3 or reiserfs). If you use minix for the file, it must be no bigger than 64M.

The opportunity here is that if you have a spare partition somewhere, you can use it. However, by default it must be formatted as a MSDOS or VFAT filesystem and should be empty (no files in it) --but Puppy doesn't care if there are other files already in it. As you can see from the table though, if you have a spare partition with minix or ext2/3 filesystem, you can use that (my personal experience is that if you have a choice between ext2 and ext3, always go for ext3, as it is much more reliable).
If you are just evaluating Puppy for the first time, don't bother, leave isolinux.cfg as-is.

Note, in theory, you could mount the Windows vfat partition (usually hda1) on Puppy's /root folder, and Puppy will of course create all sorts of folders and files in it ...but, will Windows still be bootable? Probably, I have never tried this. I don't think that any of Puppy's folders and files would conflict with existing Windows folders and files ...give it a go at your own risk.
I think that it is possible to create a folder in a Windows partition and make Puppy mount that folder as a partition onto /root, but I have never investigated how to do this.

So, leave the isolinux.cfg file alone for your first evaluation of Puppy. If you don't have a (blank formatted) floppy disk inserted when booting Puppy, no problem, you will still have a home directory, except that it is in RAM and isn't permanent.

...later, you can use the "Remaster live-Puppy CD" to customise Puppy.

The ability to remaster the CD direct from inside Puppy is very convenient. One bit of advice: the live-Puppy CD ships with "PFILE=pup0-none-131072", which means that the file "pup0" is 128M. This gives you a 128M ext2 filesystem mounted on /root, what we call the "home device". However, that is a somewhat minimal size, and if you want to make it bigger, be sure to use a different filename also, as when Puppy boots he will see that "pup0" already exists and won't make a new file. So, something like this: "PFILE=pup1-none-524288" will create file "pup1" of size 512M. If you want to specify that it must be created on a particular partition, "PHOME=hda1" will use /dev/hda1, as long as it is a vfat, ext2/3 or reiserfs partition.

Useful titbits of info: 48M = 49152K, 64M=65536K, 128M=131072K, 512M=524288K, 1G=1048576K. Puppy v0.7.4 uses a 64M ramdisk, v0.7.6 uses only 48M.

Sharing files with Windows

By default, Puppy mounts the home device (flash card, floppy disk, etc) onto /root as a UMSDOS filesystem.
What this means is that the home device is still an MSDOS filesystem from Windows' point of view, but is a UMSDOS filesystem from Puppy's point of view. UMSDOS is enhanced with file permissions, create/modified/last-accessed dates, long filenames and symbolic links.

Note that with v0.7.4 you have a choice of filesystem to mount on /root, and the remaster-cd program takes you through this step by step (see "Start" button then "Utilities").

For the default of UMSDOS, when you boot into Windows, you can look at the home device and you will see all the files that Puppy saved. For example, you can see the configuration files and the email messages. Windows sees the home device as just a MSDOS filesystem, more specifically as VFAT, meaning Windows can save files with long filenames onto the home device. Any file that you save from Windows, will be there in your /root folder when you boot Puppy. This interchangeability is a fantastic feature of Puppy.

Now for the downside. Long filenames do not transfer between Windows and Puppy. A long filename saved when in Windows, will appear to Puppy in the famous 8.3 format. That is, it will be truncated (they refer to it as "munged"). Same thing in the other direction.
Note that the long filename given when inside Puppy, or that given when inside Windows, will not be actually changed. It will just appear munged when you are in the other operating system.

As an example of this, Sylpheed email files are kept in a folder named ".sylpheed" -- over in Windows, this will be munged into the 8.3 format, and becomes "_SYLPHEE.{_I", which is very odd indeed. Don't rename these odd-looking files and folders, as you will upset Puppy!

Note that an enhanced version of UMSDOS is under development, called UVFAT, that will transfer long filenames between Windows and Linux.

Sharing files with other Linux distros

No problemo. For the example of /dev/sda1 being the home device, just type this (assuming the default filesystem type being umsdos):

# modprobe umsdos
# mount -t umsdos /dev/sda1 /mnt/flash
# umssync /mnt/flash

The first line is if the kernel doesn't have UMSDOS filesystem support built-in, but loadable as a module.
The second line presumes that directory /mnt/flash has already been created. Substitute "sda1" with whatever is Puppy's home device.
The last line is absolutely essential if you have previously accessed the home device from DOS/Windows. It synchronises the MSDOS and UMSDOS filesystems. umssync* is part of the UMSDOS package and is probably already installed in your Linux system. If you need to download the package, the UMSDOS homepage is here:

The image.gz file is a Minix filesystem, and you can use a loop device to mount it. Umm, let's see, something like this:

# modprobe minix
# cp /mnt/flash/image.gz image.gz
# gzip -d image.gz
# mount -o loop image mount-dir

How to make changes to image.gz

You can do it from inside Puppy. I have created a shell script, called save2image* (note that I often append an asterisk to denote an executable file, and a "/" to denote a directory). From the commandline (that is, inside the rxvt terminal emulator), type this:

# save2image

IMPORTANT: This script is obviously not going to work for live-Puppy. The script is written with the requirement that the home device be writable and have image.gz file in it, that is, boot device and home device is the same. flash-Puppy meets this requirement, as the boot device is also the home device, and it is writable. live-Puppy is an example where the boot device (the CDROM) is different and not writable.

The image.gz file is read off the home device and uncompressed into another ramdisk (/dev/ram1), and you are given the opportunity of copying across any files you wish, then the ramdisk (/dev/ram1) is compressed and written back to the home device.

In the case of cd-Puppy, you can create a new image.gz and then follow the instructions on the cd-Puppy page for creating a new ISO image.

There is a catch with using the save2image* script: you will need a PC with 256M of RAM. There are other ways of doing this, but this is my first take on it.

One criterion was that I wanted to keep the original image.gz in as pristine a state as possible. So, if you mess up the Puppy on the ramdisk (/dev/ram0), it won't matter. You can keep a very tight control on what gets written back to the boot device.

However, it is best to avoid using this script. It's ok for experimenting, however, when you next download a new image.gz from the Puppy website, your changes will be lost. Therefore, I plan to document another way to do it -- any changes, such as an application that you have added to Puppy, can be saved as a separate compressed file on the boot/home device, and automatically expanded and installed when Puppy boots.

Note, I do intend to integrate save2image into the "Remaster live-Puppy CD" script.


The "symbols" have been stripped out of all files in Puppy, which reduces files to the smallest possible size. This has also been done to shared library files, but this means that if you bring some other application into Puppy it may not work. The application may have to be compiled with the same versions of the library files, and in some cases also the same kernel version.

I used Red Hat 8.0 as host for building Puppy. Other shared libraries such as neXtaw will also need to be the same version that I used, and I'm not sure, but may also need to be compiled with the same compile-options. Stay tuned, I'll document this more fully soon.
Note, I may go over to Slackware, as Red Hat is designed for a i686 class of CPU and I want Puppy to be able to run on i586 or even i486 CPUs.