ZIPL.CONF(5)

NAME
zipl.conf - zipl configuration file

DESCRIPTION
The zipl.conf file contains configuration information for the IBM S/390 and zSeries boot loader tool zipl (see zipl(8)).
By default this configuration file is located at /etc/zipl.conf. A different location may be specified either using the '--config' option of zipl or by setting the ZIPLCONF shell environment variable.
Using the zipl.conf configuration file, one can specify several different boot configurations. Each configuration represents one of the following tasks which are performed at boot time:

-   boot a Linux kernel using a specific kernel parameter line and optionally a ramdisk

-   load a data segment for initializing named saved segments

-   create a system dump on a DASD disk partition or tape device

-   create a system dump file on a SCSI disk partition

To be able to specify more than one boot configuration, the zipl.conf file is divided into sections. There are two types of sections: configuration sections and menu sections. Configuration sections specify a single task while menu sections represent a list of tasks which are grouped together as a 'menu'. Each section begins with a heading. In the case of configuration sections, the heading is a single line containing the section name in square brackets ([]). Such names may be made up of any printable character except for space and have to be unique among the configuration file. Menu headings are made up of a leading colon (':'), followed by a menu name which may consist of alphabetic characters and numbers. The heading is followed by a number of lines, called the section body. Inside this body, options are specified, one per line, using the form

    key=value

where 'key' may be any of the options described below or a number in case of a menu section. The 'value' field may be enclosed in quotes (" or ') to preserve leading and trailing spaces. Lines beginning with a hash sign (#) are treated as comments and will be ignored. Note that it is not allowed to specify key=value pairs outside of a section (i.e. before the first section heading). As a special section name, 'defaultboot' is reserved for specifying a default boot configuration (see options 'default' and 'defaultmenu' below). Example configuration:

    # An example for a zipl.conf file
    [defaultboot]
    defaultmenu = menu1
    [linux]
    target = /boot
    image = /boot/image
    parameters = "root=/dev/dasda1 console=ttyS0"
    [test]
    target = /boot
    image = /boot/image-test
    parmfile = /boot/parmfile-test
    :menu1
    target = /boot
    1 = linux
    2 = test
    default = 1
    prompt = 1
    timeout = 0

Boot menu The zipl tool provides a boot menu function which enables a user to choose a boot configuration and to add extra kernel command line parameters at IPL time (only available for DASD disk devices). Before a boot menu can be used, a menu section has to be defined (see example configuration) and installed. Configurations included in the menu section are subsequently identified by their assigned number. If the 'prompt' setting of the menu section is set to 1, a menu text will be displayed during IPL and the boot program will wait for user input:

    zIPL interactive boot menu
     0. default (linux)

     1. linux
     2. test

    Please choose:

The menu prompt expects the configuration number as input. Typing '0' will start the default configuration. Additional kernel parameters can be specified by supplying them after the configuration number, separated by a blank character. Example input:

    2 mem=128m maxcpus=1

This will start configuration 2 and append the string "mem=128m maxcpus=1" to the existing kernel command line. Note that the extra parameters are only temporary and won't be saved for the next IPL process. Note also that the selected configuration number will be available to the init process through the environment variable named BOOT_IMAGE. If the 'timeout' option has been used, the boot menu will automatically start the default configuration after the specified number of seconds has passed without user input. VM users need to prefix all input with the VM VINPUT command, e.g. type '#cp vinput vmsg 0' to boot the default configuration. Another way of selecting a configuration without the interactive menu is by specifying its number using the IPL 'loadparm' function, e.g.:

    #cp ipl 0192 loadparm 2

In case the specified number does not correspond to a valid configuration, the boot process will abort with a disabled wait state (address code 0x300). The loadparm function is available even if the menu has been deactivated by setting 'prompt' to zero or by installing only a single configuration. The menu can then be temporarily activated by passing the string 'prompt' via the loadparm function:

    #cp ipl 0192 loadparm prompt

OPTIONS
number = section name (menu only)

    Menu section:
    Specifies that section section name be included in the menu at position number, where number is limited to the interval from 1 to 62 (30 on SCSI devices). A choice of boot configurations will either be available through a respective hardware feature or using the interactive boot menu (DASD devices only - see description above). Note that only disk IPL sections (see option image) and file system dump sections (option dumptofs) may be included in menus.

default = default-configuration (configuration and menu)

    Configuration section:
    This option specifies the name of the default configuration section which is used when zipl is called without parameters. A user may override this setting by specifying a different section as command line argument when calling zipl. Note that this option is only valid in a special section named 'defaultboot'. Menu section:
    This option specifies the position number of the menu entry to use as default, i.e. when no user selection is available at boot time. If no default entry is specified, the first entry to appear in the menu section will be used as default.

defaultmenu = default-menu (configuration only)

    Configuration section:
    This option specifies the name of the default menu configuration section which is used when zipl is called without parameters. A user may override this setting by specifying a different menu section using the '--menu' option when calling zipl. Note that this option is only valid in a special section named 'defaultboot'.

dumpto = dump-device[,size] (configuration only)

    Configuration section:
    Specify a DASD partition or an IBM 3480/3490/3590 tape device on which to install a system dump record. Once a device prepared in such a way is booted, the current system status is written in a raw format to that device and can later be retrieved using the zgetdump utility (see zgetdump(8)). An optional decimal SIZE parameter may be specified to determine the maximum dump size in bytes. SIZE can be suffixed by either of the letters K, M or G to signify that the decimal number be interpreted as kilobytes, megabytes or gigabytes respectively. SIZE will be rounded up to the next megabyte boundary. Note that when you specify a SIZE lower than the actual memory size used by linux (see kernel parameter mem=), the resulting dump will be incomplete.

dumptofs = dump-partition[,size] (configuration only)

    Configuration section:
    Specify a SCSI partition which should be used for system dump. Every time this configuration is booted, the current system status is written as a numbered file to the file system located on the dump partition. This option has to be specified together with the 'target' option. If necessary, the 'parmfile' or 'parameters' option may be used to pass parameters to the system dump tool. An optional decimal SIZE parameter may be specified to determine the maximum dump size in bytes. SIZE can be suffixed by either of the letters K, M or G to signify that the decimal number be interpreted as kilobytes, megabytes or gigabytes respectively. SIZE will be rounded up to the next megabyte boundary. Note that when you specify a SIZE lower than the actual memory size used by linux (see kernel parameter mem=), the resulting dump will be incomplete.

image = image-file[,address] (configuration only)

    Configuration section:
    Specify an image file containing the Linux kernel which should be started when booting this configuration. An optional hexadecimal address may be provided to load the kernel to a non-default memory location. An initial ramdisk may be provided using 'ramdisk'. To change the kernel parameters, use 'parmfile' or 'parameters'. This option cannot be used together with either 'dump', 'dumptofs' or 'segment'.

parameters = kernel-parameters (configuration only)

    Configuration section:
    Use this option to specify a parameter line which will be passed to the Linux kernel at boot time. Note that the parameter line may be enclosed in quotes (" or ') to preserve leading and trailing spaces.

parmfile = kernel-parmfile[,address] (configuration only)

    Configuration section:
    This option can be used to specify a file which contains the kernel parameter line. An optional hexadecimal address may be provided to load the kernel to a non-default memory location.

prompt = 0/1 (menu only)

    Menu section:
    Setting this option to 1 activates the interactive boot menu which can be used to select a configuration at boot time (DASD disks only). See previous section for a detailed description of the boot menu. The default value for 'prompt' is 0.

ramdisk = ramdisk-file[,address] (configuration only)

    Configuration section:
    Specify an image file containing an initial ramdisk which will be used as root device when booting a Linux kernel with respective parameters. An optional hexadecimal address may be provided to load the kernel to a non-default memory location.

segment = segment-file,address (configuration only)

    Configuration section:
    Specify a file which will be used to initialize a named saved segment. address is mandatory as it specifies the hexadecimal load address for the segment file.

tape = tape-device (configuration only)

    Configuration section:
    Specify a IBM 3480/3490/3590 tape device on which to install a boot record. This option cannot be used together with 'target', 'dump', 'dumptofs' or 'segment'.

target = target-directory (configuration and menu)

    Configuration and menu section:
    Specify a target directory for a configuration or menu section. This directory is used for the following purpose:

-   A special file named 'bootmap' will be written to this directory. It holds data which is required for the boot process. Note that any attempt of deleting or modifying it will result in undefined behavior.

-   The device on which the target directory is located will be used as 'target device', i.e. it will be prepared for booting (initial program load).

timeout = menu-timeout (menu only)

    Menu section:
    Specify a timeout interval in seconds after which the interactive boot menu will automatically select the default boot configuration. Setting this value to 0 or providing any user input at boot time will deactivate the timeout mechanism. The default value for 'timeout' is 0.

BUGS
Please report errors to linux390@de.ibm.com

SEE ALSO
zipl(8), zgetdump(8)