pgi-build(1)

NAME

pgi-build — generate ISO images containing the PGI Debian installer

SYNOPSIS

pgi-build [option ...]

Description

pgi-build (pronounced ``piggy-build'') is system for creating PGI-based installers for the Debian GNU/Linux operating system. PGI is derived from the installer used in the Progeny Linux Systems, Inc. distribution of Debian. Without customization, PGI produces a minimal Debian system installer on an ISO 9660 filesystem image suitable for burning to recordable CD or DVD media. pgi-build supports an extensive set of configuration options to support the tailoring of installer media to your needs.

Options and Environment

Several options have abbreviated, single-letter forms; when using an abbreviated option that takes an argument, the option argument should be specified after the option and a space character. For instance, the commands:

$ pgi-build [email protected]$ pgi-build -B [email protected] 

both do the same thing.

-B | --builder=email-address

BUILDER; specifies the identity of the builder of this image; the address will be included in the helpfile for syslinux. Default: falls back to, in order: DEBEMAIL, EMAIL, USERID.

-C | --complete

COMPLETE; includes all available packages in the package archive on the generated ISO image(s). Default: off.

-D | --dir=pgi-directory

PGI_DIR; identifies location of the PGI infrastructure. Default: /usr/share/pgi.

-M | --misctmpdir=miscellanous-temporary-directory

TDIR; specifies directory to use for transient temporary files. PGI uses loopback mounts in this directory, so it must be on a filesystem capable of handling those (i.e., not NFS). Default: subdirectory of BASETMPDIR called misc; see -t | --tmpdir.

-O | --official

OFFICIAL; marks the image as ``official'' for purposes of apt's CD methods. Default: off.

-P | --pgi-http-proxy=URL

PGI_HTTP_PROXY; identifies location of HTTP proxy server by URL. This option should be used when PGI-based installer media are being distributed in a controlled environment (e.g, within one company or organization) where an HTTP proxy is required for external web access. Note that an HTTP proxy URL often includes a port number, in which case the URL should be in the format: http://hostname:port/. Also note the trailing slash. Default: empty.

-V | --release-version=release-version

VERSION; specifies a version number for the product being generated. Default: 3.0 (for the Debian ``woody'' release).

-a | --additional-archives=additional-archives

OTHER_ARCHIVES; reserved for future expansion. Default: empty.

-c | --codename=release-code-name

CODENAME; designates a product code name for generated ISO images. This is used as the subdirectory of /etc/pgi within which to search for customization information, such as the options file to set default values for the PGI system. Default: custom.

Alphanumeric characters and underscores may be used, but the first character may not be a digit.

-d | --debian-version=debian-version

DEBVERSION; specifies the version number of underlying Debian distribution. Default: VERSION; see -V | --release-version.

-h | --help

Displays a brief usage message for pgi-build to standard output and exits.

-i | --installer-only

INSTALLER_ONLY; generates an ISO image including only the installer, and excluding Debian package archives. Default: off.

-k | --kernel-version=kernel-version

KERNEL_VERSION; indicates version of Linux kernel to use for installer and installed system. Default: the output of uname -r.

-m | --pgi-mirror=mirror-directory

PGI_MIRROR; specifies location of Debian package archives as used by the running installer (not pgi-build itself). Default: http://archive.progeny.com/debian.

-o | --outdir=output-directory

OUT; identifies location where generated ISO image(s) should be deposited. Default: subdirectory of BASETMPDIR called out; see -t | --tmpdir.

-p | --path=execution-path

PGI_PATH; set the environment variable PATH for use by the pgi-build process. Default: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin.

-r | --gain-root-command=command

SU_CMD; indicates command with which to run the parts of the pgi-build process that require root privileges (e.g., loopback mounting of filesystems). Default: sudo.

-s | --suite=distribution-suite-name

SUITE; specifies name of Debian suite upon which the images are based (e.g., potato, woody). Default: woody.

-t | --tmpdir=temporary-directory

BASETMPDIR; specifies the directory where all files generated by pgi-build are written. Default: a subdirectory of TMPDIR (or the current directory) called pgi- followed by the username of the invoking user (also see -u | --username).

-u | --username=username

USERID; specifies the username used by the BUILDER and BASETMPDIR variables. Also see -B | --builder and -t | --tmpdir. Default: output of whoami.

-v | --version

Prints the version of pgi-build to standard output and exits.

--build-mirror

PGI_BUILD_MIRROR; specifies the location of a mounted filesystem containing a mirror of the Debian package archive to be used in the creation of Debian package archives on the ISO image(s). Note that HTTP or FTP access to a Debian mirror is insufficient for the purposes of this option. An actual mirror must be available, though it can be NFS-mounted. Default: /archive.

--clean

Indicates whether to clean the temporary directories before and after building the ISO image(s), and whether to clean the output directory before building. (Also see --post-clean.) Default: off.

--include-nonfree

NONFREE; indicates that unofficial Debian packages that do not meet the Debian Free Software Guidelines should be included in the package archives on the ISO image(s). Default: off.

--include-source

INCLUDE_SOURCE_PACKAGES; indicates that Debian source package archives should be included on the ISO image(s). Default: on.

--no-clean

Inverts --clean; see above.

--no-include-nonfree

Inverts --include-nonfree; see above.

--no-include-source

Inverts --include-source; see above.

--no-post-clean

Inverts --post-clean; see below.

--not-complete

Inverts -C | --complete; see above.

--not-official

Inverts -O | --official; see above.

--post-clean

Indicates whether to clean the temporary directories after building the ISO image(s). Overrides --clean at the end of the build process. Default: off.

--product=name of PGI-based

product" 10 PRODUCT; specifies the name of the PGI-based product being generated. Also see --vendor. Default: GNU/Linux.

--subdir=subdirectory

Invokes only a section of the pgi-build process; valid values are subdirectories of --dir. For advanced usage. Default: none.

--target=subdirectory Makefile

target" 10 Invokes a specific PGI Makefile target; valid values depend on the --subdir option argument. For advanced usage. Default: none.

--vendor=name of vendor/distributor

VENDOR; specifies the name of the PGI-based product vendor. Also see --product. Default: Debian.

--with-debian-debootstrap

DEBIAN_DEBOOTSTRAP; indicates that pgi-build should generate ISO images using the version of debootstrap installed on the system, instead of PGI's own forked version. Default: off.

--without-debian-debootstrap

Inverts ---with-debian-debootstrap; see above.

Other Environment Variables

Other environment variables of interest used by pgi-build but not directly accessible through command-line options include:

ETC_DIR

Automatically set to /etc/pgi/codename.

SYSLINUX_OPTIONS

Options to pass to syslinux. Only useful on the i386 architecture.

COPYLINK

Indicates whether files from the PGI_BUILD_MIRROR should be copied or hardlinked. If set to 1, copy; if set to 0, create hard links. Default: 1.

More advanced options are documented within the stock /etc/pgi/custom/options file. However, such options should be changed only with great caution.

Input Files

PGI is highly configurable through the editing of its configuration files. In addition to the variables set in the options file, documented above, there are several files that handle other aspects of the created installer, and permit customization of the installer's content. Many of these files contain internal documentation and commentary to aid you with your customizations.

extra_packages

This file contains a list of Debian package names, one per line, that should be retrieved and installed when the system is being bootstrapped. The packages are installed and set up on the target system after debootstrap runs, but before the target system is entered with the pivot_root() system call.

live.devices.list

This file contains a list of device names, one per line, that should exist in the live filesystem's environment (thus, the installer's environment). This does not affect the initrd or the target system, and the device must be in a format recognizable by MAKEDEV.

live.dirs.list

This file contains a list of octal file modes and directories, one per line, that should exist in the live filesystem's environment (thus, the installer's environment). The mode comes first, followed by a space, followed by the absolute path name of the directory desired.

live.files.list

This file contains a list of files that exist on the system hosting the PGI build, and which should be copied into the live filesystem. The live filesystem has no /usr directory, and is not FHS-compatible in general for space efficiency. The file format is one pair of filenames per line, with the source filename on the host system followed by a space and then the destination filename on the live filesystem.

logoicon.xpm

This file contains an X pixmap (XPM) which is to be used by the graphical installer for presentation in the GNOME Druid that is used in the user interface. It should be kept fairly small; 48 pixels square is a good size. XPM is a color image file format which supports transparency (but not alpha channel).

messages

This file contains the text that is to be shown to the user at the starting and ending screens of the first-stage installer. If this file is missing, some generic, hard-coded fallback text is used instead. The format of this file is the literal text to be used, surrounded by HTML-style tags. At present, the only defined tags are "start" and "end". For example:

<start> 
Welcome to my custom Debian installer! 
</start> 
<end> 
The system is now installed; have fun! 
</end> 

package_list

This file contains a list of supplementary Debian packages, one per line, to be included in the Debian package archive on the ISO image(s). This file is ignored if the INSTALLER_ONLY or COMPLETE options are set. Note that it is not necessary to list here any packages that are already listed in extra_packages, depended upon by debootstrap, or depended upon by any of the packages in the aforementioned groups. Thus, it serves mainly as a convenience for the user. (Especially when the network is unavailable or unreliable, and the compelled installation of the packages named in this file is not desirable.)

postinst.sh

This file is a POSIX shell script containing whatever housekeeping and setup is necessary and desired to prepare the second stage (configuration stage) of the system installation. When this script is run, the target system has been initialized and all necessary packages for bootstrapping, as well as all packages from extra_packages have been unpacked and configured. This file is commonly used to write or copy an init script to the target system's /etc/rcS.d/ directory, which will take control of the system when the target system runs. Such an init script should ensure that is disables itself in some manner after running succesfully so that it does not run every time the system is booted.

preinst.sh

This file serves a similar function to postinst.sh, but runs before the target system has been installed; indeed, even before the installer proper has itself run. The target system is not initialized, and the target disk drive may not even be partitioned. Make no assumptions about the state of the system beyond what is known about the initrd and the live filesystem when writing this script.

root_window.xbm

This file contains an X bitmap (XBM) which is to be drawn on the screen when the graphical installer first initializes (i.e., when the X server launches). XBM is a monochrome image file format and does not support transparency. The file will be rendered with a white foreground and a black background, and will tile the root window. A good image size is 160x120, because it fits nicely into both possible resolutions that the graphical installer may come up in: 640x480 and 800x600. (At 160x120, the image's aspect ratio matches that of the display, and the image can be projected on both axes an integral number of times.)

root_window.extension

This file contains an image in any format supported by the xloadimage program. If the color depth of the root window is greater than four bits, this image will be drawn on the screen when the graphical installer first initializes (i.e., when the X server launches). The image will tile the root window. A good image size is 160x120, because it fits nicely into both possible resolutions that the graphical installer may come up in: 640x480 and 800x600. (At 160x120, the image's aspect ratio matches that of the display, and the image can be projected on both axes an integral number of times.)

sources.list.dist

This file contains an APT sources.list file for installation to the target system. It should include any desired Debian package repositories. See the source.list manual page for more information on the format of this file.

syslinux.screen*.txt.in

These files, numbered 01 through 10, correspond to the screens that the syslinux boot loader for the i386 architecture displays upon the press of the various function keys. Use the existing examples as a guide. Note that the strings @DATE@, @BUILDER@, @PGI_VERSION@, and @VERSION@ get expanded (the first to an ISO 8601 date string), and the value of the corresponding pgi-build variables described above, respectively, before these files are written to the emulated floppy image used for booting.

These files are not presently useful for the ia64 architecture.

Output Files

ISO image(s) whose names are dependent on how PGI was invoked, in OUTDIR. For example, when generating an installer-only ISO image, the codename and architecture are included; e.g., custom-installer-i386. When generating ISO image(s) with Debian package archives on them, the suite name, the machine architecture, and a disc number are included; e.g., woody-i386-1.iso.

Authors

PGI includes a derivative version of YACS, by Raphaël Hertzog, and a derivative version of debootstrap, by Anthony Towns.

PGI was written by Eric Gillespie, Jr.; Adam Lazur; Jeff Licquia; Ian Murdock; and Branden Robinson. John R. Daily, Steve Hunger, and Steven Schafer contributed to the documentation.

See Also

Creating Debian Installers with PGI (link to URL http://hackers.progeny.com/pgi/guide/)