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>
Remove the call to `gzip` before installing the manpage during the
`make install` call. What and if compression is done should be handled by
the distribution tooling.
This also removes a dependency for the build process.
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>
Add a README.md for chreipl-fcp-mpath and infrastructure to build and
install a man page generated from the README.md. Building and installing
of the man page is only done when supplying the make option `ENABLE_DOC=1`
(per default disabled). The `pandoc` utility is used to build the man page.
The README.md is reused since there is no other tool or command as part of
chreipl-fcp-mpath that needs to be documented in a separate man page.
Also add information about chreipl-fcp-mpath to the main README.md and
CHANGELOG.md.
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>
Add a dracut configuration file that might optionally be installed along
with the toolset (per default to: $(USRLIBDIR)/dracut/dracut.conf.d). It
causes the udev rules and helper scripts to be included into an initial
ramdisk, when (re-)built with dracut; along with any dependency.
This is only done when passing `HAVE_DRACUT` set to 1 during the
installation (default is 0), e.g.: make install HAVE_DRACUT=1.
Enabling the toolset during the initial ramdisk phase has the advantage
that paths can be audited earlier in the life cycle of this Linux
runtime, e.g. to record the WWID in the ID-file.
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>
In the final step of the udev rules toolset, we either know that the
current event subject is the re-IPL target, a dm-multipath device with
the re-IPL target, or represents the same volume based on its WWID. As
such it is a candidate to replace the current re-IPL target.
The new helper `chreipl-fcp-mpath-try-change-ipl-path` will use the
subject itself - in case it is a single scsi disk -, or the dm-multipath
device, to test whether there is a path in a good state.
"Good state" is based on the zfcp device driver state
(<SDEV>/zfcp_failed, <SDEV>/zfcp_in_recovery), the scsi_transport_fc
port state (<SDEV>/../../fc_remote_ports/rport-*/port_state), and the
scsi device state (<SDEV>/state). A path is only considered if they all
indicate a device in good conditions.
If such a path is found, the helper will try to set it as new re-IPL
target regardless of whether the current re-IPL is still in good shape
or not. This is by design, and done to reduce complexity in further
state checking, and prevention of races with overlapping events in udev
(when executing in parallel workers).
Whenever a new re-IPL target is selected and set in
/sys/firmware/reipl/fcp/{device,wwpn,lun}, the helper will also update
the records in the ID-file - otherwise they might appear as stale, when
they aren't.
This step in the udev rule processing might also result in log messages
written to the syslog (using the utility `logger` from util-linux;
writing to /dev/log).
In case the re-IPL target is changed, a message with level notice is
logged, informing about the new target.
In case no good path is found as part of a dm-multipath device, a
message with level critical is logged, as it might result in a failed
re-IPL if no path is available.
Lastly, when changing the information in /sys/firmware/reipl/fcp/ fails
for whatever reason, a message with level alert is logged, as the
written information might be inconsistent and must be audited/corrected
manually by an operator.
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>
When the first test, whether the current event subject represents the
re-IPL target failed, we attempt a second test, using the recorded WWID
of a previously successful attempt.
The new helper `chreipl-fcp-mpath-is-ipl-vol` utilizes the information
previously stored in the ID-file (read under lock via `flock`).
The recorded WWID is compared with the one of the event subject; if it
matches we know that it addresses the same volume, and might be used as
alternative re-IPL target.
Additionally we also compare the current re-IPL triplet with the one
recorded in the ID-file. If it doesn't match anymore, we assume the
recorded WWID is stale - e.g., because the operator changed the re-IPL
target manually - and the previous check invalid.
If both the WWID match, and the re-IPL triplet is still the same as
previously recorded, the toolset may continue with the subject, and use
it as replacement for the current re-IPL target.
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>
When we have identified the current event subject to represent the
re-IPL target, we record its WWID for future identification in a
stateful ID-file (per default: /run/udev/chreiplzfcpmp-ipl-volume-id). In
addition to the WWID, we also record the current re-IPL triplet
(<Dev-Bus-ID>:<WWPN>:<LUN>), so that when that changes - e.g. due to an
operator manually changing the re-IPL target -, we know that the
recorded WWID is stale.
This record may be used in cases when the current re-IPL target is
completely gone from the system, so we can't used it as comparison
object for when events arrive for paths that go to the same volume, but
don't have the same I_T_L nexus. They however have the same WWID. We
may use these (new) paths as replacement for the one that is completely
gone.
The new helper `chreipl-fcp-mpath-record-volume-identifier` uses the
kernel scsi-device attribute `wwid` as source for the WWID (verbatim).
As with reading the re-IPL firmware information, when writing to the
ID-file, a lock is taken via `flock`, to prevent overlapping
writes/reads to the file.
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>
Now that we know that the system uses s390x IPL and the current re-IPL
target is from FCP, whenever we get a udev event that indicates a path
state changed, we have to figure out whether it affects the path that is
currently set as re-IPL target, or goes to the same volume (so we might
use it as alternative re-IPL path).
Add a new helper `chreipl-fcp-mpath-is-ipl-tgt` for this task.
Based on the information provided in
/sys/firmware/reipl/fcp/{device,wwpn,lun} it figures out whether the
current event subject has the same triplet <Dev-Bus-ID>:<WWPN>:<LUN> (in
T10 SCSI: I_T_L nexus), or whether one of its parts (in case of
dm-multipath) has.
If true, we know for sure, that we deal with an event affecting the
current re-IPL setting, and continue.
When accessing the re-IPL firmware information a lock is taken via the
`flock` utility (from util-linux). This is done so concurrent changes
from the toolset, that are added in a later commit, don't result in
inconsistent reads.
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>
Add second filter stage to the udev rules: only continue with the
toolset, if the system uses s390x IPL and if the current re-IPL target
is from FCP.
For the test, whether the next re-IPL target is planned to be done from
FCP, a helper `chreipl-fcp-mpath-is-reipl-zfcp` is added, and the
information in /sys/firmware/reipl/reipl_type is used.
If either one or both of the tests are not true, the udev rules will
exit.
For debugging, the toolset can be built with the Make variable `D` set
to 1 (e.g.: make D=1; make install D=1). This causes the toolset to
write shell traces of the helper to $(DEBUGOUTDIR) (per default:
/run/udev); otherwise no output is generated. `dbginfo.sh` will be
changed to collect this data automatically.
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>
