From 88619b6dbac5e4447e6515aadb711e1703fbac40 Mon Sep 17 00:00:00 2001 From: Benjamin Block Date: Mon, 27 Sep 2021 21:35:18 +0200 Subject: [PATCH] chreipl-fcp-mpath: documentation and man page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a README.md for chreipl-fcp-mpath and infrastructure to build and install a man page generated from the README.md. Building and installing of the man page is only done when supplying the make option `ENABLE_DOC=1` (per default disabled). The `pandoc` utility is used to build the man page. The README.md is reused since there is no other tool or command as part of chreipl-fcp-mpath that needs to be documented in a separate man page. Also add information about chreipl-fcp-mpath to the main README.md and CHANGELOG.md. Reviewed-by: Steffen Maier Signed-off-by: Benjamin Block Signed-off-by: Jan Höppner --- CHANGELOG.md | 4 + README.md | 25 ++- chreipl-fcp-mpath/.gitignore | 5 + chreipl-fcp-mpath/Makefile | 61 ++++++ chreipl-fcp-mpath/README.md | 269 ++++++++++++++++++++++++ chreipl-fcp-mpath/chreipl-fcp-mpath.mak | 30 +++ 6 files changed, 389 insertions(+), 5 deletions(-) create mode 100644 chreipl-fcp-mpath/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 56c4ce77..6ffa65a6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,10 @@ Release history for s390-tools (MIT version) For Linux kernel version: 5.xx + Add new tools / libraries: + - chreipl-fcp-mpath: New toolset that uses multipath information to change + the configured FCP re-IPL path on detecting issues with the current path + Changes of existing tools: Bug Fixes: diff --git a/README.md b/README.md index 085f44ed..eb5c81fd 100644 --- a/README.md +++ b/README.md @@ -270,6 +270,10 @@ Package contents can be time consuming and prevent the HSA memory from being reused by other LPARs. + * chreipl-fcp-mpath: + Use multipath information to change the configured FCP re-IPL path on + detecting issues with the current path. + For more information refer to the following publications: * "Device Drivers, Features, and Commands" chapter "Useful Linux commands" @@ -307,11 +311,11 @@ build options: This table lists additional build or install options: -| __COMPONENT__ | __OPTION__ | __TOOLS__ | -|------------------|:----------------------------:|:--------------:| -| dracut | `HAVE_DRACUT` | zdev | -| initramfs-tools | `HAVE_INITRAMFS` | zdev | -| | `ZDEV_ALWAYS_UPDATE_INITRD` | zdev | +| __COMPONENT__ | __OPTION__ | __TOOLS__ | +|------------------|:----------------------------:|:-----------------------:| +| dracut | `HAVE_DRACUT` | zdev, chreipl-fcp-mpath | +| initramfs-tools | `HAVE_INITRAMFS` | zdev | +| | `ZDEV_ALWAYS_UPDATE_INITRD` | zdev | The s390-tools build process uses "pkg-config" if available and hard-coded compiler and linker options otherwise. @@ -465,3 +469,14 @@ the different tools are provided: (libxml2-devel.rpm), and libcurl version 7.59 or newer (libcurl-devel.rpm). Tip: you may skip the libkmipclient build by adding `HAVE_OPENSSL=0`, `HAVE_JSONC=0`, `HAVE_LIBXML2=0`, or `HAVE_LIBCURL=0` to the make invocation. + +* chreipl-fcp-mpath: + For a complete list and documentation of the requirements, installation and + uninstallation, please see + [chreipl-fcp-mpath/README.md](chreipl-fcp-mpath/README.md). + + Summarized: chreipl-fcp-mpath requires GNU Bash, GNU Core Utilities, + util-linux, udev, and multipath-tools. When using `HAVE_DRACUT=1` with the + make invocation, it also requires dracut. When using `ENABLE_DOC=1` with the + make invocation to build a man page and render the README.md as HTML, make + further requires pandoc, GNU awk, and GNU Gzip for the build process. diff --git a/chreipl-fcp-mpath/.gitignore b/chreipl-fcp-mpath/.gitignore index 203a7f6d..46111959 100644 --- a/chreipl-fcp-mpath/.gitignore +++ b/chreipl-fcp-mpath/.gitignore @@ -6,3 +6,8 @@ /chreipl-fcp-mpath-record-volume-identifier /chreipl-fcp-mpath-try-change-ipl-path /dracut/dracut.conf.d/70-chreipl-fcp-mpath.conf +/README.html +/README.pdf +/chreipl-fcp-mpath.md +/chreipl-fcp-mpath.7 +/chreipl-fcp-mpath.7.gz diff --git a/chreipl-fcp-mpath/Makefile b/chreipl-fcp-mpath/Makefile index 1bd40015..80cab7f1 100644 --- a/chreipl-fcp-mpath/Makefile +++ b/chreipl-fcp-mpath/Makefile @@ -11,6 +11,11 @@ # - chreipl-fcp-mpath.mak # bash: # - bash +# If $(ENABLE_DOC) is `1`: +# GNU Gzip: +# - gzip +# GNU awk: +# - gawk override SHELL := /bin/bash override .SHELLFLAGS := -O globstar -O nullglob -O extglob -c @@ -77,6 +82,40 @@ chreipl-fcp-mpath-dracut-clean: chreipl-fcp-mpath: dracut/dracut.conf.d/70-chreipl-fcp-mpath.conf chreipl-fcp-mpath-clean: chreipl-fcp-mpath-dracut-clean +ifeq ($(ENABLE_DOC),1) + +.PHONY: chreipl-fcp-mpath-doc +chreipl-fcp-mpath-doc: README.html chreipl-fcp-mpath.7 + +ifeq ($(ENABLE_DOC_PDF),1) +chreipl-fcp-mpath-doc: README.pdf + +README.pdf: PANDOCFLAGS += -M title="chreipl-fcp-mpath" -M subtitle="README" +endif + +README.html: PANDOCFLAGS += -M title="chreipl-fcp-mpath" -M subtitle="README" + +chreiplzfcpmp-doc-man-meta = \ + -M title="CHREIPL-FCP-MPATH" \ + -V header="Administrator Manual" \ + -V section="7" \ + -V footer="s390-tools $(S390_TOOLS_RELEASE)" + +chreipl-fcp-mpath.7: PANDOCFLAGS += $(chreiplzfcpmp-doc-man-meta) + +.INTERMEDIATE: chreipl-fcp-mpath.md +chreipl-fcp-mpath.md: README.md + gawk -- '/NOT-IN-MAN \{/,/NOT-IN-MAN \}/ { next } { print }' $(<) > $(@) + +.PHONY: chreipl-fcp-mpath-doc-clean +chreipl-fcp-mpath-doc-clean: + rm -f README.html README.pdf chreipl-fcp-mpath.md chreipl-fcp-mpath.7 + +chreipl-fcp-mpath: chreipl-fcp-mpath-doc +chreipl-fcp-mpath-clean: chreipl-fcp-mpath-doc-clean + +endif + # ## Install # @@ -139,6 +178,28 @@ chreipl-fcp-mpath-install: chreipl-fcp-mpath-install-dracut-config endif +ifeq ($(ENABLE_DOC),1) + +# chreipl-fcp-mpath: install man page +INSTDIRS += $(MANDIR) + +.PHONY: chreipl-fcp-mpath-install-man-page +chreipl-fcp-mpath-install-man-page: | $(DESTDIR)$(MANDIR)/man7 +chreipl-fcp-mpath-install-man-page: chreipl-fcp-mpath.7 + $(GZIP) -fk --best chreipl-fcp-mpath.7 + $(INSTALL_DATA) -t $(DESTDIR)$(MANDIR)/man7 \ + chreipl-fcp-mpath.7.gz + +chreipl-fcp-mpath-install: chreipl-fcp-mpath-install-man-page + +.PHONY: chreipl-fcp-mpath-install-man-page-clean +chreipl-fcp-mpath-install-man-page-clean: + rm -f chreipl-fcp-mpath.7.gz + +chreipl-fcp-mpath-clean: chreipl-fcp-mpath-install-man-page-clean + +endif + # ## Utility # diff --git a/chreipl-fcp-mpath/README.md b/chreipl-fcp-mpath/README.md new file mode 100644 index 00000000..3943f736 --- /dev/null +++ b/chreipl-fcp-mpath/README.md @@ -0,0 +1,269 @@ + + +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](#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: \:\:\. + +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](#requirements): + + - GNU Bash; + - GNU Core Utilities (mktemp, readlink, sync, truncate); + - util-linux (flock, hexdump, logger); + - udev / systemd-udev; + - multipath-tools. + +To make use of the optional dracut configuration you need: dracut. + +To build and install the documentation (man page) you need: + + - pandoc; + - GNU Core Utilities (date); + - GNU awk; + - GNU Gzip. + +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 and install a 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 and documentation 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.gz + +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](#installation)), reload the udev rules database, and rebuild all +modified initial ramdisks as described in [INSTALLATION](#installation)). + + + +EXAMPLES +======== + +Manual Changes to the Configured re-IPL Device +---------------------------------------------- + +As outlined in [DESCRIPTION](#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]( "Link to the s390-tools Issues page"). + +SEE ALSO +======== + +**chreipl**(8), **dracut**(8), **journalctl**(1), **lsreipl(8)**, +**lszfcp**(8), **multipath**(8), **multipathd**(8), **udev**(7), +**udevadm**(8), **zipl**(8) diff --git a/chreipl-fcp-mpath/chreipl-fcp-mpath.mak b/chreipl-fcp-mpath/chreipl-fcp-mpath.mak index 9d0c9d64..d6299d39 100644 --- a/chreipl-fcp-mpath/chreipl-fcp-mpath.mak +++ b/chreipl-fcp-mpath/chreipl-fcp-mpath.mak @@ -8,6 +8,11 @@ # https://www.gnu.org/software/make/manual/make.html#Utilities-in-Makefiles # GNU coreutils: # - mktemp +# If $(ENABLE_DOC) is `1`: +# Pandoc: +# - pandoc +# GNU coreutils: +# - date # ## Paths and Build Variables @@ -17,6 +22,9 @@ # toolset into the initial ramdisk, when built with it. HAVE_DRACUT = 0 +# Build documentation; requires: Pandoc +ENABLE_DOC = 0 + # https://www.gnu.org/software/make/manual/make.html#Directory-Variables CHREIPLZFCPMPDIR = $(USRLIBDIR)/chreipl-fcp-mpath UDEVDIR = $(USRLIBDIR)/udev @@ -61,3 +69,25 @@ endef clean: clean-mk-temp clean-mk-temp: rm -f .make.tmp.[[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]][[:alnum:]] + +# Definitions for generating documentation when $(ENABLE_DOC) is set to `1` + +PANDOCFLAGS = --fail-if-warnings +ALL_PANDOCFLAGS = --preserve-tabs --tab-stop=8 --strip-comments \ + --standalone --self-contained \ + -M date="$(shell date +'%Y-%m-%d')" \ + $(PANDOCFLAGS) + +$(eval $(call cmd_define, PANDOC," PANDOC ",pandoc)) + +%.html : ALL_PANDOCFLAGS += -t html +%.html : %.md + $(PANDOC) $(ALL_PANDOCFLAGS) -f gfm -o $(@) $(<) + +%.pdf : ALL_PANDOCFLAGS += -t latex --toc +%.pdf : %.md + $(PANDOC) $(ALL_PANDOCFLAGS) -f gfm -o $(@) $(<) + +%.7 : ALL_PANDOCFLAGS += -t man +%.7 : %.md + $(PANDOC) $(ALL_PANDOCFLAGS) -f gfm -o $(@) $(<)