mirror of
https://github.com/ibm-s390-linux/s390-tools.git
synced 2026-08-05 02:14:52 +00:00
4fe6025b18
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>
172 lines
6.2 KiB
Groff
172 lines
6.2 KiB
Groff
.\" Automatically generated by Pandoc 3.1.11.1
|
|
.\"
|
|
.TH "CHREIPL\-FCP\-MPATH" "7" "2025\-03\-12" "s390-tools 2.37.0-build-20250312" "Administrator Manual"
|
|
.SH NAME
|
|
chreipl\-fcp\-mpath \- use multipath information for re\-IPL path
|
|
failover on a running Linux instance
|
|
.SH DESCRIPTION
|
|
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
|
|
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
|
|
\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
|
|
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
|
|
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
|
|
.EX
|
|
\[ti] # udevadm settle
|
|
\[ti] # udevadm control \-\-stop\-exec\-queue
|
|
\[ti] # chreipl ...
|
|
\[ti] # udevadm control \-\-start\-exec\-queue
|
|
.EE
|
|
.SS Listing messages with journalctl
|
|
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
|
|
.EX
|
|
\[ti] # journalctl \-t chreipl\-fcp\-mpath
|
|
.EE
|
|
.PP
|
|
To list only messages that were issued since the last IPL, use this
|
|
command:
|
|
.IP
|
|
.EX
|
|
\[ti] # journalctl \-t chreipl\-fcp\-mpath \-b
|
|
.EE
|
|
.SH REPORTING BUGS
|
|
Use the \f[B]Issues\f[R] functionality on GitHub to report any bugs in
|
|
\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
|
|
\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)
|