Scroll to navigation

CHREIPL-FCP-MPATH(7) Administrator Manual CHREIPL-FCP-MPATH(7)

NAME

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

DESCRIPTION

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.

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.

Chreipl-fcp-mpath requires udev, multipathd and dm-multipath. Once installed, the toolset runs automatically and autonomously. No user intervention is possible or required.

Other than installing the toolset, there is no user interface for chreipl-fcp-mpath.

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.

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.

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)

2025-03-12 s390-tools 2.37.0-build-20250312