kata-containers/s390-tools
1
0
Fork 0
mirror of https://github.com/ibm-s390-linux/s390-tools.git synced 2026-08-05 02:14:52 +00:00
Code Issues Packages Projects Releases Wiki Activity

chreipl-fcp-mpath: bundle a pre-cooked version of the man page

Browse Source 
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 <jremus@linux.ibm.com>
Reviewed-by: Steffen Maier <maier@linux.ibm.com>
Signed-off-by: Benjamin Block <bblock@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
This commit is contained in:
Benjamin Block
2021-11-30 18:54:35 +01:00
committed by Jan Höppner
parent 5394cd363c
commit 0d15a07c0a
7 changed files with 221 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
CHANGELOG.md
View File

@@ -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:

5
README.md
View File

@@ -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.

1
chreipl-fcp-mpath/.chreipl-fcp-mpath.7.cksum Normal file
View File

@@ -0,0 +1 @@
8e604dab39577678bc9f24bfe5e2ee35354b2f4b1759edd16093157b1ecce9d3 README.md

1
chreipl-fcp-mpath/.gitignore vendored
View File

@@ -9,4 +9,3 @@
/README.html
/README.pdf
/chreipl-fcp-mpath.md
/chreipl-fcp-mpath.7

29
chreipl-fcp-mpath/Makefile
View File

@@ -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
#

14
chreipl-fcp-mpath/README.md
View File

@@ -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

183
chreipl-fcp-mpath/chreipl-fcp-mpath.7 Normal file
View File

@@ -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: <device-bus-id>:<wwpn>:<lun>.
.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)