ZIPL.CONF(5)

📦 version 2.44.1, in opensuse-leap 16.0

okay so you've stumbled into ZIPL.CONF(5), straight out of the File Formats Manual, and honestly? she's giving documentation icon 💅 this is the whole entire man page for the zipl.conf config file, and by the end you're gonna be obsessed, promise 🫶

🎀 NAME 🎀

zipl.conf — zipl configuration file ✨

🌸 DESCRIPTION 🌸

so the zipl.conf file contains configuration information for zipl, the boot loader tool for IBM S/390 and zSeries (go peep zipl(8) for the whole story, iykyk) 👑

By default, zipl checks for zipl.conf at /run/zipl/zipl.conf, /etc/zipl.conf, and /lib/s390-tools/zipl.conf, in exactly that order — whichever one gets found first is the one that gets used, no cap. But if you're feeling particular, you can specifically choose a location using the --config option of zipl, or by setting the ZIPLCONF shell environment variable. your file, your rules 💅

Using the zipl.conf configuration file, one can specify several different boot configurations. Each configuration represents one of the following tasks, and these are the things that get 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
create a system dump on a NVMe 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 they 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 — yes, spaces are precious, protect them 🎀. 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). every key needs a home, bestie.

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

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). iconic behavior, honestly 👑

There are two alternatives for specifying a boot menu:

by explicitly defining a menu section (see example configuration)
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 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). 💀 not the vibe, but good to know.

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, a NVMe partition or an IBM 3490 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)). 🦋
### 📐 the SIZE thing (optional, decimal)

You can tack an optional decimal SIZE onto it to cap the maximum dump size in bytes. SIZE can wear a lil suffix — K, M, or G — which means "bestie, read that decimal number as kilobytes / megabytes / gigabytes respectively 💅".

SIZE gets rounded up to the next megabyte boundary (no sliver-of-a-meg leftovers, we go full meg here ✨).

⚠️ Real talk: if you pass a SIZE that's lower than the actual memory size used by linux (peep kernel parameter mem=), your dump will be incomplete 😭. And heads up — for SCSI/NVMe dump the SIZE parameter is not supported. Nope. Not a thing. Don't try it 🫶

dumptofs — this one's been removed, so use dumpto instead. It's giving deprecated. It's giving ghosted. 👻
mvdump = dumplist[,size] (configuration only)

🌸 Configuration section:

Point this at a file containing a list of ECKD DASD partitions formatted with compatible disk layout. Every device associated with one of those listed partitions gets prepped for multi-volume dump — a dump signature is written to each listed partition ✍️. Once a device prepped like this boots, the current system status is written in a raw format to that specified set of partitions, and later you can retrieve it with the zgetdump utility (see zgetdump(8)) 🎀.

Optional decimal SIZE — same deal as above: max dump size in bytes, suffixes K, M, G = kilobytes, megabytes, gigabytes respectively, and SIZE is rounded up to the next megabyte boundary. And again, if SIZE is lower than the actual memory size used by linux (kernel parameter mem=), the resulting dump will be incomplete 😬.

This option is the moment if the actual memory size used by linux is larger than any single ECKD DASD partition could hold — literally its whole purpose 💖.

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

🌸 Configuration section:

Specify an image file holding the Linux kernel that should be started when this configuration boots 🐧✨. You can drop an optional hexadecimal address to load the kernel at a non-default memory location.

Want an initial ramdisk? That's ramdisk. Want to change kernel parameters? Use parmfile or parameters 🫶.

💀 Cannot be used together with dump or segment. Pick a lane, bestie.

optional = 0/1 (configuration only)

🌸 Configuration section:

Set it to 1 and the configuration section only shows up in the boot menu if the referenced image file exists — and running zipl won't fail if that image file is missing 😌✨.

The default value for optional is 0.

parameters = kernel-parameters (configuration only)

🌸 Configuration section:

Use this to hand over a parameter line that gets passed to the Linux kernel at boot time 🐧. Note that the parameter line may be wrapped in quotes (" or ') to preserve leading and trailing spaces — yes, spaces matter, protect them 🥺.

The parameter line can also contain zIPL environment variables (see zipl-editenv(8)) 💜.

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

🌸 Configuration section:

Use this to name a file that contains the kernel parameter line 📄. Optional hexadecimal address to load the kernel at a non-default memory location, same vibe as image ✨.

kdump = auto (configuration only)

🌸 Configuration section:

Specify this to install a kdump kernel that works 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's been configured with a reserved memory area for kdump.

For Linux, that memory is reserved with the "crashkernel" kernel parameter. Iconic reserved-memory behaviour, no cap 👑

prompt = 0/1 (configuration and menu)

🌸 Configuration section:

This option is only valid in a special section named defaultboot, and only when specified together with the options defaultauto or target 🎯.

Setting it to 1 activates the interactive boot menu so you can pick a configuration at boot time (DASD disks only). See the previous section for a detailed description of the boot menu 👀.

The default value for prompt is 0.

Setting it to 1 activates the interactive boot menu for selecting a configuration at boot time (DASD disks only). See the previous section for the full boot menu breakdown.

The default value for prompt is 0.

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

🌸 Configuration section:

Specify an image file containing an initial ramdisk, which gets used as the root device when booting a Linux kernel with the respective parameters 🌱✨. Optional hexadecimal address to load it at a non-default memory location 🫶.

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

🌸 Configuration section:

Controls the zIPL secure boot support. Set it to one of these:

auto: write signatures if available and supported by the system ✨
1: write signatures regardless of support indicated by the local system 💪 — but 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 that will be used to initialize a named saved segment 🎀. address is mandatory here — it's the hexadecimal load address for the segment file. No address, no segment, periodt 💅.

tape = tape-device (configuration only)

🌸 Configuration section:

Specify an IBM 3490 tape device to install a boot record on 📼✨.

💀 Cannot be used together with target, dump, or segment. Choose wisely.

target = target-directory (configuration and menu)

Specify a target directory for a configuration or menu section. This directory does two jobs:

A special file named bootmap gets written to this directory 📝. It holds data required for the boot process.
The device on which the target directory lives becomes the target device — i.e. it gets prepared for booting (initial program load) 🚀

⚠️ Heads up, seriously: any attempt at deleting or modifying that bootmap file will result in undefined behavior 💀 Do not touch. Do not vibe-check it. Leave it alone 🙈

targetbase = base-device (configuration and menu)

Specify the device which will be prepared for booting 👑.