DOKK / manpages / debian 10 / s390-tools / zipl.8.en
ZIPL(8) System Manager's Manual ZIPL(8)

zipl - boot loader for IBM S/390 and zSeries architectures

zipl [OPTION] [SECTION]

zipl is a boot loader tool for IBM S/390 and zSeries machines. It can be used to prepare devices for initial program load (IPL). The following functions are supported:

-
booting a Linux kernel with optional ramdisk and kernel command line
-
taking a snapshot of the current system status (system dump)
-
loading a data file to initialize named saved segments (NSS)

Each of these operations is characterized by a boot configuration, i.e. a set of required parameters. zipl supports two ways of specifying a boot configuration:

-
command line: all parameters are provided through the command line switches described below. Using this mode, only a single boot configuration can be specified.
-
configuration file: parameters are provided by sections defined in a configuration file (see zipl.conf(5)). Using a configuration file, you can either specify a single boot configuration or a menu, i.e. a list of configurations from which users can choose at boot time.

To use a single boot configuration section, provide its name as parameter to zipl. If zipl is called without parameters, it searches the configuration file for a section specifying the default action.

Boot menu

The zipl tool implements a boot menu which includes the following features:

-
display a list of available configurations
-
allow to choose a configuration
-
allow to specify additional kernel command line parameters

See the zipl.conf(5) man page for details on how to use the boot menu.

Logical devices

zipl can be used to prepare logical devices (e.g. a linear device mapper target) for booting when the following requirements are met by the logical device setup:

-
all boot relevant files (i.e. kernel, ramdisk and parameter files) must be located on a logical device which is mapped to a single physical disk of a type supported by zipl (i.e. DASD or SCSI disk)
-
adjacent data blocks on the logical device must correspond to adjacent blocks on the physical device
-
access to the first blocks (starting at block 0) of the physical device must be given

Examples for logical device setups that are supported are linear and mirror mapping.

When working with logical devices, zipl requires that the user provides more information about the target device:

-
device characteristics of the underlying physical device: disk type and format (e.g. ECKD CDL or FCP SCSI), disk geometry in case of ECKD DASDs and block size
-
target device offset, i.e. the number of blocks between the physical device start and the start of the logical device containing the filesystem with all boot relevant files
-
a device node which provides access to the first blocks of the device

If the user does not provide this information explicitly by parameters zipl automatically runs a driver specific helper script to obtain these data, e.g. zipl_helper.device-mapper.

Note that zipl uses /proc/devices to determine the driver name for a given device. If the driver name cannot be determined the preparation of a logical device for boot might fail. This can be the case in a chroot environment when /proc is not mounted explicitly.

Print usage information, then exit.

Print version information, then exit.

Use the specified <CONFIG FILE>. If none is supplied, the environment variable ZIPLCONF is evaluated if set, otherwise /etc/zipl.conf is used.

Use the specified <TARGET DIRECTORY>. zipl uses this directory to store the bootmap, i.e. a file containing boot data. The actual boot loader is installed onto the device containing the target directory. Supported devices are DASD and SCSI disks.

It is not possible to specify both this parameter and the name of a menu or configuration section on the command line at the same time.

Install the actual boot loader on the device node specified by BASE DEVICE.

This option is required when working with logical devices (see section "Logical devices" above).

Assume that the physical device is of the specified type. Valid values are:
-
CDL: DASD disk with ECKD/compatible disk layout
-
LDL: DASD disk with ECKD/linux disk layout
-
FBA: FBA disk DASD
-
SCSI: SCSI disk
This option is required when working with logical devices (see section "Logical devices" above).

Assume that the physical device has the specified number of cylinders, heads and sectors.

This option is required when working with logical devices which are located on DASD ECKD disks (see section "Logical devices" above).

Assume that blocks on the physical device are SIZE bytes long.

This option is required when working with logical devices (see section "Logical devices" above).

Assume that the logical device containing the directory specified by the --target option is located on the physical device starting at the block specified by OFFSET.

This option is required when working with logical devices (see section "Logical devices" above).

Install bootloader on the specified <TAPE DEVICE>. Use this option instead of the 'target' option to prepare a tape device for IPL.

It is not possible to specify both this parameter and the name of a menu or configuration section on the command line at the same time.

Use the Linux kernel image file <IMAGE>. An optional hexadecimal ADDRESS may be provided to specify a non-standard load address for the image file.

It is not possible to specify both this parameter and the name of a menu or configuration section on the command line at the same time.

Use the ramdisk image <RAMDISK>. An optional hexadecimal ADDRESS may be provided to specify a non-standard load address for the ramdisk file.

It is not possible to specify both this parameter and the name of a menu or configuration section on the command line at the same time.

Use the kernel command line stored in file <PARMFILE>. An optional hexadecimal ADDRESS may be provided to specify a non-standard load address for the parameter file.

It is not possible to specify both this parameter and the name of a menu or configuration section on the command line at the same time.

When installing a kernel, use the kernel command line <PARMLINE>. When --parmfile is specified as well, the contents of the parmfile and <PARMLINE> are appended to form the resulting command line.

It is not possible to specify both this parameter and the name of a menu section on the command line at the same time.

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.

Use the segment image <SEGMENT>. The mandatory hexadecimal ADDRESS specifies the load address for the segment file.

It is not possible to specify both this parameter and the name of a menu or configuration section on the command line at the same time.

Install a system dump record on the device identified by DEVNODE. Supported devices are DASD ECKD or FBA disk partitions, device mapper multipath partitions of FCP attached SCSI disks and IBM 3480/3490/3590/3592 tape devices.

With the exception of SCSI, 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.

Note that on partitions formatted with the ECKD/linux disk layout, the dump record will be overwritten by system dump data so that it can be used for IPL only once before the system dump record has to be installed again. Partitions formatted with the ECKD/compatible disk layout allow for an arbitrary number of subsequent dumps.

It is not possible to specify both this parameter and the name of a menu or configuration section on the command line at the same time.

This option has been removed, use --dumpto instead.

Install a multi-volume dump record on each device associated with one of the partitions listed in file DUMPLIST. Supported are DASD ECKD partitions formatted with the compatible disk layout.

A dump signature is written to each partition contained in DUMPLIST. This signature is checked by the dump tool, when the dump is written. If a dump partition does not have the signature, the dump tool will refuse to write the dump. With the --force option this mechanism can be disabled. E.g. this can be used for installing swap space on dump partitions.

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.

It is not possible to specify both this parameter and the name of a menu or configuration section on the command line at the same time.

Install the multi-boot configuration defined in menu section <MENU> of the configuration file.

This option cannot be used together with either --target, --image, --ramdisk, --parmfile, --parameters, --segment, --dumpto or --mvdump.

Answer all confirmation questions with 'yes'. This option may be useful when zipl is called from within a shell script or in other situations where no user interaction is possible.

Provide more verbose output.

Copy all specified files to the bootmap file instead of just referencing them. This option allows specifying files in a boot configuration which are not located on the target device.

Print the results of performing the specified action without actually changing the IPL records. This option can be used to test a configuration since all error-checking is still done.

Note that when working with tapes, the current device position will be changed even when specifying this option.

Omit validity checking while producing a multi-volume dump. Multi-volume dump partitions will be overwritten with dump data no matter whether they contain a dump signature or not.

This option can only be used together with --mvdump.

1. Scenario: prepare disk for booting a Linux kernel image using the following parameters:
- the directory /boot is located on the boot device
- /boot/image contains the Linux kernel image
- /boot/ramdisk.img contains a ramdisk image
- /boot/parmfile contains the kernel parameter line

The respective zipl call reads:


zipl -t /boot -i /boot/image -r /boot/ramdisk.img
-p /boot/parmfile

2. Scenario: prepare DASD partition /dev/dasda1 for system dump:


zipl -d /dev/dasda1

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.

zipl.conf(5), kexec(8)

Feb 2012 s390-tools