Skip to content

Latest commit

 

History

History
270 lines (190 loc) · 10.2 KB

README.md

File metadata and controls

270 lines (190 loc) · 10.2 KB
Raw

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.

SOFTWARE REQUIREMENTS

chreipl-fcp-mpath integrates into s390-tools's build and install infrastructure. Use make to build it. No explicit dependency management is in place, but the toolset has some software dependencies besides the requirements in section Requirements:

  • GNU Bash;
  • GNU Core Utilities (mktemp, readlink, sync, truncate, sha256sum);
  • util-linux (flock, hexdump, logger);
  • udev / systemd-udev;
  • multipath-tools.

To make use of the optional dracut configuration you need: dracut.

To build a fresh version of the documentation (man page) you need:

  • pandoc;
  • GNU Core Utilities (date);
  • GNU awk;

otherwise the pre-cooked version shipped with the source will be used.

INSTALLATION

If your distribution includes a packaged version of chreipl-fcp-mpath, either as a separate package or as part of a s390-tools package, install that package. Otherwise, you can either install it from source as part of s390-tools or separately.

To install chreipl-fcp-mpath as part of s390-tools, use make on the top-level directory of your s390-tools distribution. Installing the entire distribution might overwrite other already installed tools.

To install the tool separately, change into the chreipl-fcp-mpath directory, and use make there.

You need root privileges to install the tool into the root file system.

Calling make runs the build steps. Calling make install runs the build steps and copies the resulting components to their final destination. s390-tools offers more options and targets to customize the build (see make help).

chreipl-fcp-mpath has the following optional build options:

Option Values Default Effect
HAVE_DRACUT 0, 1 0 Install a dracut configuration file that includes chreipl-fcp-mpath in the initial ramdisks built with dracut.
ENABLE_DOC 0, 1 0 Build a fresh version of the man page for chreipl-fcp-mpath.

Specify any options as arguments for both the make and make install command as shown in the following example:

~ # cd chreipl-fcp-mpath/
~ # make HAVE_DRACUT=1 ENABLE_DOC=1
~ # make HAVE_DRACUT=1 ENABLE_DOC=1 install

After the installation, reload the udev rules database:

~ # udevadm control --reload

The toolset is now active on your running Linux instance.

If you use the HAVE_DRACUT=1 option, also rebuild your initial ramdisk, to immediately include the toolset instead of waiting for the next kernel update.

How to rebuild the initial ramdisk and the naming scheme for the resulting file or files depends on your distribution. The following example applies to Fedora and to Red Hat Enterprise Linux:

~ # dracut --force /boot/initramfs-"$(uname -r)".img "$(uname -r)"

For SUSE Linux Enterprise Server run for example:

~ # dracut --hostonly --force /boot/initrd-"$(uname -r)" "$(uname -r)"

These commands replace the initial ramdisk for the currently running kernel. If your distribution uses zipl as its boot loader, run zipl to refresh the boot record to find the new initial ramdisk.

~ # zipl

With dracut enabled, make install deploys the following files to these default locations:

/usr/lib/chreipl-fcp-mpath/chreipl-fcp-mpath-common.sh
/usr/lib/dracut/dracut.conf.d/70-chreipl-fcp-mpath.conf
/usr/lib/udev/chreipl-fcp-mpath-is-ipl-tgt
/usr/lib/udev/chreipl-fcp-mpath-is-ipl-vol
/usr/lib/udev/chreipl-fcp-mpath-is-reipl-zfcp
/usr/lib/udev/chreipl-fcp-mpath-record-volume-identifier
/usr/lib/udev/chreipl-fcp-mpath-try-change-ipl-path
/usr/lib/udev/rules.d/70-chreipl-fcp-mpath.rules
/usr/share/man/man7/chreipl-fcp-mpath.7

UNINSTALL

If your distribution includes a separately from s390-tools packaged version of chreipl-fcp-mpath, uninstall that package.

For installations without distribution packaging, you cannot uninstall chreipl-fcp-mpath with make.

Instead, remove the toolset by deleting the installed files as listed in INSTALLATION), reload the udev rules database, and rebuild all modified initial ramdisks as described in INSTALLATION).

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)