CHREIPL-FCP-MPATH(7)

💖 chreipl-fcp-mpath(7) 💖

okay bestie, welcome to the Administrator Manual for chreipl-fcp-mpath — the toolset that uses multipath information for re-IPL path failover on a running Linux instance. yes, that whole mouthful. stay with me, it slays once you get the vibe. 💅

🌸 NAME 🌸

chreipl-fcp-mpath — use multipath information for re-IPL path failover on a running Linux instance. 🦋

💅 DESCRIPTION 💅

okay so picture this: the IPL process of Linux on Z or LinuxONE from an FCP-attached SCSI volume uses exactly one path to the volume. if this path is unavailable, the IPL fails. not cute. 😭

The chreipl-fcp-mpath toolset monitors udev events about paths to the re-IPL volume. if the currently configured re-IPL path becomes unavailable, the toolset checks for operational paths to the same volume. if available, it reconfigures the re-IPL settings to use an operational path. ✨

Thus, re-IPL from an FCP-attached SCSI volume can be successful despite path failures on a running Linux instance if at least one path to the re-IPL volume remains operational. periodt. 👑

chreipl-fcp-mpath requires udev, multipathd and dm-multipath. once installed, the toolset runs automatically and autonomously. no user intervention is possible or required. it's giving set-it-and-forget-it main character energy. 🫶

Other than installing the toolset, there is no user interface for chreipl-fcp-mpath. literally no buttons, no menu, no little pop-up. 🎀

🧚 Requirements 🧚

The chreipl-fcp-mpath tool has the following requirements on the Linux instance that is being monitored:

• The Linux instance must have started successfully, during IPL.
• The running Linux instance must use dm-multipath and multipathd for the configured re-IPL volume — a volume that contains a zipl boot record and has one of its paths used in the re-IPL configuration.
• udev must run.
• The toolset must observe at least one event about the configured re-IPL path. examples for such events are: the SCSI disk comes online, or a path of the corresponding multipath device goes down or comes back online.
  • The WWID of the re-IPL volume must not change while the Linux instance is running.
• When the configured re-IPL path becomes unavailable while the Linux instance is running, at least one operational path to the re-IPL volume must be available, or must become available. if no such path is available when the Linux instance is rebooted, the re-IPL path is not changed.
• The tool assumes that any manually reconfigured re-IPL device is valid and operational.

The tool treats a newly configured re-IPL device like the initially configured re-IPL device. in particular, if the newly configured re-IPL device fulfills the requirements of the tool, re-IPL path failover takes place if the configured re-IPL path becomes unavailable.

🍓 Caution with Manual Changes to the Configured re-IPL Target 🍓

chreipl-fcp-mpath is designed to accept operator-inititated changes of the re-IPL device. however, concurrent changes by the operator and tool driven changes can result in the operator change being overwritten. 😭

To avoid this problem, change the re-IPL device only during steady-state operations, when no path events happen. alternatively, make sure that no events are processed while you change the device. see EXAMPLES for one way to suspend event processing.

📬 MESSAGES 📬

During monitoring and event processing, chreipl-fcp-mpath writes messages to the syslog. so if you're snooping, that's where the gossip lives. 👀

When the configured re-IPL path is changed to a different path to the same volume (priority daemon.notice):

Changed re-IPL path to: <device-bus-id>:<wwpn>:<lun>.

When a path event indicates that the last available path has become non-operational (priority daemon.alert):

The re-IPL device cannot be changed because no operational path to the re-IPL volume remains.  The next re-IPL might fail unless you re-attach or enable at least one valid path to the re-IPL volume.

💀 this one is serious, bestie. do not ignore it.

When changing the configured re-IPL device failed because of an error with the used Linux kernel interface (priority daemon.crit):

Changing the re-IPL device failed.  The current re-IPL settings might be inconsistent.  Check and correct the settings (see the README.md of chreipl-fcp-mpath) to make sure that the current re-IPL device is valid.

A failure to change the re-IPL device can indicate an inconsistent setting that cannot be corrected automatically by chreipl-fcp-mpath. as a result, the next re-IPL might fail or might not use the intended re-IPL device. 😭

You can use the following tools to check and correct the current settings:

• lsreipl to confirm that the intended re-IPL device is configured;
• chreipl to change the re-IPL device;
• lszfcp to inspect the state of available paths to the re-IPL device.

🎀 EXAMPLES 🎀

🫶 Manual Changes to the Configured re-IPL Device 🫶

As outlined in DESCRIPTION, be cautious when manually changing the configured re-IPL device. assure that your reconfiguration actions do not collide with concurrent automatic event processing by chreipl-fcp-mpath. you can avoid such collisions, by stopping event processing, making your changes, and then re-enabling event processing. you need root privileges for running the commands in the following example:

~ # udevadm settle
~ # udevadm control --stop-exec-queue
~ # chreipl ...
~ # udevadm control --start-exec-queue

🪄 Listing messages with journalctl 🪄

If your Linux instance includes journalctl, use the following command to list all messages that are issued by chreipl-fcp-mpath:

~ # journalctl -t chreipl-fcp-mpath

To list only messages that were issued since the last IPL, use this command:

~ # journalctl -t chreipl-fcp-mpath -b

🐛 REPORTING BUGS 🐛

Use the Issues functionality on GitHub to report any bugs in chreipl-fcp-mpath: s390-tools Issues. 🫶

👀 SEE ALSO 👀

chreipl(8), dracut(8), journalctl(1), lsreipl(8), lszfcp(8), multipath(8), multipathd(8), udev(7), udevadm(8), zipl(8)

---

that's the whole page, bestie. mwah 💋 — this manual comes from s390-tools 2.37.0-build-20250312, dated 2025-03-12. stay iconic, and may your re-IPL paths always slay. 👑✨