---
name: "pgi-build"
section: "1"
platform: "linux"
package: "pgi"
version: "0.9.6.3"
release: "Debian 3.0 (Woody)"
platforms: ["linux"]
url: "https://new.carta.tech/pgi-build"
---
# pgi-build(1)
generate ISO images containing the PGI Debian installer
## 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 --builder=homer@example.com$ pgi-build -B homer@example.com
```
both do the same thing.
**Note:**
**Most of the defaults listed below are derived from** **the default options file provided with** **the PGI package. Furthermore, most command-line options** **are associated with a variable that is passed into the** **pgi-build process environment. For** **convenient reference, if such a variable is associated with** **a command-line option, it is listed at the beginning of the** **option's description.**
- **-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.**
**Warning:**
-
**When applied against the full Debian archive,** **enabling this option can result in several ISO** **images.**
- **-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.**
**Warning:**
-
**Do** *not* **use this option** **unless you are certain that you know what you are** **doing. Only those with legal rights to the Debian** **name, for instance, are authorized to create official** **Debian CD images for distribution. If you unsure as** **to whether you should be branding your product as** **official, see the --vendor and** **--product options, and seek the** **advice of counsel.**
- **-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.**
**Note:**
-
**If running pgi-build as** **root, try** **/bin/sh.**
- **-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.**
**Warning:**
-
**Use this option with extreme care when** **specifying it in conjunction with the -t \|** **-tmpdir, -M \| --misctmpdir,** **or -o \| --outdir options, or their** **corresponding variables. Specifying** **--clean will remove all files in** **these directories.**
- **--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.**
**Warning:**
-
**Much software that does not satisfy the Debian** **Free Software Guidelines is** *not* **licensed for commercial distribution; enable this** **option at your own legal risk.**
- **--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.**
**Warning:**
-
**Use this option with extreme care when** **specifying it in conjunction with the -t \|** **--tmpdir or -M \|** **--misctmpdir options, or their corresponding** **variables. Specifying --post-clean will remove all files in these directories.**
- **--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.*
**Note:**
**Keep in mind that all configuration files are** **specific to a codename; therefore, you will find them in** **/etc/pgi/***codename.*
- **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:*
```
Welcome to my custom Debian installer!
The system is now installed; have fun!
```
- **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/)*