ZIPL(8)

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

SYNOPSIS
zipl [OPTION] [SECTION]

DESCRIPTION
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 three 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.

-   BLS config files: boot configurations are specified using BootLoaderSpec (BLS) configuration files. The zipl.conf(5) configuration file is still used to specify parameters or additional boot configurations.

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

-   choose a configuration

-   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, SCSI or NVMe 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.

OPTIONS

-h or --help
    Print usage information, then exit.

-v or --version
    Print version information, then exit.

-c <CONFIG FILE> or --config=<CONFIG FILE>
    Use the specified <CONFIG FILE>. If none is supplied, the environment variable ZIPLCONF is evaluated if set, otherwise %SYSCONFDIR%/zipl.conf is used.

-b <BLS DIRECTORY> or --blsdir=<BLS DIRECTORY>
    Use the specified <BLS DIRECTORY> to parse BootLoaderSpec config files. If none is supplied, the /boot/loader/entries directory is used.

-t <TARGET DIRECTORY> or --target=<TARGET DIRECTORY>
    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, SCSI and NVMe 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.

--environment=<FILE>
    Import zIPL environment from specified <FILE>. If none is supplied, it will be imported from "/etc/ziplenv".

--targetbase=<BASE DEVICE>
    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).

--targettype=<TARGET TYPE>
    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 or NVMe disk

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

--targetgeometry=<CYLINDERS,HEADS,SECTORS>
    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).

--targetblocksize=<SIZE>
    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).

--targetoffset=<OFFSET>
    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).

-T <TAPE DEVICE> or --tape=<TAPE DEVICE>
    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.

-i <IMAGE[,ADDRESS]> or --image=<IMAGE[,ADDRESS]>
    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.

-r <RAMDISK[,ADDRESS]> or --ramdisk=<RAMDISK[,ADDRESS]>
    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.

-p <PARMFILE[,ADDRESS]> or --parmfile=<PARMFILE[,ADDRESS]>
    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.

-P <PARMLINE> or --parameters=<PARMLINE>
    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. The command line can contain zIPL environment variables (see zipl-editenv(8)).

-k auto or --kdump=auto
    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.

-s <SEGMENT,ADDRESS> or --segment=<SEGMENT,ADDRESS>
    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.

-d <DEVNODE[,SIZE]> or --dumpto=<DEVNODE[,SIZE]>
    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, partitions of NVMe disks and IBM 3480/3490/3590/3592 tape devices. For CCW-type DASD dump, zlib compression is used to compress the dump data before writing it to the DASD ECKD partition. Zlib compression requires the DFLTCC facility. Compression might increase dumping performance, thus minimizing system downtime. It also saves DASD space. With the exception of SCSI/NVMe, 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.

-D or --dumptofs
    This option has been removed, use --dumpto instead.

--ldipl-dump
    Install a List-directed dump record instead of a CCW-type dump.

--no-compress
    Do not use zlib compression for a CCW-type dump. Zlib compression is used by default for CCW-type single-volume DASD standalone dump when the DFLTCC facility is available on the system.

-M <DUMPLIST[,SIZE]> or --mvdump=<DUMPLIST[,SIZE]>
    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.

-m <MENU> or --menu=<MENU>
    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.

-n or --noninteractive
    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.

-V or --verbose
    Provide more verbose output.

-a or --add-files
    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.

--dry-run
    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. When working with ngdumps, the directory specified by the shell environment variable TMPDIR is used for simulating the dump job. This directory should belong to a "real" file system managing disk space addresses (like ext4, or xfs), and have enough free space (matching the size of the specified dump device). If TMPDIR is not set, then "/tmp" is used, which can lead to errors, e.g. in case when it belongs to tmpfs.

-f or --force
    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.

-S <SWITCH> or --secure <SWITCH>
    Control the zIPL secure boot support. <SWITCH> can take one of three values:
      auto (default)
        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.

EXAMPLE
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

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. The NVMe stand-alone dump can be used only on IBM z15 or newer machine generations because it requires larger amount of HSA memory offered by firmware only on IBM z15 machines. Whereas the SCSI stand-alone dump is able to work with HSA memory of 32M, the NVMe stand-alone dump requires 512M HSA memory.

SEE ALSO
zipl.conf(5), zipl-editenv(8), kexec(8)