chreipl - Modify the re-IPL configuration

Edit online

7.1 LPAR mode z/VM guest KVM guest

Use the chreipl tool to modify the re-IPL configuration for Linux® on IBM® Z.

You can configure a particular device as the reboot device. For zipl boot menu configurations, you can set the boot menu entry to be used for the next reboot. You can also specify additional kernel parameters for the next reboot.

chreipl syntax


1  chreipl
1 
2.1  ! ccw <device_bus_id>? -L<parm>
2.1 
2.2.1  eckd <device_bus_id>
2.2.2.1!  --brchr auto
2.2.2.1  --brchr <cylinder>,<head>,<record>
2.2.1 !  fcp(1)  <device_bus_id> <wwpn> <lun>
2.2.1  nvme -i <function-id>
2.2.2.1! -s 1
2.2.2.1 -s <namespace-id>
2.1?  -L <parm>
2.1?  -b <n>
2.1 ! node
2.2.1 <node>
2.2.1 <dir>
2.1? -L <parm>
2.1 ? -b <n>(2)
2.2.1!  --brchr auto(3)
2.2.1  --brchr <cylinder>,<head>,<record>
2.1! -c 0
2.1 -c 1
1 nss <name>
2? -p <bootparms>
2? -f
Notes:
  • 1 You can specify the <device_bus_id>, <wwpn>, and <lun> in any order if you use the corresponding command options.
  • 2 The -b option can be used if the device node or directory maps to a SCSI disk, an NVMe device, or a DASD with load type eckd.
  • 3 Only for DASD with load type eckd.
Where:
<device_bus_id> or -d <device_bus_id> or --device <device_bus_id>
specifies the device bus-ID of a CCW re-IPL device or of the FCP device through with a SCSI re-IPL device is attached.
eckd
declares that the following parameters refer to an ECKD DASD re-IPL device with a secure-boot enabled format of the boot data.
--brchr <cylinder>,<head>,<record>
specifies the cylinder, head, and record of a specific boot record location. Use one of the specifications auto, 0, or 0.0.0 to make the bootloader derive the location from the volume label. This is the default.
<wwpn> or -w <wwpn> or --wwpn <wwpn>
specifies the worldwide port name (WWPN) of a SCSI re-IPL device.
<lun> or -l <lun> or --lun <lun>
specifies the logical unit number (LUN) of a SCSI re-IPL device.
nvme
declares that the following parameters refer to an NVMe re-IPL device.
-i <function_id> or --fid <function_id>
specifies the PCIe function ID of the NVMe device. The function ID is an 8-digit hexadecimal value. Specify the ID with a leading 0x. In the value itself you can omit leading zeroes.
-s <namespace_id> or --nsid <namespace_id>
specifies the name space ID of the NVMe device as a decimal value. Name space IDs are assigned by NVMe disk controllers to divide a physical NVMe device into multiple logical devices.
<node>
specifies a device node of a DASD, SCSI, NVMe, or logical device mapper re-IPL device.
<dir>
specifies a directory in the Linux file system on the re-IPL device.
-c or --clear
controls memory clearing during the re-IPL. Possible values are 1 and 0:
0
does not clear memory during the re-IPL. This is the default.
1
clears all memory during the re-IPL. For large memory sizes, memory clearing can considerably slow down the re-IPL process. Use this setting if you must clear memory, even at the expense of a prolonged re-IPL procedure.

You cannot control memory clearing for all environments and re-IPL devices. For unsupported devices and environments, this option causes the command to fail with an error message.

This setting can affect the online state of hotplug memory after the re-IPL, see Memory state and reboot

nss
declares that the following parameters refer to a z/VM® named saved system (NSS).
<name> or -n <name> or --name <name>
specifies the name of an NSS as defined on the z/VM system.
Note: You cannot load Linux kernel 4.13 or later from an NSS. The NSS could contain a Linux distribution with NSS support or another mainframe operating system, for example, CMS.
-L <parm> or --loadparm <parm>
Specifies an entry in a zipl boot menu, a site context, or both. Depending on the menu configuration, omitting a value for <n> might display the menu or select the default configuration.
Boot menu entry
Applies only to menu configurations. Omit this specification if you are not addressing a menu configuration. If you have a menu configuration and omit this value, the default configuration might be used, or the menu might be displayed.
To specify a boot menu entry, you can use one of the following values for <parm>:
<i>
Specifies the configuration number, which is a positive integer.
0
Specifies the default configuration.
prompt
Forces the menu to be displayed.

When the menu is displayed, you can specify additional kernel parameters. These additional kernel parameters are appended to the parameters you might have provided in a parameter file. The combined parameter string must not exceed a length that is set when the kernel is compiled.

For more information about menu configurations, see Menu configurations. For examples of how a boot menu is displayed, see DASD menu configuration example for z/VM and DASD menu configuration example for LPAR.
Site specification
Applies only to Linux in a site-specific context, see Site-specific Linux instantiation. Omit this parameter if you are not working with site-specific sections in zipl environments or with site-specific DASD configurations.
To specify a site, you can use one of the following values for <parm>:
S<n>
Specifies the site ID for which site-specific kernel parameters and DASD configurations are to be used. The site ID <n> is a digit in the range 0 to 9.
SS
Uses the subchannel set ID (SSID) of the IPL device as the site ID, for example, if the SSID is 0, values for site 0 are used.
S
Uses the common specifications. Specifying a single capital S without a trailing site ID is equivalent to omitting the S parameter.
If you work with a combination of menu configurations and site specifications, append the site specification to the menu specification without a blank. For example, 3S2 selects the third zipl boot menu entry with the site 2 context.
-b or --bootprog <n>
specifies the entry in a zipl boot menu to be used for the next reboot. This parameter applies only to re-IPL devices with zipl boot menus and only for SCSI disks , NVMe devices, and ECKD DASDs with a secure-boot enabled format of the boot data.
Omitting this parameter eliminates an existing selection in the boot configuration and the default boot configuration is used.
-p or --bootparms
specifies boot parameters for the next reboot. The boot parameters, which typically are kernel parameters, are appended to the kernel parameter line in the boot configuration. The number of characters you can specify depends on your environment and re-IPL device as shown in Table 1.
Table 1. Maximum characters for additional kernel parameters by re-IPL device
Environment DASD SCSI or NVMe NSS
LPAR none 3452 n/a
z/VM 64 3452 56
KVM none n/a n/a

DASD with secure-boot enabled boot data, LD-IPL DASD (ECKD), accepts 3452 characters.

If you omit this parameter, the existing boot parameters in the next boot configuration are used without any changes.

-f or --force
With this option, you can force the re-IPL from a target device even if the target cannot be verified by the system. This is the case, for example, if the device is on the cio_ignore exclusion list.
Note: Use this option with great care. Specifying a non-existing device causes the re-IPL to fail.
-h or --help
displays help information for the command. To view the man page, enter man chreipl.
-v or --version
displays version information.
For disk-type re-IPL devices, the command accepts but does not require an initial statement:
ccw
declares that the following parameters refer to a DASD or a virtio block re-IPL device.
fcp
declares that the following parameters refer to a SCSI re-IPL device.
node
declares that the following parameters refer to a disk re-IPL device that is identified by a device node or by a directory in the Linux file system on that device. The disk device can be a DASD or a SCSI disk.

Examples

These examples illustrate common uses for chreipl.

  • The following commands all configure the same DASD as the re-IPL device, assuming that the device bus-ID of the DASD is 0.0.7e78, that the standard device node is /dev/dasdc, that udev creates an alternative device node /dev/disk/by-path/ccw-0.0.7e78, that /mnt/boot is located on the Linux file system in a partition of the DASD.
    • Using the bus ID: 
      # chreipl 0.0.7e78
    • Using the bus ID and the optional ccw statement: 
      # chreipl ccw 0.0.7e78
    • Using the bus ID, the optional statement and the optional --device keyword: 
      # chreipl ccw --device 0.0.7e78
    • Using the standard device node: 
      # chreipl /dev/dasdc
    • Using the udev-created device node: 
      # chreipl /dev/disk/by-path/ccw-0.0.7e78
    • Using a directory within the file system on the DASD: 
      # chreipl /mnt/boot
  • The following commands all configure the same SCSI disk as the re-IPL device, assuming that the device bus-ID of the FCP device through which the device is attached is 0.0.1700, the WWPN of the storage server is 0x500507630300c562, and the LUN is 0x401040b300000000. Further it is assumed that the standard device node is /dev/sdb, that udev creates an alternative device node /dev/disk/by-id/scsi-36005076303ffc56200000000000010b4, and that /mnt/fcpboot is located on the Linux file system in a partition of the SCSI disk.
    • Using bus ID, WWPN, and LUN: 
      # chreipl 0.0.1700 0x500507630300c562 0x401040b300000000
    • Using bus ID, WWPN, and LUN with the optional fcp statement: 
      # chreipl fcp 0.0.1700 0x500507630300c562 0x401040b300000000
    • Using bus ID, WWPN, LUN, the optional statement, and keywords for the parameters. When you use the keywords, the parameters can be specified in any order: 
      # chreipl fcp --wwpn 0x500507630300c562 -d 0.0.1700 --lun 0x401040b300000000
    • Using the standard device node: 
      # chreipl /dev/sdb
    • Using the udev-created device node: 
      # chreipl /dev/disk/by-id/scsi-36005076303ffc56200000000000010b4
    • Using a directory within the file system on the SCSI disk: 
      # chreipl /mnt/fcpboot
  • To configure a DASD with bus ID 0.0.7e78 as the re-IPL device, using the first entry of the zipl boot menu: 
    # chreipl 0.0.7e78 -L 1
Re-IPL type:  ccw
Device:       0.0.7e78
Loadparm:     "1"
Bootparms:    ""
clear:        0
Secure boot:  0
  • The following example configures a DASD with bus ID 0.0.7e78 as the re-IPL device. To also display all kernel messages on the console, add ignore_loglevel to the existing kernel parameters in the boot configuration. To clear memory at the expense of a prolonged re-IPL procedure, set the clear mode to 1.
    # chreipl 0.0.7e78 -p "ignore_loglevel" -c 1
Re-IPL type:  ccw
Device:       0.0.7e78
Loadparm:     ""
Bootparms:    "ignore_loglevel"
clear:        1
Secure boot:  0
  • The following example configures an NVMe device with Function ID 0x00000013 and name space ID 0x00000001 as the re-IPL device. 
    # chreipl nvme -i 0x13 -s 1
Re-IPL type: nvme
FID:         0x00000013
NSID:        0x00000001
bootprog:    0
br_lba:      0
Loadparm:    ""
Bootparms:   ""
clear:       0
Secure boot: 0
  • The following example configures an ECKD DASD with bus-ID 0.0.7e79 as the re-IPL device with IPL type eckd. If the DASD has a zipl boot menu, entry 0 is used.
    # chreipl eckd 0.0.7e79
  • The following example configures an ECKD DASD with bus-ID 0.0.7e77 as the re-IPL device with IPL type eckd. Entry 2 is used within a zipl boot menu and the site-specific configuration for site 3 is used.
    # chreipl eckd -d 0.0.7e77 -b 2 -L S3
  • The following example configures an ECKD DASD with bus-ID 0.0.7e77 as the re-IPL device with IPL type eckd. The example specifies the location of the boot record as cylinder 3, head 0, and record 1.
    # chreipl eckd --brchr 3,0,1