CHREIPL(8)

📦 version 2.44.1, in opensuse-leap 16.0

CHREIPL(8) 💅✨

okay bestie, welcome to chreipl — the System Manager's Manual page for changing the re-IPL configuration on Linux on System z. this is literally your glowy mainframe boot queen and she's about to eat 🎀

✨ NAME ✨

chreipl — change the re-IPL configuration for Linux on System z 🦋

🌸 SYNOPSIS 🌸

chreipl [TARGET] [OPTIONS]

💖 DESCRIPTION 💖

so like, use the chreipl tool to modify the re-IPL configuration for Linux on System z. no cap, that's the whole vibe 💅 You can configure a certain boot device and, for zipl boot menu configurations, the boot menu entry that will be used for the next reboot. Also kernel parameters for the next Linux kernel can be defined. it's giving "prep your next glow-up" energy ✨

Initial program load (IPL) is the mainframe synonym for what is called "boot" under Linux. bestie, it's just mainframe-speak for booting, iykyk 🫶 Accordingly re-IPL can be translated to "reboot" in the non-mainframe context.

ngl, normally for reboot the last IPL device is used to restart the system. To reboot from another IPL device, you first have to change the re-IPL settings with chreipl and then run the reboot(8) command. two steps, no shortcuts, periodt 💀

All settings made with chreipl are preserved over reboots until they are changed again. your choices stick around like a loyal bestie 🌈

👑 TARGET 👑

The first argument specifies the re-IPL target:

  • ccw: Specify a DASD CCW device for reboot 🔥
  • eckd: Specify a DASD ECKD device for reboot 🎀
  • fcp: Specify a FCP device for reboot 🦋
  • nvme: Specify an NVMe device for reboot ⭐
  • nss: Specify a named saved system (NSS) for reboot 🌸
  • node: Specify a device for reboot using a device node or directory 🧚

If the target specification is non-ambiguous it can be omitted. See section AUTOTARGET for more information. Ambiguous setups are very rare, e.g. the name of a device node theoretically could be the same as a bus-ID. like, literally edge case of edge cases 💜

💅 OPTIONS 💅

  • -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 blacklist.
Note: Use this option with great care. You can specify non-existing devices, which will cause the re-IPL to fail. 😭 like bestie pls be careful, this is the "chaotic impulsive friend" option fr fr
  • -p or --bootparms — Specifies boot parameters for the next reboot. The boot parameters which are typically kernel parameters are appended to the kernel parameter line. If you specify the boot parameters with a leading equal sign (=), the boot parameters replace all parameters on the kernel parameter line. To remove boot parameters, specify an empty string for this option. 🫶

Depending on the chreipl target a different maximum number of characters is allowed for boot parameters. Under LPAR it is not possible to specify boot parameters for the ccw target. 💀

Note: When replacing all parameters, you might inadvertently omit parameters that the boot configuration requires. Read /proc/cmdline to find out with which parameters a running Linux instance has been started. ngl that's the vibe check you don't wanna skip 🌸
  • -h or --help — Print help information, then exit. iconic, the "help me help you" flag 💖
  • -v or --version — Print version information, then exit. 🎀

All other options are specific to the re-IPL target and are discussed below in the respective section. For a more detailed description of the Linux on System z IPL mechanisms see zipl.conf(6). The mandatory options (e.g. device, wwpn, lun, etc.) can also be specified as positional parameters. lowkey convenient, highkey slay ✨

🦋 AUTOTARGET 🦋

For the ccw, fcp, and node targets chreipl can find automatically the correct re-IPL target. To do this, omit the re-IPL target parameter and start specifying the required positional parameters. it's giving "she knows where she's going" energy 💅

Examples:

  1. Next time reboot from the DASD device /dev/dasda using the first boot configuration:
# chreipl /dev/dasda -L 1
  1. Next time reboot from the CCW device with the bus-ID 0.0.7e78 and empty loadparm:
# chreipl 0.0.7e78
  1. Next time reboot from the SCSI disk with FCP bus-ID 0.0.1700, WWPN 0x500507630300c562, and LUN 0x401040b300000000. In addition to that append kernel parameter "mem=" to restrict memory to 512 MB:
# chreipl 0.0.1700 0x500507630300c562 0x401040b300000000 -p "mem=512M"
  1. Next time reboot from the NVMe device with function id 0x13, namespace 1:
# chreipl nvme 0x13 1

🌈 ccw 🌈

Use the ccw re-IPL target for DASD devices that are accessed by the hardware using channel command word (CCW) channels. it's the classic, the original, the main character 👑

  • -d or --device — Specifies the CCW bus-ID. If the bus-ID starts with "0.0." this prefix can be omitted and the four digit short notation can be used (e.g. 5000 is the same as 0.0.5000). 🫶
  • -L or --loadparm — Specifies an entry in the zipl(8) boot menu, and an active namespace in the installed zIPL environment block for evaluation of zIPL environment variables in the kernel command line. 💖

This option requires an argument, which has to be a string of the form "nSX", where optional number n indicates the boot menu entry, and optional token SX specifies the active namespace. This token consists of a mandatory leading capital S and of an optional trailing character X, which is either any decimal digit, indicating ID of the active site, or a capital S. In the last case, ID of the active namespace is determined as the SSID (Subchannel Set ID). okay that's a lot of letters bestie, but you got this 🎀

If the menu entry is omitted in the argument, then the default menu entry is used. If the X is omitted, or the whole token SX is omitted, then the common namespace of the installed zIPL environment block will be activated. defaults are your friend fr fr

  • -c or --clear — Specify whether memory should be cleared on re-IPL. Possible values are 0 to disable and 1 to enable memory clearing on re-IPL. Memory clearing is supported if the "clear" attribute is present in /sys/firmware/reipl/ccw/. 🌸

Examples:

  1. Next time reboot from the CCW device with the bus-ID 0.0.7e78 and empty loadparm:
# chreipl ccw 0.0.7e78
  1. Next time reboot from the CCW device with the bus-ID 0.0.7e78 using the first entry of the zipl boot menu and the second site namespace in the installed zIPL environment block for evaluation of zIPL environment variables in the kernel command line:
# chreipl ccw -d 0.0.7e78 -L 1S2

⭐ eckd ⭐

Use the eckd re-IPL target for DASD devices that are accessed by the hardware using channel command word (CCW) channels. In contrast to the ccw re-IPL target, the eckd target uses a list-directed bootloader that supports secure boot. so she's the upgraded, secure-boot-supporting sister of ccw — obsessed 🔥

  • -d or --device — Specifies the device bus-ID of the DASD. If the bus-ID starts with "0.0." this prefix can be omitted and the four digit short notation can be used (e.g. 5000 is the same as 0.0.5000). 🫶
  • -b or --bootprog — Specifies an entry in the ECKD boot configuration by defining the IPL boot program selector. If omitted, '0' is used. defaults stay winning 💅
  • --brchr — Specifies the block on the DASD where the boot record is located. If omitted, 0 is used. The specification comprises comma-separated values for cylinder, head, and record: "--brchr C,H,R". Alternatively, specifying "0" or "auto" makes the bootloader determine the boot record location from the volume label. auto-pilot mode activated ✨
  • -L or --loadparm — The loadparm for the eckd re-IPL target is not used to control the ECKD boot configuration that is defined by the zipl(8) boot menu. Instead it can be used to control higher level boot loaders like GRUB. For more details refer to distribution specific documentation. iykyk, check your distro docs 🦋
  • -c or --clear — Controls whether memory is cleared on re-IPL. Possible values are 0 to disable and 1 to enable memory clearing on re-IPL. Memory clearing is supported if the "clear" attribute is present in /sys/firmware/reipl/eckd/. 🌸

Examples:

  1. Next time reboot from the ECKD device with the bus-ID 0.0.7e78 and boot program selector 0:
# chreipl eckd 0.0.7e78
  1. Next time reboot from the ECKD device with the bus-ID 0.0.7e78 and boot program selector 2:
# chreipl eckd -d 0.0.7e78 -b 2
  1. Next time reboot from the ECKD device with the bus-ID 0.0.7e78 and tell the bootloader that the bootrecord is located in Cylinder 3, Head 0, Record 1:
# chreipl eckd -d 0.0.7e78 --brchr 3,0,1

🧚 fcp 🧚

Use the fcp re-IPL target for SCSI disks that are accessed by the hardware using Fibre Channel Protocol (FCP) channels. fibre channel realness 💜

  • -d or --device — Specifies the bus-ID of the FCP adapter that should be used to access the SCSI re-IPL device. If the bus-ID starts with "0.0." this prefix can be omitted and the four digit short notation can be used (e.g. 5000 is the same as 0.0.5000). 🫶
  • -w or --wwpn — Specifies the world wide port name (WWPN) for the FCP attached SCSI disk. 🌈
  • -l or --lun — Specifies the logical unit number (LUN) for the FCP attached SCSI disk. ⭐
  • -b or --bootprog — Specifies an entry in the FCP boot configuration by defining the IPL boot program selector. If omitted, '0' will be used. 🎀
  • -L or --loadparm — The loadparm for the fcp re-IPL target is not used to control the FCP boot configuration that is defined by the zipl(8) boot menu. Instead it can be used to control higher level boot loaders like GRUB. For more details refer to distribution specific documentation. same vibe as eckd, check your docs bestie 🦋
  • -c or --clear — Specify whether memory should be cleared on re-IPL. Possible values are 0 to disable and 1 to enable memory clearing on re-IPL. Memory clearing is supported if the "clear" attribute is present in /sys/firmware/reipl/fcp/. 🌸

Examples:

  1. Next time reboot from the SCSI disk with FCP bus-ID 0.0.1700, WWPN 0x500507630300c562, LUN 0x401040b300000000, and boot program selector 0:
# chreipl fcp 0.0.1700 0x500507630300c562 0x401040b300000000
  1. Use same configuration as (1) but choose boot program selector 2 and use options instead of positional parameters:
# chreipl fcp -d 0.0.1700 -w 0x5005076... -l 0x401040b3... -b 2

and that's part 1 bestie, we're literally only getting started 💖✨🎀

nvme 💾✨

Okay so when your re-IPL target is an NVMe disk, that's this one. It's giving "reboot but make it flashy storage" and honestly? Iconic.

  • -i, --fid — the PCI Function ID of the NVMe IPL device, and ngl bestie it's in hex, so don't come at it with decimals 💅
  • -s, --nsid — the Namespace ID of the NVMe IPL device. This one is decimal, and the default is 1 🎀
  • -b, --bootprog — picks an entry in the boot configuration by setting the IPL boot program selector. Leave it out and it just uses '0', easy peasy 🦋
  • -L, --loadparm — heads up bestie, for the nvme re-IPL target the loadparm does not control the boot configuration that the zipl(8) boot menu defines. It's for controlling higher level boot loaders like GRUB instead 🫶 for the deets you gotta check your distribution's own documentation, iykyk
  • -c, --clear — says whether memory should be cleared on re-IPL. Possible values are 0 to disable and 1 to enable memory clearing on re-IPL. Memory clearing is only supported if the "clear" attribute is actually present in /sys/firmware/reipl/nvme/ — so vibe check that path first bestie 🔍

Examples ✨

  1. Next time reboot from the NVMe disk with function-id 0x13 and namespace 1:
# chreipl nvme 0x13 1
  1. Use same configuration as (1) but choose boot program selector 2 and use options instead of positional parameters:
# chreipl nvme -i 0x13 -s 1 -b 2

nss 🌸

This is the re-IPL target for z/VM named saved systems (NSS) — yeah, that's what NSS stands for, you're welcome 😌 use it when you want to reboot into an NSS, periodt.

  • -n, --name — specifies the name of the NSS. That's it, that's the whole option, she's simple and she serves 💅

Examples 🎀

Use the NSS named LINUX1 for the next reboot:

# chreipl nss LINUX1

node 🦋

okay this one is genuinely so convenient — you can identify DASD, SCSI, or NVMe re-IPL devices indirectly, through a device node or a directory 💖 and chreipl then figures out the info that you'd otherwise have to type out yourself with the ccw or fcp target. literally doing the homework for you, main character energy fr fr.

Examples ⭐

  1. Next time reboot from the DASD device /dev/dasda:
# chreipl node /dev/dasda
  1. Next time reboot from the SCSI disk /dev/sda:
# chreipl node /dev/sda
  1. Next time reboot from the device where directory /mnt/boot is located:
# chreipl node /mnt/boot
  1. Next time reboot from the NVMe device represented by /dev/nvme0n1
# chreipl node /dev/nvme0n1

✨ SEE ALSO ✨ 👀

Like, go read those too, they're the friend group 💜

and that's the whole page bestie!! 🎉 this lil masterpiece is from s390-tools, dated July 2010, and the manual page is CHREIPL(8) — go forth and re-IPL responsibly, mwah 💋👑
📦 where this page comes from