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)