Using the PGI Debian Installer

$Progeny: usermanual.xml,v 1.47 2002/06/17 15:57:59 branden Exp $

Table of Contents
1. Introduction
2. Boot-Time Commands
2.1. Options for Install and Rescue Modes
2.1.1. Networking Options
2.1.2. Live Filesystem Options
2.1.3. Environment Options
2.1.4. Debugging Options
2.2. Options Specific to Install Mode
2.2.1. Text Mode
2.2.2. Remote Display
2.2.3. Prompting Level
2.3. Options Specific to Boot Mode
2.3.1. Specifying a Root Partition
2.3.2. Starting in Single-User Mode
2.3.3. Using an Alternative init Program
3. Troubleshooting
3.1. Virtual Consoles
3.1.1. Graphical Install
3.1.2. Text Mode Install
3.2. Log Files
A. Using PGI on i386 (IA-32) Machines
B. Using PGI on IA-64 Machines
B.1. Booting the Installer CD
B.2. Partitioning the Hard Drive
C. Other Resources

1. Introduction

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.

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.


2. Boot-Time Commands

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.


2.1. Options for Install and Rescue Modes

2.1.1. Networking Options

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

dhcp

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.

nodhcp

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.

ip=address

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.)

netmask=address

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).

gateway=address

As with netmask, if all needed installer services are provided locally, the gateway address is unnecessary. Otherwise, specify the address of the local router.

nameserver=address

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.

broadcast=address

This argument specifies the broadcast address for the local network segment. It is not normally necessary to specify this parameter.

domain=domain_name

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.


2.1.2. Live Filesystem Options

The following live filesystem options are available:

[livefs=host:path] [livefstype=fstype]

livefs=( device | host:path )

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.

livefstype=fstype

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.


3. Troubleshooting

3.1. Virtual Consoles

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.


3.2. Log Files

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.


A. Using PGI on i386 (IA-32) Machines

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.


B. Using PGI on IA-64 Machines


C. Other Resources

Notes

[1]

Essentially, the first stage begins when the Live filesystem mounted from... message is displayed.