1.1. Features

PGI implements several existing technologies to ensure that it is both flexible enough to deal with a broad range of hardware, and compatible with the official Debian installation system. The latter point is important because it should not matter how the user gets Debian GNU/Linux onto his or her computer; what is important is that the resulting system is compatible with any other Debian GNU/Linux system at the infrastructural level.

• PGI uses debootstrap, Debian's official means of retrieving and installing the core components of a Debian GNU/Linux system. Stage 1 of PGI (see Implementing the Second Stage) can be thought of as a "wrapper" around debootstrap; PGI gets the system into a state where debootstrap can be run successfully.

• PGI features both text-mode and graphical user interfaces. The latter uses version 4.1.0 of the XFree86 X server, supporting a wide variety of video hardware at reasonable color depths and resolutions. In cases where the graphical interface is not desired or unsupported by XFree86, a text-mode interface is available and provides the user with the same functionality.

• PGI's graphical user interface autodetects most pointing devices (mice, trackballs, etc.) and video hardware. In most cases, it is not necessary to answer any configuration questions to use the installer's graphical interface — it "just comes up". In situations where manual configuration is necessary, only a few easily-understood questions are asked of the user, to give the GUI the "push" it needs to get going. Alternatively, you can run the graphical interface even when the target machine's video hardware is not supported by the XFree86 X server; simply set the display boot parameter and run the installer on an X server elsewhere on your local network[2].

• Even when the X Window System is unavailable, PGI's text mode spares the Linux novice the intimidation of a shell prompt. The dialog utility is used to provide a friendly, menu-and-button-driven interface to the text-mode installer.

• PGI is largely independent of the Linux kernel version. PGI may be built around an extremely broad variety of kernels; only a few kernel configuration options or mandatory for PGI's proper operation (see Kernel and Module Selection). You can create lean-and-mean kernels for use with PGI, or large, featureful kernels for use on a range of hardware. You can also use PGI with the latest Linux kernel[3], or your own specially-patched version, in the event that the target hardware for installation is not supported to your satisfaction by the stock Debian kernel.

• PGI uses Progeny's Discover hardware autodetection system to automatically detect the correct kernel module or XFree86 server driver to use with PCI, AGP, USB, and PCMCIA devices.

• PGI provides and uses the GNU Parted library and utility for flexible and featureful disk partitioning. A graphical partitioner based on Progeny's Python bindings to the Parted library makes partitioning easy and intuitive[4].

• PGI is architecture-independent. PGI has been designed for portability. In its first release, it supports the Intel x86 and IA-64 architectures. Hooks are in place for developers on other architectures to add support for their platforms without having to make infrastructural changes to PGI.

• PGI is flexible. Not only are many aspects of its behavior customizable at build time (and even run time), but PGI supports the simultaneous development of different "profiles", which are referred to by code names that you select. You can choose between these profiles at build time with a command-line option.

  As an example, imagine that you're responsible for managing a pair of university computer labs. One lab is for general undergraduate use, so you want the machines to have a desktop environment and a large array of applications, like Mozilla, Gnumeric, KWord, Gaim, and Kontour. Another lab is used only by CS students taking Systems Programming courses; some of these guys eschew all windowing systems[5] and want to get straight into their text editors and debuggers. For this audience, you might not ship the X Window System at all, and ensure that Vim, Emacs, Gdb, and User-Mode Linux are present. Once you have set up the profiles for each, you can create ISOs for either at will without needing to shuffle files.

• PGI is network-enabled. For GNU/Linux users in general and for Debian users in particular, the days of being restricted to installing your system from a fixed, physical medium and then having to hurriedly upgrade to the latest patches from your vendor are fast becoming a memory.

  debootstrap is network-aware, and can retrieve the base system from a local disk, a web server internal to your home or office, or directly from an official Debian mirror on the Internet. PGI goes still further, however. Only the earliest phases of installation (the booting of the Linux kernel, loading kernel modules necessary to support the target machine's hardware, and configuration of the network interface) need depend on the installation medium (CD or DVD). NFS can then be used to mount the "live" filesystem inside which the installer proper runs.

  These network installation options allow vendors to update PGI-based installers without replacing the existing CD images.

• PGI is boot-loader agnostic. On the x86 platform, PGI uses GNU GRUB for a friendly, menu-driven boot loader. GNU GRUB also supports a powerful command-line interface at boot time, if the user elects to use it. On the IA-64 platform, elilo is used, and the Linux kernel's interface to EFI variables is used to update the boot menu in the system firmware.

• PGI can generate ISO 9660 images that contain only a PGI-based installer, images that contain the installer plus the packages needed to support your installation profile, or the installer plus a complete snapshot of the Debian package archive. Multiple ISO images are generated as needed.

• PGI-based installers are more than just installers. The installer can also be started in a system rescue/recovery mode, which loads the live filesystem and provides the user with a shell. The live filesystem can be configured to contain practically anything desired, from network diagnostic tools to a full XFree86 installation and even a web browser[6]. The PGI installation medium can also be used a simple boot disk, loading the kernel and getting out of the way, transferring control to the specified root filesystem device.

1.2. What PGI Won't Do (Without Your Help)

As stated above, PGI breaks the installation process down into two[7] stages. The first stage is concerned with establishing a bootable system on the computer. The second stage involves setting up that system; configuration of date and time, network interface card setup, and the XFree86 X server is typical.

Using a network connection and graphical interface for the first stage is not unusual, so if the network card and X server are configured at that time, their parameters are stored and made available in the second stage.

PGI is designed to be agnostic about the second stage, and in fact does not provide one for you, except by way of example. See Implementing the Second Stage for further details.

5.1. Creating Installer-Only PGI ISO Images

By invoking pgi-build with the --installer-only option, an ISO that contains nothing but the files actually implementing the PGI installer itself will be generated. This type of image is the quickest to generate, and will consume less than 100MB of space on the i386 architecture in pgi-build's default configuration. Another advantage of --installer-only builds is that they require no locally-mounted mirror of the Debian package archive.

Note that because the installed packages' dependencies are calculated at build time, not install time, debootstrap can fail if a package to be installed automatically has changed its dependencies by the time the install is run. For instance, if I create a PGI ISO with --installer-only and --suite=unstable, and am using a Debian mirror for package retrieval, my ISO will likely become outdated sooner or later. More specifically, the python2.1 package, for example, may not declare a dependency on libssl0.9.6 at the time I create my ISO — but a few days later, when using my ISO to install a system, if the version of python2.1 available in Debian's "unstable" tree depends on libssl0.9.6, I will be in trouble and the install will fail, becase debootstrap does not know how to resolve dependencies; it retrieves and installs exactly what you tell it to, no more and no less. Therefore, it is wise to use the --installer-only option only in conjunction with a stable package archive, or for short-term and/or experimental purposes. A future version of PGI may perform package dependency calculation at install time, and retrieve newly-required packages from the network. The above situation is not a problem with the other approaches to package placement, since the packages that the installer requires will be retrieved from the ISO, not the network, and their dependency relationships will be static.

5.2. Creating PGI ISO Images with a Partial Package Archive

By default (i.e., if neither the --installer-only nor --complete pgi-build options are specified, a limited set of Debian packages is included in the generated PGI ISO. These packages include whatever debootstrap depends on, a small set of additional packages that PGI requires to be on the system (such as the Discover hardware auto-detection system, and a boot loader), any packages explicitly identified by the builder in the extra_packages and package_list, and finally any dependencies of any of the foregoing packages not already present. Note that extra_packages refers to packages that must, in the builder's opinion, be installed to the system. The package_list is a mechanism for including packages on the ISO, but of which installation is not compelled.

Using pgi-build in this manner requires the existence of a Debian package archive mirror. Use the --build-mirror option or PGI_BUILD_MIRROR variable to identify the location of such a mirror on the local filesystem. (The mirror may be NFS-mounted from a remote host; "local" means only that the mirror must be accessible via a traditional pathname.)

5.3. Creating PGI ISO Images with a Complete Package Archive

If the --complete option is given to pgi-build, a complete set of packages from the Debian distribution is included as part of the (generally more than one) ISO images generated.

Using pgi-build in this manner requires the existence of a Debian package archive mirror. Use the --build-mirror option or PGI_BUILD_MIRROR variable to identify the location of such a mirror on the local filesystem. (The mirror may be NFS-mounted from a remote host; "local" means only that the mirror must be accessible via a traditional pathname.)

6.1. Pre-configuring Network Options

It is important to recognize that if the installer disc includes all needed packages, no network connectivity is required by PGI itself. Even then, it is well worth documenting that fact so that the end user knows not to worry about the boot-time parameters.

If, on the other hand, no packages are included (pgi-build --installer-only), then a network connection will be required. PGI will attempt to contact a DHCP server by default if the user does not provide any networking information and --installer-only was specified by the installer creator.

If your installer image is targetted at a discrete set of users in a common network environment, pre-configuring any necessary HTTP proxy for package retrieval is one way to reduce the chance of user error. Note that it is not necessary to set up an HTTP proxy if your users have unrestricted outbound HTTP connectivity, or if you have configured PGI to use an internal Debian archive mirror that users don't require an HTTP proxy to access. Furthermore, we strongly recommend setting up a DHCP server to serve network configuration parameters to users' workstations. By preparing your network in this way, and by pre-configuring the HTTP proxy and/or archive mirror, users of installer-only PGI discs need not know anything about network configuration to perform an installation[12].

6.2. Documentation for the User

On the i386 architecture, syslinux provides help screens that can be customized.

Since the syslinux help screens are not universally available, and since there is limited room for comprehensive help text, a user manual is provided with the PGI package. You should customize this manual to describe the installer as your users will experience it.

8.1. /etc/pgi/codename

As mentioned in the Overview chapter, PGI can be configured to produce several distinct installer images without having to change its configuration in between. This is achieved by associating each installer configuration (or profile, if you will) with a code name, which is then supplied on the pgi-build command line as an option.

$ pgi-build --codename=home
$ pgi-build --codename=work
        

This flexibility is accomplished through the creation of a subdirectory under /etc/pgi containing the customized input files needed to generate an installer image. The codename may be any name that is useful for you, the installer vendor; it has nothing to do with Debian release code names, which are referred to as suites.

The codename must contain only alphanumeric characters and underscores; it must not start with a number.

For instance, to start developing the profiles in the example above, you could use a recursive copy command to duplicate the existing custom codename directory that ships with the PGI package.

$ cp -a /etc/pgi/custom /etc/pgi/home
$ cp -a /etc/pgi/custom /etc/pgi/work
        

You would then modify the files in each of these directories as needed for the distinct environments.

8.2. /etc/pgi/codename/options

Use this file to define basic parameters for your build. Some examples of variables defined here include the destination directory for the ISO image(s), the kernel version to use, and where to find a mirror of the Debian archive.

Alternatively, you may pass command-line arguments to pgi-build for most of these values. See Options and Environment for a list of command-line options and their corresponding variable names.

8.3. Other Files Under /etc/pgi/codename

See Input Files for a list of the customizable files located here.

9.1. Selecting Debian Package Archive Mirrors

A Debian installer is fundamentally a delivery mechanism for Debian packages; PGI is no different. Debian packages are kept at many locations on the Internet. A large number of locations contain the official distribution; these sites are referred to as "mirrors", since they are clones of a central package archive server which is not publicly accessible[13]. There are also other, generally much smaller, repositories that are not run by or affiliated with the Debian Project, and are typically dedicated to providing Debian packages for a given piece of software or the products of a particular company. PGI uses Debian mirrors in two distinct ways; a mirror is used by the installer itself when a Debian package archive cannot be found on the live filesystem, and the pgi-build process uses a mirror that is mounted on the system used to build a set of PGI-based installation images. The former defaults to Progeny Linux Systems, Inc.'s Debian mirror, archive.progeny.com[14]; it is used if the installer can't find Debian packages on the live filesystem (when it's mounted via NFS, for example). The latter is necessary when running pgi-build without the --installer-only option. Use the --build-mirror option to specify the location of your Debian package mirror. The build mirror may be NFS-mounted.

A local mirror must be available if you are not using the --installer-only option; there is a great deal of internal structure to a Debian package repository that is not accessible through the package retrieval methods used by, e.g., apt. pgi-build requires a local mirror to populate the ISO image(s), because those ISOs will themselves contain package repositories.

$ pgi-build --pgi-mirror=http://archive.progeny.com/debian
      --build-mirror=/archive/debian/ftp
      

9.2. Selecting the Kernel Version To Be Used by PGI

At the time of this writing, there are three versions of the Linux kernel that are both considered "stable" and actively maintained. The earliest, in the 2.0.x series, is nearly abandoned, and cannot be used with PGI since it lacks facilities that the PGI installer requires. The others are the 2.2.x series and the 2.4.x series. PGI supports both of these kernel versions on the Intel x86 architecture and continuing support for both is planned. On the IA-64 architecture, only the 2.4.x series is supported.

Debian makes multiple variants of each kernel version available in Debian packages; these are called "flavors". Each flavor has different configuration options. Some, like the stock 2.2.20 package (kernel-image-2.2.20), take a "kitchen sink" approach, compiling many IDE and SCSI device controllers directly into the kernel. Others lack SCSI support entirely. There are many flavors of Linux 2.4 available for Debian/i386, but only one of them will work with PGI: the -386 flavor. This flavor expects its initrd to be an ext2 filesystem, which is what PGI requires. Other versions use the CRAM (Compressed RAM) filesystem, which is small but not writable. The PGI installer demands a writable initrd. You can use the --kernel-version to specify a kernel version rather than the default (whichever kernel is running on your build system):

$ pgi-build --kernel-version=2.4.18-386
        

If Debian does not provide a kernel package flavor that suits your needs (or PGI's), you can always compile and package your own. For this we recommend the excellent kernel-package Debian package, which makes the process quite easy.

9.3. Identifying and Branding your PGI-Based Installer

pgi-build provides a few options for branding or identifying your images. You can use the --builder option to set the builder email address. The --product option sets the name of the product (default: "GNU/Linux") and --vendor sets the vendor name (default: "Debian").

$ pgi-build --builder=debian-staff@example.com --vendor="Example Penguin Unix Systems"
        --product="Debian GNU/Linux"
        

9.4. Selecting the Temporary Directory Used by PGI

When building multiple PGI profiles, it may be convenient to specify the temporary directory to be used by pgi-build. This is achieved through the --tmpdir option:

$ pgi-build --tmpdir=vanilla-2.4.17-386 --kernel-version=2.4.17-386
        

Other options for controlling where temporary files and output files go are available; see Options and Environment.

9.5. Controlling Cleanup and Setting up Live Filesystems for NFS Usage

By default, pgi-build does not clean any of the directories it uses by default; this is useful if you need to try to recover from a failed pgi-build and are interested in looking at some of the transient files produced by pgi-build or need to keep the live filesystem around for NFS export.

Be very careful when using the --clean and --post-clean options in conjunction with any of the --tmpdir, --misctmpdir, or --outdir options (or their corresponding option variables). The cleanup process can remove files that have nothing do with PGI if these directories are not chosen carefully. For example, it is unwise to specify --clean --outdir=/. The default temporary and output directory names that pgi-build uses are such that it is unlikely you will lose any data when specifying --clean or --post-clean.

--clean instructs pgi-build to remove everything in its temporary directories and output directory before going to work, and in its temporary directories after it finishes (the latter can be overridden with --no-post-clean. In general, after investigating the cause of a pgi-build failure, you should specify --clean so that any configuration changes you make are reflected from the beginning of the build process when you run pgi-build again. Otherwise, you run a good chance of producing a useless installer ISO.

--post-clean instructs pgi-build to not clean up its temporary directories after it finishes. This option will prove useful to those who are confident that their ISO builds are sound and useful, and who have no need to create NFS exports containing a live filesystem for use by PGI.

The live filesystem is found in a subdirectory of the temporary directory called misc/live (if the miscellaneous temporary directory was explicitly set, it is a subdirectory of that directory).

If the live filesystem for a given PGI build is located in the directory /home/frank/pgi/vanilla-2.4.17-386/misc/live on a host called margaret, then the administrator of margaret can add the following line to /etc/exports:

/home/frank/pgi/vanilla-2.4.17-386/misc/live 192.168.0.0/16(ro)
        

In the example above, we provide a read-only export to any machine with an address in the given range. The details of NFS server configuration and /etc/exports management are beyond the scope of this manual, but the corresponding PGI boot-time option to access this NFS export is not:

install nfslive=margaret:/home/frank/pgi/vanilla-2.4.17-386/misc/live
        

The above example assumes that a DHCP server will be available to supply the installing host with network configuration information, including a domain and DNS nameserver to use. Otherwise, the network will have to be configured by the user at install time.

10.1. Examining the Generated ISO Images with Loopback Mounting

Mounting an ISO image as a loopback filesystem will let you look in the image as directory in the filesystem. One reason for doing this is to evaluate the directory structure to ensure the correct packages are on the ISO.

Generally, loopback mounting the image is not necessary, but can sometimes help to track down problems with an image build.

To loopback mount an image, use the following command:

# mount -t iso9660 -o loop,ro image.file /mount.point
        

This command mounts the image file (image.file) to the mount point (/mount.point) as a iso9660 filesystem type in loopback mode.

A concrete example:

# mount pgi-i386.iso /mnt -t iso9660 -o loop
        

10.2. Creating CD/DVDs from ISO Images

There are several applications that will burn an ISO image to a recordable CD or DVD. One of these applications is cdrecord.

In order to use cdrecord, you will need to know the logical location of the recording device ("burner") in a specialized format. cdrecord has an option for locating the device. The following example shows the -scanbus option which identifies the burner as 0,0,0.

cdrecord assumes that the burner is a SCSI device. If you have an IDE burner, you will need to use SCSI emulation by loading the ide-scsi module (modprobe ide-scsi) into the kernel.

# cdrecord -scanbus

Cdrecord 1.10 (i686-pc-linux-gnu) Copyright (C) 1995-2001 Jörg Schilling
Linux sg driver version: 3.1.22
Using libscg version 'schily-0.5'
scsibus0:
        0,0,0     0) 'TEAC    ' 'CD-W512EB       ' '2.0A' Removable CD-ROM
        0,1,0     1) *
        0,2,0     2) *
        0,3,0     3) *
        0,4,0     4) *
        0,5,0     5) *
        0,6,0     6) *
        0,7,0     7) *
scsibus1:
        1,0,0   100) 'QUANTUM ' 'ATLAS V  9 WLS  ' '0201' Disk
        1,1,0   101) 'IBM     ' 'DDYS-T36950M    ' 'S80D' Disk
        1,2,0   102) *
        1,3,0   103) *
        1,4,0   104) 'SEAGATE ' 'ST336704LWV     ' '4301' Disk
        1,5,0   105) *
        1,6,0   106) *
        1,7,0   107) *
        

Once the burner is identified and the ISO image is available, you can record the image(s) to optical disc(s) using a command similar to the following example:

# cdrecord -verbose speed=8 -eject dev=0,0,0 pgi-i386.iso
        

This example records the pgi-i386.iso image to device 0,0,0 at a maximum speed of 8x. cdrecord will provide verbose information about the burn and will eject the disc when the burn is complete.

Once the disc is finished you can then use it to boot a computer for installation.