Copyright © 2002 by Progeny Linux Systems, Inc.
PGI is not just an installer for Debian GNU/Linux, but a system for creating Debian installers. As such, it can be heavily customized, so that two installers may be very different. This document emphasizes the features that should be common to all PGI-generated installers. Vendors of Debian or Debian-based distributions should edit and update this manual to document the interface their PGI-based installer presents to the user.
The PGI installer supports three modes: install, rescue, and a general boot mode for using an existing root filesystem. This document covers the boot-time options used to customize the operation of the modes, provides troubleshooting guidance, and gives a brief description of the operation of the installer.
Specifying install will start the system in its primary mode: installation. This is also the default mode when PGI is started without an explicit mode specification.
A rescue mode is also available. In this mode, PGI's live filesystem may be used to recover a system which is having booting difficulties. This mode allows access to many standard commands for system and network maintenance and troubleshooting, as well as extra utilities such as vi, GNU Parted, GNU GRUB, and many others.
Rescue mode can be useful not only for repairing damaged systems, but also for installing systems in very specialized scenarios. Performing an installation (as opposed to system recovery tasks) via rescue mode is recommended for experts only, since it is not an automated process.
Specifying linux at the prompt will cause the installer to boot its kernel and mount an existing file system from the local disks through use of the root option. This is one (rather awkward) alternative to installing a boot loader.
Note: For the linux/boot mode to work, the kernel used by PGI must have compiled into it all necessary functions for accessing and mounting the root device. This includes such things as IDE or SCSI disk support, the SCSI driver needed for the machine's SCSI controller (if any), and the filesystem driver for the root filesystem (e.g., ext2). Fewer restrictions apply to install and rescue modes because they use an initrd that performs hardware detection and contains kernel modules. If boot mode does not work on your system with the vendor-supplied PGI kernel, use rescue mode instead.
Any options not handled by the PGI installer will be passed without modification into the system environment; http_proxy is one example of such an option.
At boot time, one of the three modes must be selected:
install [install-specific options] [install/rescue common options]
rescue [install/rescue common options] [boot-specific options]
linux [boot-specific options]
Note that the machine platform may influence the process of starting PGI and specifying the above commands; see the appendices for information specific to your architecture.
The following networking options are available:
[dhcp | nodhcp | ip=address | netmask=mask | gateway=address | broadcast=address | nameserver=address | domain=domain_name]
Note: In each case, address should be specified in standard, "dotted-quad" notation for IP addresses (e.g. 192.168.0.23). The mask is not an IP address, but specified using the same notation (e.g. 255.255.255.0). The domain_name is the portion of the machine's fully-qualified host name, excluding the host part. For example, the host part of the fully-qualified name "metis.example.com" is "metis", and the domain part is "example.com".
Details
The dhcp argument instructs the installer to get its network configuration information from a DHCP server on the network interface. The DHCP server should provide the local IP, netmask, gateway, and DNS settings. Note that the dhcp argument is assumed if the livefs option is used with an NFS argument or if the display option is specified (see below).
If the installer hangs while trying to obtain DHCP information, power-cycle the machine and manually specify the network information with the other arguments documented here. Repeated messages like Sending discover... may indicate DHCP problems. (The DHCP server may not be running, may not be reachable, or may not be configured to provide your machine with information.)
Caution |
You can specify network settings manually (e.g., ip) in addition to dhcp, but any configuration parameters sent by the DHCP server will override manual settings. If both dhcp and nodhcp are specified, the last one which occurs is determinative. |
The nodhcp argument instructs the installer to prompt the user for network configuration information early in the installation process.
Caution |
If both dhcp and nodhcp are specified, the last one which occurs is determinative. |
The ip argument configures the network address of the machine. This will be necessary if the local network does not support DHCP and if part of the install process requires network connectivity. (In stock configurations of PGI, network access is only required if the installation medium does not include a Debian package archive containing the packages required for installation.)
The network mask (netmask) identifies those addresses which are considered local to the network segment (i.e. not on the other side of a router).
As with netmask, if all needed installer services are provided locally, the gateway address is unnecessary. Otherwise, specify the address of the local router.
Specifying a DNS server is recommended if the livefs option is used with an NFS argument, if the display option is used, or if a Debian archive server will be used for package download. In each case, nameserver will allow hostnames to be used in place of IP addresses.
This argument specifies the broadcast address for the local network segment. It is not normally necessary to specify this parameter.
This argument usually specifies the domain name of the local network; it is optional and may be used to reduce the amount of typing when specifying an HTTP proxy server address or NFS server name when mounting the live filesystem via NFS. Of course, a DNS server must be usable for name-based server references to work.
The following live filesystem options are available:
[livefs=host:path] [livefstype=fstype]
livefs instructs the installer to mount its live filesystem from an alternative location. Two forms may be specified; the first indicates a device node, such as /dev/hda3, the other uses the NFS network protocol. The live filesystem includes the actual programs to perform the system installation, as opposed to the code which boots the kernel, performs hardware detection, and configures the network, which is always contained on the installation medium. For the device form to work, a filesystem must exist at the specified device node and must contain a top-level directory called live which contains a PGI live filesystem. For the NFS form of this option to work, an NFS server must be running at host, reachable via the network, and be configured to export a live filesystem at path corresponding to your installer medium. Vendors that plan to support this option should prominently document the correct values for host and path.
In the event that the mount command cannot automatically determine the filesystem type, use of the livefstype option in conjuction with this option is suggested.
Note: If the live filesystem cannot be mounted as the user specifies, the installer will fall back to searching for one on the installation medium.
livefstype is used in conjunction with the livefs option to instruct the mount command how to mount the specified filesystem. Valid values include any parameter recognized by the mount command; note that kernel support for the specified filesystem type is also required.
The following options influence the installer's behavior through the process environment:
[http_proxy=http://host:port/] [MIRROR=http://host/directory/] [SUITE=suite_name]
Details
If an HTTP proxy is required to access the World Wide Web, it may be specified via this argument.
Use the Debian package mirror located in mirror_directory on host, instead of the default mirror.
Use the Debian release code-named suite_code_name instead of the default suite.
At present, only one debugging option is available:
[debug]
debug increases the verbosity of the installer to the system console, and launches shells at strategic points in the installation process so that the state of the system can be examined. It is intended for use by those doing development work on PGI, by advanced users who are curious about how the installer works or exactly what it is doing (and aren't satisfied by the log files), and by any user working with a vendor's technical support representative to troubleshoot installation problems.
A few options only make sense for install mode.
[textmode | display=host:servernumber] [prompting= {less | more} ]
The textmode argument instructs the installer to run in text mode. This argument is useful when installing on video hardware that is incapable of raster graphics, or is not supported by the XFree86 4.x X server.
Text Mode Caveats
Running the text mode installer requires the use of parted for partitioning. Familiarity with this application is recommended.
Text mode uses dialog, which is not likely to work across a serial connection.
The display argument instructs the installer to use the X display specified instead of the local machine's X server. The display must specify a host as well as an X server identifier. For example, display=athena:0 will display the installer at the host athena on X server zero (usually the first, or only, running X server). Note that a DNS server must be available to resolve the hostname or the host's IP address must be used instead.
The prompting argument specifies the level of prompting the installer uses during operations like hardware detection. Use of this option is recommended if omitting it leads to undesirable system behavior (hangups, garbled display, etc.) while the installer reports that it is configuring the X server. This option may be set to less or more; the default is less.
Using the following options in conjunction with installer or rescue modes is strongly discouraged, as they will not permit the installer to work correctly. (They both use an initrd as their root filesystem, and provide their own init commands.)
[root=disk-partition-device] [single] [init=path-to-init-program]
The root filesystem to be mounted from the local drive(s) can be selected with an argument like root=/dev/disk, where disk is a partition identifier such as hda1.
Specifying the single argument will pass this parameter to the init program, starting the system in single-user mode.
If the root filesystem's init program is missing, corrupt, or behaving undesirably, an alternative program can be used as init. This could be an init installed outside the regular command search path, or -- more typically for system maintenance and recovery -- the Bourne shell, /bin/sh.
Once the first stage of the install has begun[1], five additional virtual consoles are available for use. Each can be used to gain a shell prompt for investigating the system. The mechanism for switching to the virtual consoles differs between graphical and text installation modes.
In the examples below, F2 may be replaced with Fn, where n is a digit between 2 and 6, inclusive. This is because there is a shell available on each of the virtual consoles, 2 through 6.
To switch to a virtual console, use Control-Alt-F2. The combination Alt-F7 will return to the main status screen.
To switch to a virtual console, use Alt-F2. The combination Alt-F1 will return to the main status screen.
While the installer is running, several files may be examined from a shell prompt via any available system utility like /usr/bin/less.
/var/log/installer.log
/var/log/installer.syslog
/var/log/installer.dmesg
/var/log/installer.ident
/var/log/XFree86.0.log
Except for /var/log/XFree86.0.log, the above files are all copied to the /var/log directory of the installed system at the end of the installation process.
On i386, the syslinux bootloader, which is the first thing the user sees after booting from the CD or DVD drive, provides help screens to synopsize many of the options documented in this manual. There is a boot prompt at which you may type any of the PGI boot commands (install, rescue, or linux), followed by any desired options.
Currently, there is no user-friendly environment like syslinux for the IA-64 platform. The manufacturer's instructions for booting from CD or DVD should be followed. Example B-1 is an illustration of how one model of IA-64 system can be booted into install mode.
Example B-1. Booting from the DVD-ROM Drive on an IA-64 Machine
EFI Shell was selected from the EFI boot menu to get to the Shell> prompt. Then:
Shell> fs0: fs0: on this system denotes the DVD-ROM drive fs0:\> elilo install dhcp |
If Custom Partitioning is selected, or if parted is run via text mode, a boot partition must be established.
This partition should be 64 MB or larger, must be a primary partition, must be of type EFI Boot, and must be called /boot/efi.
"The Linux BootPrompt-HowTo" provides information on additional kernel parameters that may be useful.
The "Debian Installation Manual" describes the standard Debian installer, but may be of value, particularly during the second stage.
[1] | Essentially, the first stage begins when the Live filesystem mounted from... message is displayed. |