From 0d15a07c0a5842a359554b6fb5f8cba3d11fd5cc Mon Sep 17 00:00:00 2001 From: Benjamin Block Date: Tue, 30 Nov 2021 18:54:35 +0100 Subject: [PATCH] chreipl-fcp-mpath: bundle a pre-cooked version of the man page MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit On several distributions `pandoc` is not available via the default repositories, and thus not available in the build environments for the distribution packages. That means, the man page can't be bundled along with the packages generated for those distributions. But since this is a valuable asset for some users, instead of requiring `pandoc` in order to have a man page be generated during the build, so it can be installed, bundle a pre-cooked version that corresponds to the current version of the `README.md` file. This way, the man page can always be packaged, and is now always installed, even if `ENABLE_DOC` is set to `0` (the default). This also means, whenever the `README.md` file is changed, the bundled man page needs to be regenerated, so it stays in sync. As a safeguard we also add a checksum of the `README.md` file that is regenerated along with the man page. This checksum is tested even when `pandoc` is not available, and the user is notified whenever it runs out of sync (with a hint as to how to remedy it). Nothing changes for the compile/installation workflow, if `ENABLE_DOC` is set to `1`. Suggested-by: Jens Remus Reviewed-by: Steffen Maier Signed-off-by: Benjamin Block Signed-off-by: Jan Höppner --- CHANGELOG.md | 2 + README.md | 5 +- chreipl-fcp-mpath/.chreipl-fcp-mpath.7.cksum | 1 + chreipl-fcp-mpath/.gitignore | 1 - chreipl-fcp-mpath/Makefile | 29 ++- chreipl-fcp-mpath/README.md | 14 +- chreipl-fcp-mpath/chreipl-fcp-mpath.7 | 183 +++++++++++++++++++ 7 files changed, 221 insertions(+), 14 deletions(-) create mode 100644 chreipl-fcp-mpath/.chreipl-fcp-mpath.7.cksum create mode 100644 chreipl-fcp-mpath/chreipl-fcp-mpath.7 diff --git a/CHANGELOG.md b/CHANGELOG.md index eda87f46..0f9c68fe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,6 +10,8 @@ Release history for s390-tools (MIT version) - dbginfo.sh: rework script formatting (indents, order) - dbginfo.sh: update sysfs collection (excludes, messages) - dbginfo.sh: replace "which" by builtin command "type" + - chreipl-fcp-mpath: bundle a pre-cooked version of the manpage for + build environments without access to `pandoc` Bug Fixes: diff --git a/README.md b/README.md index 21ad2d8b..069c6a53 100644 --- a/README.md +++ b/README.md @@ -478,5 +478,6 @@ the different tools are provided: 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 and GNU awk for the build process. + make invocation to build a fresh man page (instead of using the pre-cooked + version) and render the README.md as HTML, make further requires pandoc and + GNU awk for the build process. diff --git a/chreipl-fcp-mpath/.chreipl-fcp-mpath.7.cksum b/chreipl-fcp-mpath/.chreipl-fcp-mpath.7.cksum new file mode 100644 index 00000000..56e76090 --- /dev/null +++ b/chreipl-fcp-mpath/.chreipl-fcp-mpath.7.cksum @@ -0,0 +1 @@ +8e604dab39577678bc9f24bfe5e2ee35354b2f4b1759edd16093157b1ecce9d3 README.md diff --git a/chreipl-fcp-mpath/.gitignore b/chreipl-fcp-mpath/.gitignore index ecd49eee..53c41de9 100644 --- a/chreipl-fcp-mpath/.gitignore +++ b/chreipl-fcp-mpath/.gitignore @@ -9,4 +9,3 @@ /README.html /README.pdf /chreipl-fcp-mpath.md -/chreipl-fcp-mpath.7 diff --git a/chreipl-fcp-mpath/Makefile b/chreipl-fcp-mpath/Makefile index 6cf65a3f..e7fb920d 100644 --- a/chreipl-fcp-mpath/Makefile +++ b/chreipl-fcp-mpath/Makefile @@ -11,6 +11,8 @@ # - chreipl-fcp-mpath.mak # bash: # - bash +# GNU coreutils: +# - sha256sum # If $(ENABLE_DOC) is `1`: # GNU awk: # - gawk @@ -100,20 +102,41 @@ chreiplzfcpmp-doc-man-meta = \ -V footer="s390-tools $(S390_TOOLS_RELEASE)" chreipl-fcp-mpath.7: PANDOCFLAGS += $(chreiplzfcpmp-doc-man-meta) +chreipl-fcp-mpath.7: .chreipl-fcp-mpath.7.cksum .INTERMEDIATE: chreipl-fcp-mpath.md chreipl-fcp-mpath.md: README.md gawk -- '/NOT-IN-MAN \{/,/NOT-IN-MAN \}/ { next } { print }' $(<) > $(@) +.chreipl-fcp-mpath.7.cksum: README.md + sha256sum $(<) > $(@) + .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 + rm -f README.html README.pdf chreipl-fcp-mpath.md chreipl-fcp-mpath: chreipl-fcp-mpath-doc chreipl-fcp-mpath-clean: chreipl-fcp-mpath-doc-clean +else # $(ENABLE_DOC) != 1 + +# We bundle a pre-cooked man page with the source-code so that distributions +# don't need `pandoc` in order to be able to ship the man page. As of this +# writing multiple distributions don't have a packaged version of it. +# +# In order to remember to regenerate this pre-cooked version whenever the +# README.md is changed, we also generate a checksum of the README.md, bundle +# that as well, and compare that whenever `make` is called. This way, the +# freshness of the man page can be checked, even if `pandoc` is not available, +# or ENABLE_DOC disabled. + +MANPAGE_FRESH := $(shell sha256sum --check .chreipl-fcp-mpath.7.cksum >/dev/null && echo 1 || echo 0) +ifeq ($(MANPAGE_FRESH),0) +$(warning chreipl-fcp-mpath.7 is outdated, please regenerate it by calling `make ENABLE_DOC=1`) endif +endif # $(ENABLE_DOC) == 1 + # ## Install # @@ -180,8 +203,6 @@ chreipl-fcp-mpath-install: chreipl-fcp-mpath-install-dracut-config endif -ifeq ($(ENABLE_DOC),1) - # chreipl-fcp-mpath: install man page INSTDIRS += $(MANDIR) $(DESTDIR)$(MANDIR)/man7: install_dirs @@ -194,8 +215,6 @@ chreipl-fcp-mpath-install-man-page: chreipl-fcp-mpath.7 chreipl-fcp-mpath-install: chreipl-fcp-mpath-install-man-page -endif - # ## Utility # diff --git a/chreipl-fcp-mpath/README.md b/chreipl-fcp-mpath/README.md index d58ccd2c..3d69ad54 100644 --- a/chreipl-fcp-mpath/README.md +++ b/chreipl-fcp-mpath/README.md @@ -120,18 +120,20 @@ 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); + - 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 and install the documentation (man page) you need: +To build a fresh version of the documentation (man page) you need: - pandoc; - GNU Core Utilities (date); - - GNU awk. + - GNU awk; + +otherwise the pre-cooked version shipped with the source will be used. INSTALLATION ============ @@ -160,7 +162,7 @@ steps and copies the resulting components to their final destination. | 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**. +| 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: @@ -195,8 +197,8 @@ 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: +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 diff --git a/chreipl-fcp-mpath/chreipl-fcp-mpath.7 b/chreipl-fcp-mpath/chreipl-fcp-mpath.7 new file mode 100644 index 00000000..1b8eda87 --- /dev/null +++ b/chreipl-fcp-mpath/chreipl-fcp-mpath.7 @@ -0,0 +1,183 @@ +.\" Automatically generated by Pandoc 2.16.1 +.\" +.TH "CHREIPL-FCP-MPATH" "7" "2022-02-24" "s390-tools 2.20.0-build-20220224" "Administrator Manual" +.hy +.SH NAME +.PP +chreipl-fcp-mpath - use multipath information for re-IPL path failover +on a running Linux instance +.SH DESCRIPTION +.PP +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. +.PP +The \f[B]chreipl-fcp-mpath\f[R] toolset monitors \f[B]udev\f[R] 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. +.PP +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. +.PP +\f[B]Chreipl-fcp-mpath\f[R] requires \f[B]udev\f[R], +\f[B]multipathd\f[R] and \f[B]dm-multipath\f[R]. +Once installed, the toolset runs automatically and autonomously. +No user intervention is possible or required. +.PP +Other than installing the toolset, there is no user interface for +\f[B]chreipl-fcp-mpath\f[R]. +.SS Requirements +.PP +The \f[B]chreipl-fcp-mpath\f[R] tool has the following requirements on +the Linux instance that is being monitored: +.IP \[bu] 2 +The Linux instance must have started successfully, during IPL. +.IP \[bu] 2 +The running Linux instance must use \f[B]dm-multipath\f[R] and +\f[B]multipathd\f[R] 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. +.IP \[bu] 2 +\f[B]udev\f[R] must run. +.IP \[bu] 2 +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. +.RS 2 +.IP \[bu] 2 +The WWID of the re-IPL volume must not change while the Linux instance +is running. +.RE +.IP \[bu] 2 +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. +.IP \[bu] 2 +The tool assumes that any manually reconfigured re-IPL device is valid +and operational. +.RS 2 +.PP +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. +.RE +.SS Caution with Manual Changes to the Configured re-IPL Target +.PP +\f[B]chreipl-fcp-mpath\f[R] 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. +.PP +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. +.SH MESSAGES +.PP +During monitoring and event processing, \f[B]chreipl-fcp-mpath\f[R] +writes messages to the syslog. +.PP +When the configured re-IPL path is changed to a different path to the +same volume (priority \f[I]daemon.notice\f[R]): +.RS +.PP +Changed re-IPL path to: ::. +.RE +.PP +When a path event indicates that the last available path has become +non-operational (priority \f[I]daemon.alert\f[R]): +.RS +.PP +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. +.RE +.PP +When changing the configured re-IPL device failed because of an error +with the used Linux kernel interface (priority \f[I]daemon.crit\f[R]): +.RS +.PP +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. +.RE +.PP +A failure to change the re-IPL device can indicate an inconsistent +setting that cannot be corrected automatically by +\f[B]chreipl-fcp-mpath\f[R]. +As a result, the next re-IPL might fail or might not use the intended +re-IPL device. +.PP +You can use the following tools to check and correct the current +settings: +.IP \[bu] 2 +\f[B]lsreipl\f[R] to confirm that the intended re-IPL device is +configured; +.IP \[bu] 2 +\f[B]chreipl\f[R] to change the re-IPL device; +.IP \[bu] 2 +\f[B]lszfcp\f[R] to inspect the state of available paths to the re-IPL +device. +.SH EXAMPLES +.SS Manual Changes to the Configured re-IPL Device +.PP +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 \f[B]chreipl-fcp-mpath\f[R]. +You can avoid such collisions, by stopping event processing, making your +changes, and then re-enabling event processing. +You need \f[I]root\f[R] privileges for running the commands in the +following example: +.IP +.nf +\f[C] +\[ti] # udevadm settle +\[ti] # udevadm control --stop-exec-queue +\[ti] # chreipl ... +\[ti] # udevadm control --start-exec-queue +\f[R] +.fi +.SS Listing messages with journalctl +.PP +If your Linux instance includes \f[B]journalctl\f[R], use the following +command to list all messages that are issued by +\f[B]chreipl-fcp-mpath\f[R]: +.IP +.nf +\f[C] +\[ti] # journalctl -t chreipl-fcp-mpath +\f[R] +.fi +.PP +To list only messages that were issued since the last IPL, use this +command: +.IP +.nf +\f[C] +\[ti] # journalctl -t chreipl-fcp-mpath -b +\f[R] +.fi +.SH REPORTING BUGS +.PP +Use the \f[B]Issues\f[R] functionality on GitHub to report any bugs in +\f[B]chreipl-fcp-mpath\f[R]: s390-tools +Issues (https://github.com/ibm-s390-linux/s390-tools/issues). +.SH SEE ALSO +.PP +\f[B]chreipl\f[R](8), \f[B]dracut\f[R](8), \f[B]journalctl\f[R](1), +\f[B]lsreipl(8)\f[R], \f[B]lszfcp\f[R](8), \f[B]multipath\f[R](8), +\f[B]multipathd\f[R](8), \f[B]udev\f[R](7), \f[B]udevadm\f[R](8), +\f[B]zipl\f[R](8)