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 zipl checks for zipl.conf at /run/zipl/zipl.conf, /etc/zipl.conf, /lib/s390-tools/zipl.conf in that order - whichever is found first will be used. Users can specifically choose a location 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 on a device mapper multipath partition device node of a SCSI disk

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', 'defaultmenu' and 'defaultauto'" 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
secure = auto

BootLoaderSpec configuration files

Another way to specify IPL sections is to use BLS config files. These are configuration files located by default at /boot/loader/entries, but another location can be specified using the '--blsdir' option of zipl.

# An example for a BLS configuration file

version 4.15.9
linux /vmlinuz-4.15.9
initrd /initramfs-4.15.9
options root=/dev/dasda1 console=ttyS0

The location of the linux and initrd has to be specified relative to the boot partition. The BLS config files are only used to specify the IPL sections, a zipl.conf configuration file is still needed for global parameters. For this purpose, a minimal zipl.conf configuration file is shipped at /lib/s390-tools/zipl.conf which would help when used with BLS config files, by not requiring users to create the traditional configuration file at /etc/zipl.conf.

Boot menu

The zipl tool provides a boot menu function which enables users to choose a boot configuration and to modify the kernel command line parameters at IPL time (only available for DASD disk devices).

There are two alternatives for specifying a boot menu:

1. by explicitly defining a menu section (see example configuration)

2. by having zipl automatically create a menu from all available IPL sections (see description of 'defaultauto' keyword below)

When defining a menu section, included configurations 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. These kernel parameters will be converted to lower-case. 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. To replace the existing command line, prefix the the string with "=":

2 =dasd=0190 root=/dev/dasda1

This will start configuration 2 and use "dasd=0190 root=/dev/dasda1" as the kernel command line. Note that these menu-specified 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).

Only disk IPL sections (see option image) and file system dump sections (option dumpto) may be included in menus.

Note that position number 0 is reserved and will automatically be assigned to the default menu entry (see default).

default = default-configuration (configuration and menu)

Configuration section:
This option is valid only in a special section named 'defaultboot'. It indicates the default action which zipl should perform when called without parameters.

When specified alone, it indicates that zipl should install a single boot configuration. In that case, default-configuration indicates the configuration name.

When specified together with 'defaultauto' or 'target' , it indicates that zipl should install a boot menu including all IPL boot configurations found in the configuration file. In that case, default-configuration specifies the name of the boot configuration to be used as default by the menu.

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.

The default entry will also be available as position number 0.

defaultauto (configuration only)

Configuration section:
This option is valid only in a special section named 'defaultboot'. It indicates the default action which zipl should perform when called without parameters.

When specified, it indicates that zipl should install a boot menu including all IPL boot configurations found in the configuration file.

When this option is specified, a 'target' option must also be present and other menu-specific options such as 'default', 'timeout' or 'prompt' may also be present in the same section.

Note that IPL configurations included in the menu are numbered in the order in which they are found in the configuration file.

defaultmenu = default-menu (configuration only)

Configuration section:
This option is valid only in a special section named 'defaultboot'. It indicates the default action which zipl should perform when called without parameters.

When specified, it indicates that zipl should install a boot menu. In that case, default-menu indicates the menu name.

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

Configuration section:
Specify a DASD partition, device mapper multipath partition device node of a SCSI disk 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. Also note that for SCSI dump the SIZE parameter is not supported.

dumptofs

This option has been removed, use dumpto instead.

mvdump = dumplist[,size] (configuration only)

Configuration section:
Specify a file containing a list of ECKD DASD partitions formatted with compatible disk layout. Each device associated with one of the listed partitions is prepared for multi-volume dump. A dump signature is written to each listed partition. Once a device prepared in such a way is booted, the current system status is written in a raw format to the specified set of partitions 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.

This option is useful if the actual memory size used by linux is larger than any single ECKD DASD partition could hold.

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', or 'segment'.

optional = 0/1 (configuration only)

Configuration section:
If this option is set to 1 the configuration section will only be included in the boot menu if the referenced image file exists, and running zipl will not fail if the image file is missing.

The default value for 'optional' is 0.

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.

kdump = auto (configuration only)

Configuration section:
Specify this option to install a kdump kernel that can be used as a stand-alone dump tool. You can IPL this kernel in an LPAR or guest virtual machine to create a dump of a previously running operating system instance that has been configured with a reserved memory area for kdump. For Linux, the memory is reserved with the "crashkernel" kernel parameter.

prompt = 0/1 (configuration and menu)

Configuration section:
This option is valid only in a special section named 'defaultboot' and when specified together with options 'defaultauto' or 'target'.

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.

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.

secure = auto/1/0 (configuration and menu)

Configuration section:
Control the zIPL secure boot support. Set this option to one of the following values:

-

auto: Write signatures if available and supported by the system.

-

1: Write signatures regardless of support indicated by the local system. Missing signatures for stage 3 and kernel IPL files will result in an error.

-

0: Do not write signatures.

The default value for 'secure' is auto.

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

targetbase = base-device (configuration and menu)

Configuration and menu section:
Specify the device which will be prepared for booting.

This parameter is required when working with logical devices (see zipl(8)).

targettype = type (configuration and menu)

Configuration and menu section:
Specify the device type for the physical device.

-

CDL: DASD disk with ECKD/compatible disk layout

-

LDL: DASD disk with ECKD/linux disk layout

-

FBA: FBA disk DASD

-

SCSI disk

This parameter is required when working with logical devices (see zipl(8)).

targetgeometry = cylinders,heads,sectors (configuration and menu)

Configuration and menu section:
Specify the number of cylinders, heads and sectors for the physical device.

This parameter is required when working with logical devices (see zipl(8)).

targetblocksize = size (configuration and menu)

Configuration and menu section:
Specify the number of bytes per block for the physical device.

This parameter is required when working with logical devices (see zipl(8)).

targetoffset = offset (configuration and menu)

Configuration and menu section:
Specify the starting block number of the logical device on the physical device.

This parameter is required when working with logical devices (see zipl(8)).

timeout = menu-timeout (configuration and menu)

Configuration section:
This option is valid only in a special section named 'defaultboot' and when specified together with options 'defaultauto' or 'target'.

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.

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.

NOTES

While it is not recommended for reasons of recovery and redundancy, FCP. attached SCSI disks can also be accessed directly without multipathing,. for example via the "/dev/disk/by-path/" device nodes.

SEE ALSO

zipl(8), zgetdump(8)