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: Regenerate man page with new pandoc version

Browse Source 
Older versions of pandoc (<3.1.7) can sometimes produce incorrect man
page macros [1][2]. The chreipl-fcp-mpath man page had a few of those:

$ man --warnings -E UTF-8 -l -Tutf8 -Z chreipl-fcp-mpath/chreipl-fcp-mpath.7
troff:<standard input>:5: warning: cannot select font 'CB'
troff:<standard input>:160: warning: cannot select font 'C'
troff:<standard input>:174: warning: cannot select font 'C'
troff:<standard input>:183: warning: cannot select font 'C'

Regenerate the man page using pandoc 3.1.11 to fix those issues.

[1] https://github.com/jgm/pandoc/issues/9020
[2] https://github.com/bin-cli/bin-cli/issues/44
Github-ID: https://github.com/ibm-s390-linux/s390-tools/issues/170
Reviewed-by: Steffen Eiden <seiden@linux.ibm.com>
Signed-off-by: Jan Höppner <hoeppner@linux.ibm.com>
This commit is contained in:
Jan Höppner
2025-03-12 14:24:40 +01:00
parent 73b6a684ec
commit 4fe6025b18
1 changed files with 77 additions and 89 deletions
Download Patch File Download Diff File Expand all files Collapse all files

166
chreipl-fcp-mpath/chreipl-fcp-mpath.7
View File

@@ -1,182 +1,170 @@
.\" Automatically generated by Pandoc 2.16.1
.\" Automatically generated by Pandoc 3.1.11.1
.\"
.TH "CHREIPL-FCP-MPATH" "7" "2022-02-24" "s390-tools 2.20.0-build-20220224" "Administrator Manual"
.hy
.TH "CHREIPL\-FCP\-MPATH" "7" "2025\-03\-12" "s390-tools 2.37.0-build-20250312" "Administrator Manual"
.SH NAME
.PP
chreipl-fcp-mpath - use multipath information for re-IPL path failover
on a running Linux instance
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
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
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.
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].
\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].
\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 \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
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
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
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
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.
re\-IPL path is not changed.
.IP \[bu] 2
The tool assumes that any manually reconfigured re-IPL device is valid
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.
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.
.SS Caution with Manual Changes to the Configured re\-IPL Target
\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.
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]
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
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>.
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]):
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.
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
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.
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
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.
\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
\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;
\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
\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
.SS Manual Changes to the Configured re\-IPL Device
As outlined in DESCRIPTION, be cautious when manually changing the
configured re-IPL device.
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].
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.
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]
.EX
\[ti] # udevadm settle
\[ti] # udevadm control --stop-exec-queue
\[ti] # udevadm control \-\-stop\-exec\-queue
\[ti] # chreipl ...
\[ti] # udevadm control --start-exec-queue
\f[R]
.fi
\[ti] # udevadm control \-\-start\-exec\-queue
.EE
.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]:
\f[B]chreipl\-fcp\-mpath\f[R]:
.IP
.nf
\f[C]
\[ti] # journalctl -t chreipl-fcp-mpath
\f[R]
.fi
.EX
\[ti] # journalctl \-t chreipl\-fcp\-mpath
.EE
.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
.EX
\[ti] # journalctl \-t chreipl\-fcp\-mpath \-b
.EE
.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).
\f[B]chreipl\-fcp\-mpath\f[R]: \c
.UR https://github.com/ibm-s390-linux/s390-tools/issues
s390\-tools Issues
.UE \c
\&.
.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),