On Mon, Sep 11, 2023 at 06:38:40PM +0200, mwilck@xxxxxxxx wrote:
> From: Martin Wilck <mwilck@xxxxxxxx>
>
> Generate the man pages using the compile-time settings for paths
> to multipath.conf etc.
>
> Add a paragraph about the CONFIGDIR (/etc/multipath/conf.d)
> and the drop-in configuration files in the multipath.conf man page.
>
> Also, make sure all generated man pages and other files are correctly
> removed by "make clean".
>
> Signed-off-by: Martin Wilck <mwilck@xxxxxxxx>
Reviewed-by: Benjamin Marzinski <bmarzins@xxxxxxxxxx>
> ---
> .gitignore | 4 +++
> Makefile.inc | 3 +++
> mpathpersist/Makefile | 5 ++--
> .../{mpathpersist.8 => mpathpersist.8.in} | 2 +-
> multipath/Makefile | 13 +++++----
> multipath/{multipath.8 => multipath.8.in} | 10 +++----
> .../{multipath.conf.5 => multipath.conf.5.in} | 27 ++++++++++++-------
> multipathd/Makefile | 9 ++++---
> multipathd/{multipathd.8 => multipathd.8.in} | 8 +++---
> 9 files changed, 49 insertions(+), 32 deletions(-)
> rename mpathpersist/{mpathpersist.8 => mpathpersist.8.in} (99%)
> rename multipath/{multipath.8 => multipath.8.in} (97%)
> rename multipath/{multipath.conf.5 => multipath.conf.5.in} (98%)
> rename multipathd/{multipathd.8 => multipathd.8.in} (97%)
>
> diff --git a/.gitignore b/.gitignore
> index 535353e..2986578 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -13,11 +13,15 @@ cscope.files
> cscope.out
> kpartx/kpartx
> multipath/multipath
> +multipath/multipath.8
> +multipath/multipath.conf.5
> multipath/multipath.rules
> multipath/tmpfiles.conf
> multipathd/multipathd
> +multipathd/multipathd.8
> multipathd/multipathc
> mpathpersist/mpathpersist
> +mpathpersist/mpathpersist.8
> abi.tar.gz
> abi
> abi-test
> diff --git a/Makefile.inc b/Makefile.inc
> index 96206b2..79e521e 100644
> --- a/Makefile.inc
> +++ b/Makefile.inc
> @@ -133,3 +133,6 @@ NV_VERSION_SCRIPT = $(DEVLIB:%.so=%-nv.version)
> @grep -P '^[ \t]+[a-zA-Z_][a-zA-Z0-9_]*;' $< >>$@
> @printf 'local:\n\t*;\n};\n' >>$@
>
> +%: %.in
> + @echo creating $@
> + $(Q)sed 's:@CONFIGFILE@:'$(configfile)':g;s:@CONFIGDIR@:'$(configdir)':g;s:@STATE_DIR@:'$(statedir)':g;s:@RUNTIME_DIR@:'$(runtimedir)':g' $< >$@
> diff --git a/mpathpersist/Makefile b/mpathpersist/Makefile
> index f57c105..f374946 100644
> --- a/mpathpersist/Makefile
> +++ b/mpathpersist/Makefile
> @@ -8,10 +8,11 @@ LIBDEPS += -L$(mpathpersistdir) -lmpathpersist -L$(multipathdir) -lmultipath \
> -L$(mpathutildir) -lmpathutil -L$(mpathcmddir) -lmpathcmd -lpthread -ldevmapper -ludev
>
> EXEC = mpathpersist
> +MANPAGES := mpathpersist.8
>
> OBJS = main.o
>
> -all: $(EXEC)
> +all: $(EXEC) $(MANPAGES)
>
> $(EXEC): $(OBJS)
> $(Q)$(CC) $(OBJS) -o $(EXEC) $(LDFLAGS) $(CFLAGS) $(LIBDEPS)
> @@ -23,7 +24,7 @@ install:
> $(Q)$(INSTALL_PROGRAM) -m 644 $(EXEC).8 $(DESTDIR)$(mandir)/man8
>
> clean: dep_clean
> - $(Q)$(RM) core *.o $(EXEC)
> + $(Q)$(RM) core *.o $(EXEC) $(MANPAGES)
>
> include $(wildcard $(OBJS:.o=.d))
>
> diff --git a/mpathpersist/mpathpersist.8 b/mpathpersist/mpathpersist.8.in
> similarity index 99%
> rename from mpathpersist/mpathpersist.8
> rename to mpathpersist/mpathpersist.8.in
> index 8d26b37..fecef0d 100644
> --- a/mpathpersist/mpathpersist.8
> +++ b/mpathpersist/mpathpersist.8.in
> @@ -31,7 +31,7 @@ mpathpersist \- Manages SCSI persistent reservations on dm multipath devices.
> .
> This utility is used to manage SCSI persistent reservations on Device Mapper
> Multipath devices. To be able to use this functionality, the \fIreservation_key\fR
> -attribute must be defined in the \fI/etc/multipath.conf\fR file. Otherwise the
> +attribute must be defined in the \fI@CONFIGFILE@\fR file. Otherwise the
> \fBmultipathd\fR daemon will not check for persistent reservation for newly
> discovered paths or reinstated paths.
> .
> diff --git a/multipath/Makefile b/multipath/Makefile
> index 73db991..68cb5ce 100644
> --- a/multipath/Makefile
> +++ b/multipath/Makefile
> @@ -3,7 +3,9 @@
> #
> include ../Makefile.inc
>
> -EXEC := multipath
> +EXEC := multipath
> +MANPAGES := multipath.8 multipath.conf.5
> +GENERATED := $(MANPAGES) multipath.rules tmpfiles.conf
>
> CPPFLAGS += -I$(multipathdir) -I$(mpathutildir) -I$(mpathcmddir)
> CFLAGS += $(BIN_CFLAGS)
> @@ -13,7 +15,7 @@ LIBDEPS += -L$(multipathdir) -lmultipath -L$(mpathutildir) -lmpathutil \
>
> OBJS := main.o
>
> -all: $(EXEC) multipath.rules tmpfiles.conf
> +all: $(EXEC) $(GENERATED)
>
> $(EXEC): $(OBJS) $(multipathdir)/libmultipath.so $(mpathcmddir)/libmpathcmd.so
> @echo building $@ because of $?
> @@ -47,15 +49,12 @@ uninstall:
> $(Q)$(RM) $(DESTDIR)$(libudevdir)/rules.d/56-multipath.rules
> $(Q)$(RM) $(DESTDIR)$(mandir)/man8/$(EXEC).8
> $(Q)$(RM) $(DESTDIR)$(mandir)/man5/$(EXEC).conf.5
> + $(Q)$(RM) $(DESTDIR)$(tmpfilesdir)/multipath.conf
>
> clean: dep_clean
> - $(Q)$(RM) core *.o $(EXEC) multipath.rules tmpfiles.conf
> + $(Q)$(RM) core *.o $(EXEC) $(GENERATED)
>
> include $(wildcard $(OBJS:.o=.d))
>
> dep_clean:
> $(Q)$(RM) $(OBJS:.o=.d)
> -
> -%: %.in
> - @echo creating $@
> - $(Q)sed 's,@RUNTIME_DIR@,$(runtimedir),' $< >$@
> diff --git a/multipath/multipath.8 b/multipath/multipath.8.in
> similarity index 97%
> rename from multipath/multipath.8
> rename to multipath/multipath.8.in
> index 5fed6df..348eb22 100644
> --- a/multipath/multipath.8
> +++ b/multipath/multipath.8.in
> @@ -185,7 +185,7 @@ Display the currently used multipathd configuration.
> .B \-T
> Display the currently used multipathd configuration, limiting the output to
> those devices actually present in the system. This can be used a template for
> -creating \fImultipath.conf\fR.
> +creating \fI@CONFIGFILE@\fR.
> .
> .\" ----------------------------------------------------------------------------
> .SH OPTIONS
> @@ -233,11 +233,11 @@ option from \fBmultipath.conf(5)\fR.
> .B \-i
> Ignore WWIDs file when processing devices. If
> \fIfind_multipaths strict\fR or \fIfind_multipaths no\fR is set in
> -\fImultipath.conf\fR, multipath only considers devices that are
> +\fI@CONFIGFILE@\fR, multipath only considers devices that are
> listed in the WWIDs file. This option overrides that behavior. For other values
> of \fIfind_multipaths\fR, this option has no effect. See the description of
> \fIfind_multipaths\fR in
> -.BR multipath.conf (5).
> +.BR @CONFIGFILE@ (5).
> This option should only be used in rare circumstances.
> .
> .TP
> @@ -246,8 +246,8 @@ Treat the bindings file as read only.
> .
> .TP
> .BI \-b " file"
> -Set \fIuser_friendly_names\fR bindings file location. The default is
> -\fI/etc/multipath/bindings\fR.
> +(\fBdeprecated, do not use\fR) Set \fIuser_friendly_names\fR bindings file location. The default is
> +\fI@STATE_DIR@/bindings\fR.
> .
> .TP
> .B \-q
> diff --git a/multipath/multipath.conf.5 b/multipath/multipath.conf.5.in
> similarity index 98%
> rename from multipath/multipath.conf.5
> rename to multipath/multipath.conf.5.in
> index 93af17d..20df223 100644
> --- a/multipath/multipath.conf.5
> +++ b/multipath/multipath.conf.5.in
> @@ -13,14 +13,14 @@
> .SH NAME
> .\" ----------------------------------------------------------------------------
> .
> -multipath.conf \- multipath daemon configuration file.
> +@CONFIGFILE@, @CONFIGDIR@/*.conf \- multipath daemon configuration file.
> .
> .
> .\" ----------------------------------------------------------------------------
> .SH DESCRIPTION
> .\" ----------------------------------------------------------------------------
> .
> -.B "/etc/multipath.conf"
> +.B "@CONFIGFILE@"
> is the configuration file for the multipath daemon. It is used to
> overwrite the built-in configuration table of \fBmultipathd\fP.
> Any line whose first non-white-space character is a '#' is considered
> @@ -29,6 +29,15 @@ a comment line. Empty lines are ignored.
> Currently used multipathd configuration can be displayed with the \fBmultipath -t\fR
> or \fBmultipathd show config\fR command.
> .
> +.PP
> +Additional configuration can be made in drop-in files under
> +.B @CONFIGDIR@.
> +Files ending in \fI.conf\fR in this directory are read
> +in alphabetical order, after reading \fI@CONFIGFILE@\fR.
> +They use the same syntax as \fI@CONFIGFILE@\fR itself,
> +and support all sections and keywords. If a keyword occurs in the same section
> +in multiple files, the last occurence will take precedence over all others.
> +.
> .
> .\" ----------------------------------------------------------------------------
> .SH SYNTAX
> @@ -85,7 +94,7 @@ not mandatory.
> .
> .LP
> .B Note on regular expressions:
> -The \fImultipath.conf\fR syntax allows many attribute values to be specified as POSIX
> +The \fI@CONFIGFILE@\fR syntax allows many attribute values to be specified as POSIX
> Extended Regular Expressions (see \fBregex\fR(7)). These regular expressions
> are \fBcase sensitive\fR and \fBnot anchored\fR, thus the expression "bar" matches "barbie",
> "rhabarber", and "wunderbar", but not "Barbie". To avoid unwanted substring
> @@ -711,7 +720,7 @@ The default is: \fBno\fR
> .B user_friendly_names
> If set to
> .I yes
> -, using the bindings file \fI/etc/multipath/bindings\fR to assign a persistent
> +, using the bindings file \fI@STATE_DIR@/bindings\fR to assign a persistent
> and unique alias to the multipath, in the form of mpath<n>. If set to
> .I no
> use the WWID as the alias. In either case this be will
> @@ -790,7 +799,7 @@ The full pathname of the binding file to be used when the user_friendly_names
> option is set.
> .RS
> .TP
> -The default is: \fB/etc/multipath/bindings\fR
> +The default is: \fB@STATE_DIR@/bindings\fR
> .RE
> .
> .
> @@ -801,7 +810,7 @@ The full pathname of the WWIDs file, which is used by multipath to keep track
> of the WWIDs for LUNs it has created multipath devices on in the past.
> .RS
> .TP
> -The default is: \fB/etc/multipath/wwids\fR
> +The default is: \fB@STATE_DIR@/wwids\fR
> .RE
> .
> .
> @@ -813,7 +822,7 @@ track of the persistent reservation key used for a specific WWID, when
> \fIreservation_key\fR is set to \fBfile\fR.
> .RS
> .TP
> -The default is: \fB/etc/multipath/prkeys\fR
> +The default is: \fB@STATE_DIR@/prkeys\fR
> .RE
> .
> .
> @@ -872,7 +881,7 @@ The default is: \fBno\fR
> .I yes
> and the SCSI layer has already attached a hardware_handler to the device,
> multipath will not force the device to use the hardware_handler specified by
> -multipath.conf. If the SCSI layer has not attached a hardware handler,
> +@CONFIGFILE@. If the SCSI layer has not attached a hardware handler,
> multipath will continue to use its configured hardware handler.
> .RS
> .PP
> @@ -1559,7 +1568,7 @@ given device, the attributes of all matching entries are applied to it.
> If an attribute is specified in several matching device subsections,
> later entries take precedence. Thus, entries in files under \fIconfig_dir\fR (in
> reverse alphabetical order) have the highest precedence, followed by entries
> -in \fImultipath.conf\fR; the built-in hardware table has the lowest
> +in \fI@CONFIGFILE@\fR; the built-in hardware table has the lowest
> precedence. Inside a configuration file, later entries have higher precedence
> than earlier ones.
> .LP
> diff --git a/multipathd/Makefile b/multipathd/Makefile
> index 0d0146c..cdba3db 100644
> --- a/multipathd/Makefile
> +++ b/multipathd/Makefile
> @@ -1,7 +1,8 @@
> include ../Makefile.inc
>
> -EXEC := multipathd
> -CLI := multipathc
> +EXEC := multipathd
> +CLI := multipathc
> +MANPAGES := multipathd.8
>
> CPPFLAGS += -I$(multipathdir) -I$(mpathutildir) -I$(mpathpersistdir) -I$(mpathcmddir) -I$(thirdpartydir) \
> $(shell $(PKG_CONFIG) --modversion liburcu 2>/dev/null | \
> @@ -42,7 +43,7 @@ ifeq ($(FPIN_SUPPORT),1)
> OBJS += fpin_handlers.o
> endif
>
> -all : $(EXEC) $(CLI)
> +all : $(EXEC) $(CLI) $(MANPAGES)
>
> $(EXEC): $(OBJS) $(multipathdir)/libmultipath.so $(mpathcmddir)/libmpathcmd.so
> @echo building $@ because of $?
> @@ -79,7 +80,7 @@ uninstall:
> $(Q)$(RM) $(DESTDIR)$(unitdir)/$(EXEC).socket
>
> clean: dep_clean
> - $(Q)$(RM) core *.o $(EXEC) $(CLI)
> + $(Q)$(RM) core *.o $(EXEC) $(CLI) $(MANPAGES)
>
> include $(wildcard $(OBJS:.o=.d) $(CLI_OBJS:.o=.d))
>
> diff --git a/multipathd/multipathd.8 b/multipathd/multipathd.8.in
> similarity index 97%
> rename from multipathd/multipathd.8
> rename to multipathd/multipathd.8.in
> index cc72b77..e98c27f 100644
> --- a/multipathd/multipathd.8
> +++ b/multipathd/multipathd.8.in
> @@ -155,7 +155,7 @@ Show the format wildcards used in interactive commands taking $format.
> .TP
> .B list|show config
> Show the currently used configuration, derived from default values and values
> -specified within the configuration file \fI/etc/multipath.conf\fR.
> +specified within the configuration file \fI@CONFIGFILE@\fR.
> .
> .TP
> .B list|show config local
> @@ -165,7 +165,7 @@ the devices section to those devices that are actually present in the system.
> .TP
> .B list|show blacklist
> Show the currently used blacklist rules, derived from default values and values
> -specified within the configuration file \fI/etc/multipath.conf\fR.
> +specified within the configuration file \fI@CONFIGFILE@\fR.
> .
> .TP
> .B list|show devices
> @@ -290,13 +290,13 @@ Get the current persistent reservation key associated with $map.
> .B map|multipath $map setprkey key $key
> Set the persistent reservation key associated with $map to $key in the
> \fIprkeys_file\fR. This key will only be used by multipathd if
> -\fIreservation_key\fR is set to \fBfile\fR in \fI/etc/multipath.conf\fR.
> +\fIreservation_key\fR is set to \fBfile\fR in \fI@CONFIGFILE@\fR.
> .
> .TP
> .B map|multipath $map unsetprkey
> Remove the persistent reservation key associated with $map from the
> \fIprkeys_file\fR. This will only unset the key used by multipathd if
> -\fIreservation_key\fR is set to \fBfile\fR in \fI/etc/multipath.conf\fR.
> +\fIreservation_key\fR is set to \fBfile\fR in \fI@CONFIGFILE@\fR.
> .
> .TP
> .B path $path setmarginal
> --
> 2.42.0
--
dm-devel mailing list
dm-devel@xxxxxxxxxx
https://listman.redhat.com/mailman/listinfo/dm-devel
