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" .TH "CHREIPL\-FCP\-MPATH" "7" "2025\-03\-12" "s390-tools 2.37.0-build-20250312" "Administrator Manual"
.hy
.SH NAME .SH NAME
.PP chreipl\-fcp\-mpath \- use multipath information for re\-IPL path
chreipl-fcp-mpath - use multipath information for re-IPL path failover failover on a running Linux instance
on a running Linux instance
.SH DESCRIPTION .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. volume uses exactly one path to the volume.
If this path is unavailable, the IPL fails. If this path is unavailable, the IPL fails.
.PP .PP
The \f[B]chreipl-fcp-mpath\f[R] toolset monitors \f[B]udev\f[R] events The \f[B]chreipl\-fcp\-mpath\f[R] toolset monitors \f[B]udev\f[R] events
about paths to the re-IPL volume. about paths to the re\-IPL volume.
If the currently configured re-IPL path becomes unavailable, the toolset If the currently configured re\-IPL path becomes unavailable, the
checks for operational paths to the same volume. toolset checks for operational paths to the same volume.
If available, it reconfigures the re-IPL settings to use an operational If available, it reconfigures the re\-IPL settings to use an operational
path. path.
.PP .PP
Thus, re-IPL from an FCP-attached SCSI volume can be successful despite Thus, re\-IPL from an FCP\-attached SCSI volume can be successful
path failures on a running Linux instance if at least one path to the despite path failures on a running Linux instance if at least one path
re-IPL volume remains operational. to the re\-IPL volume remains operational.
.PP .PP
\f[B]Chreipl-fcp-mpath\f[R] requires \f[B]udev\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]. \f[B]multipathd\f[R] and \f[B]dm\-multipath\f[R].
Once installed, the toolset runs automatically and autonomously. Once installed, the toolset runs automatically and autonomously.
No user intervention is possible or required. No user intervention is possible or required.
.PP .PP
Other than installing the toolset, there is no user interface for 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 .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: the Linux instance that is being monitored:
.IP \[bu] 2 .IP \[bu] 2
The Linux instance must have started successfully, during IPL. The Linux instance must have started successfully, during IPL.
.IP \[bu] 2 .IP \[bu] 2
The running Linux instance must use \f[B]dm-multipath\f[R] and 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 \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 contains a zipl boot record and has one of its paths used in the re\-IPL
configuration. configuration.
.IP \[bu] 2 .IP \[bu] 2
\f[B]udev\f[R] must run. \f[B]udev\f[R] must run.
.IP \[bu] 2 .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. path.
Examples for such events are: the SCSI disk comes online, or a path of 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 corresponding multipath device goes down or comes back online.
.RS 2 .RS 2
.IP \[bu] 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. is running.
.RE .RE
.IP \[bu] 2 .IP \[bu] 2
When the configured re-IPL path becomes unavailable while the Linux When the configured re\-IPL path becomes unavailable while the Linux
instance is running, at least one operational path to the re-IPL volume instance is running, at least one operational path to the re\-IPL volume
must be available, or must become available. must be available, or must become available.
If no such path is available when the Linux instance is rebooted, the 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 .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. and operational.
.RS 2 .RS 2
.PP .PP
The tool treats a newly configured re-IPL device like the initially The tool treats a newly configured re\-IPL device like the initially
configured re-IPL device. configured re\-IPL device.
In particular, if the newly configured re-IPL device fulfills the In particular, if the newly configured re\-IPL device fulfills the
requirements of the tool, re-IPL path failover takes place if the requirements of the tool, re\-IPL path failover takes place if the
configured re-IPL path becomes unavailable. configured re\-IPL path becomes unavailable.
.RE .RE
.SS Caution with Manual Changes to the Configured re-IPL Target .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
\f[B]chreipl-fcp-mpath\f[R] is designed to accept operator-inititated changes of the re\-IPL device.
changes of the re-IPL device.
However, concurrent changes by the operator and tool driven changes can However, concurrent changes by the operator and tool driven changes can
result in the operator change being overwritten. result in the operator change being overwritten.
.PP .PP
To avoid this problem, change the re-IPL device only during steady-state To avoid this problem, change the re\-IPL device only during
operations, when no path events happen. steady\-state operations, when no path events happen.
Alternatively, make sure that no events are processed while you change Alternatively, make sure that no events are processed while you change
the device. the device.
See EXAMPLES for one way to suspend event processing. See EXAMPLES for one way to suspend event processing.
.SH MESSAGES .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. writes messages to the syslog.
.PP .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]): same volume (priority \f[I]daemon.notice\f[R]):
.RS .RS
.PP .PP
Changed re-IPL path to: <device-bus-id>:<wwpn>:<lun>. Changed re\-IPL path to: <device\-bus\-id>:<wwpn>:<lun>.
.RE .RE
.PP .PP
When a path event indicates that the last available path has become 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 .RS
.PP .PP
The re-IPL device cannot be changed because no operational path to the The re\-IPL device cannot be changed because no operational path to the
re-IPL volume remains. re\-IPL volume remains.
The next re-IPL might fail unless you re-attach or enable at least one The next re\-IPL might fail unless you re\-attach or enable at least one
valid path to the re-IPL volume. valid path to the re\-IPL volume.
.RE .RE
.PP .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]): with the used Linux kernel interface (priority \f[I]daemon.crit\f[R]):
.RS .RS
.PP .PP
Changing the re-IPL device failed. Changing the re\-IPL device failed.
The current re-IPL settings might be inconsistent. The current re\-IPL settings might be inconsistent.
Check and correct the settings (see the README.md of chreipl-fcp-mpath) Check and correct the settings (see the README.md of
to make sure that the current re-IPL device is valid. chreipl\-fcp\-mpath) to make sure that the current re\-IPL device is
valid.
.RE .RE
.PP .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 setting that cannot be corrected automatically by
\f[B]chreipl-fcp-mpath\f[R]. \f[B]chreipl\-fcp\-mpath\f[R].
As a result, the next re-IPL might fail or might not use the intended As a result, the next re\-IPL might fail or might not use the intended
re-IPL device. re\-IPL device.
.PP .PP
You can use the following tools to check and correct the current You can use the following tools to check and correct the current
settings: settings:
.IP \[bu] 2 .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; configured;
.IP \[bu] 2 .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 .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. device.
.SH EXAMPLES .SH EXAMPLES
.SS Manual Changes to the Configured re-IPL Device .SS Manual Changes to the Configured re\-IPL Device
.PP
As outlined in DESCRIPTION, be cautious when manually changing the 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 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 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 You need \f[I]root\f[R] privileges for running the commands in the
following example: following example:
.IP .IP
.nf .EX
\f[C]
\[ti] # udevadm settle \[ti] # udevadm settle
\[ti] # udevadm control --stop-exec-queue \[ti] # udevadm control \-\-stop\-exec\-queue
\[ti] # chreipl ... \[ti] # chreipl ...
\[ti] # udevadm control --start-exec-queue \[ti] # udevadm control \-\-start\-exec\-queue
\f[R] .EE
.fi
.SS Listing messages with journalctl .SS Listing messages with journalctl
.PP
If your Linux instance includes \f[B]journalctl\f[R], use the following If your Linux instance includes \f[B]journalctl\f[R], use the following
command to list all messages that are issued by command to list all messages that are issued by
\f[B]chreipl-fcp-mpath\f[R]: \f[B]chreipl\-fcp\-mpath\f[R]:
.IP .IP
.nf .EX
\f[C] \[ti] # journalctl \-t chreipl\-fcp\-mpath
\[ti] # journalctl -t chreipl-fcp-mpath .EE
\f[R]
.fi
.PP .PP
To list only messages that were issued since the last IPL, use this To list only messages that were issued since the last IPL, use this
command: command:
.IP .IP
.nf .EX
\f[C] \[ti] # journalctl \-t chreipl\-fcp\-mpath \-b
\[ti] # journalctl -t chreipl-fcp-mpath -b .EE
\f[R]
.fi
.SH REPORTING BUGS .SH REPORTING BUGS
.PP
Use the \f[B]Issues\f[R] functionality on GitHub to report any bugs in Use the \f[B]Issues\f[R] functionality on GitHub to report any bugs in
\f[B]chreipl-fcp-mpath\f[R]: s390-tools \f[B]chreipl\-fcp\-mpath\f[R]: \c
Issues (https://github.com/ibm-s390-linux/s390-tools/issues). .UR https://github.com/ibm-s390-linux/s390-tools/issues
s390\-tools Issues
.UE \c
\&.
.SH SEE ALSO .SH SEE ALSO
.PP
\f[B]chreipl\f[R](8), \f[B]dracut\f[R](8), \f[B]journalctl\f[R](1), \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]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]multipathd\f[R](8), \f[B]udev\f[R](7), \f[B]udevadm\f[R](8),