[PATCH v2 0/4] Manual improvements

[PATCH v2 0/4] Manual improvements

[Lukasz Florczak]

Changes in v2:
- Remove periods in commit messages
- Split commits for better clarity

Lukasz Florczak (4):
  mdadm: Respect config file location in man
  mdadm: Update ReadMe
  mdadm: Update config man regarding default files and multi-keyword
    behavior
  mdadm: Update config manual

 .gitignore                      |  1 +
 Makefile                        |  7 ++-
 ReadMe.c                        | 11 +++--
 mdadm.8.in                      | 34 ++++++-------
 mdadm.conf.5 => mdadm.conf.5.in | 84 ++++++++++++++++++++++++++++++---
 5 files changed, 104 insertions(+), 33 deletions(-)
 rename mdadm.conf.5 => mdadm.conf.5.in (90%)

-- 
2.27.0

[PATCH 1/4] mdadm: Respect config file location in man

[Lukasz Florczak]

Default config file location could differ depending on OS (e.g. Debian family).
This patch takes default config file into consideration when creating mdadm.man
file as well as mdadm.conf.man.

Rename mdadm.conf.5 to mdadm.conf.5.in. Now mdadm.conf.5 is generated automatically.

Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>
---
 .gitignore                      |  1 +
 Makefile                        |  7 ++++++-
 mdadm.8.in                      | 16 ++++++++--------
 mdadm.conf.5 => mdadm.conf.5.in |  2 +-
 4 files changed, 16 insertions(+), 10 deletions(-)
 rename mdadm.conf.5 => mdadm.conf.5.in (99%)

diff --git a/.gitignore b/.gitignore
index 217fe76d..8d791c6f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,7 @@
 /*-stamp
 /mdadm
 /mdadm.8
+/mdadm.conf.5
 /mdadm.udeb
 /mdassemble
 /mdmon
diff --git a/Makefile b/Makefile
index 2a51d813..bf126033 100644
--- a/Makefile
+++ b/Makefile
@@ -227,7 +227,12 @@ raid6check : raid6check.o mdadm.h $(CHECK_OBJS)
 
 mdadm.8 : mdadm.8.in
 	sed -e 's/{DEFAULT_METADATA}/$(DEFAULT_METADATA)/g' \
-	-e 's,{MAP_PATH},$(MAP_PATH),g'  mdadm.8.in > mdadm.8
+	-e 's,{MAP_PATH},$(MAP_PATH),g' -e 's,{CONFFILE},$(CONFFILE),g' \
+	-e 's,{CONFFILE2},$(CONFFILE2),g'  mdadm.8.in > mdadm.8
+
+mdadm.conf.5 : mdadm.conf.5.in
+	sed -e 's,{CONFFILE},$(CONFFILE),g' \
+	-e 's,{CONFFILE2},$(CONFFILE2),g'  mdadm.conf.5.in > mdadm.conf.5
 
 mdadm.man : mdadm.8
 	man -l mdadm.8 > mdadm.man
diff --git a/mdadm.8.in b/mdadm.8.in
index be902dba..d41b3ca7 100644
--- a/mdadm.8.in
+++ b/mdadm.8.in
@@ -267,13 +267,13 @@ the exact meaning of this option in different contexts.
 .TP
 .BR \-c ", " \-\-config=
 Specify the config file or directory.  Default is to use
-.B /etc/mdadm.conf
+.B {CONFFILE}
 and
-.BR /etc/mdadm.conf.d ,
+.BR {CONFFILE}.d ,
 or if those are missing then
-.B /etc/mdadm/mdadm.conf
+.B {CONFFILE2}
 and
-.BR /etc/mdadm/mdadm.conf.d .
+.BR {CONFFILE2}.d .
 If the config file given is
 .B "partitions"
 then nothing will be read, but
@@ -2009,9 +2009,9 @@ The config file is only used if explicitly named with
 or requested with (a possibly implicit)
 .BR \-\-scan .
 In the later case,
-.B /etc/mdadm.conf
+.B {CONFFILE}
 or
-.B /etc/mdadm/mdadm.conf
+.B {CONFFILE2}
 is used.
 
 If
@@ -3339,7 +3339,7 @@ uses this to find arrays when
 is given in Misc mode, and to monitor array reconstruction
 on Monitor mode.
 
-.SS /etc/mdadm.conf
+.SS {CONFFILE} (or {CONFFILE2})
 
 The config file lists which devices may be scanned to see if
 they contain MD super block, and gives identifying information
@@ -3347,7 +3347,7 @@ they contain MD super block, and gives identifying information
 .BR mdadm.conf (5)
 for more details.
 
-.SS /etc/mdadm.conf.d
+.SS {CONFFILE}.d (or {CONFFILE2}.d)
 
 A directory containing configuration files which are read in lexical
 order.
diff --git a/mdadm.conf.5 b/mdadm.conf.5.in
similarity index 99%
rename from mdadm.conf.5
rename to mdadm.conf.5.in
index 74a21c5f..83edd008 100644
--- a/mdadm.conf.5
+++ b/mdadm.conf.5.in
@@ -8,7 +8,7 @@
 .SH NAME
 mdadm.conf \- configuration for management of Software RAID with mdadm
 .SH SYNOPSIS
-/etc/mdadm.conf
+{CONFFILE}
 .SH DESCRIPTION
 .PP
 .I mdadm
-- 
2.27.0

Re: [PATCH 1/4] mdadm: Respect config file location in man

[Coly Li]

On 3/18/22 4:26 PM, Lukasz Florczak wrote:
> Default config file location could differ depending on OS (e.g. Debian family).
> This patch takes default config file into consideration when creating mdadm.man
> file as well as mdadm.conf.man.
>
> Rename mdadm.conf.5 to mdadm.conf.5.in. Now mdadm.conf.5 is generated automatically.
>
> Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>


I test and verify the change under openSUSE.


Acked-by: Coly Li <colyli@suse.de>


Thanks.


Coly Li


> ---
>   .gitignore                      |  1 +
>   Makefile                        |  7 ++++++-
>   mdadm.8.in                      | 16 ++++++++--------
>   mdadm.conf.5 => mdadm.conf.5.in |  2 +-
>   4 files changed, 16 insertions(+), 10 deletions(-)
>   rename mdadm.conf.5 => mdadm.conf.5.in (99%)
>
> diff --git a/.gitignore b/.gitignore
> index 217fe76d..8d791c6f 100644
> --- a/.gitignore
> +++ b/.gitignore
> @@ -3,6 +3,7 @@
>   /*-stamp
>   /mdadm
>   /mdadm.8
> +/mdadm.conf.5
>   /mdadm.udeb
>   /mdassemble
>   /mdmon
> diff --git a/Makefile b/Makefile
> index 2a51d813..bf126033 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -227,7 +227,12 @@ raid6check : raid6check.o mdadm.h $(CHECK_OBJS)
>   
>   mdadm.8 : mdadm.8.in
>   	sed -e 's/{DEFAULT_METADATA}/$(DEFAULT_METADATA)/g' \
> -	-e 's,{MAP_PATH},$(MAP_PATH),g'  mdadm.8.in > mdadm.8
> +	-e 's,{MAP_PATH},$(MAP_PATH),g' -e 's,{CONFFILE},$(CONFFILE),g' \
> +	-e 's,{CONFFILE2},$(CONFFILE2),g'  mdadm.8.in > mdadm.8
> +
> +mdadm.conf.5 : mdadm.conf.5.in
> +	sed -e 's,{CONFFILE},$(CONFFILE),g' \
> +	-e 's,{CONFFILE2},$(CONFFILE2),g'  mdadm.conf.5.in > mdadm.conf.5
>   
>   mdadm.man : mdadm.8
>   	man -l mdadm.8 > mdadm.man
> diff --git a/mdadm.8.in b/mdadm.8.in
> index be902dba..d41b3ca7 100644
> --- a/mdadm.8.in
> +++ b/mdadm.8.in
> @@ -267,13 +267,13 @@ the exact meaning of this option in different contexts.
>   .TP
>   .BR \-c ", " \-\-config=
>   Specify the config file or directory.  Default is to use
> -.B /etc/mdadm.conf
> +.B {CONFFILE}
>   and
> -.BR /etc/mdadm.conf.d ,
> +.BR {CONFFILE}.d ,
>   or if those are missing then
> -.B /etc/mdadm/mdadm.conf
> +.B {CONFFILE2}
>   and
> -.BR /etc/mdadm/mdadm.conf.d .
> +.BR {CONFFILE2}.d .
>   If the config file given is
>   .B "partitions"
>   then nothing will be read, but
> @@ -2009,9 +2009,9 @@ The config file is only used if explicitly named with
>   or requested with (a possibly implicit)
>   .BR \-\-scan .
>   In the later case,
> -.B /etc/mdadm.conf
> +.B {CONFFILE}
>   or
> -.B /etc/mdadm/mdadm.conf
> +.B {CONFFILE2}
>   is used.
>   
>   If
> @@ -3339,7 +3339,7 @@ uses this to find arrays when
>   is given in Misc mode, and to monitor array reconstruction
>   on Monitor mode.
>   
> -.SS /etc/mdadm.conf
> +.SS {CONFFILE} (or {CONFFILE2})
>   
>   The config file lists which devices may be scanned to see if
>   they contain MD super block, and gives identifying information
> @@ -3347,7 +3347,7 @@ they contain MD super block, and gives identifying information
>   .BR mdadm.conf (5)
>   for more details.
>   
> -.SS /etc/mdadm.conf.d
> +.SS {CONFFILE}.d (or {CONFFILE2}.d)
>   
>   A directory containing configuration files which are read in lexical
>   order.
> diff --git a/mdadm.conf.5 b/mdadm.conf.5.in
> similarity index 99%
> rename from mdadm.conf.5
> rename to mdadm.conf.5.in
> index 74a21c5f..83edd008 100644
> --- a/mdadm.conf.5
> +++ b/mdadm.conf.5.in
> @@ -8,7 +8,7 @@
>   .SH NAME
>   mdadm.conf \- configuration for management of Software RAID with mdadm
>   .SH SYNOPSIS
> -/etc/mdadm.conf
> +{CONFFILE}
>   .SH DESCRIPTION
>   .PP
>   .I mdadm

Re: [PATCH 1/4] mdadm: Respect config file location in man

[Mariusz Tkaczyk]

On Sun, 20 Mar 2022 17:54:56 +0800
Coly Li <colyli@suse.de> wrote:

> On 3/18/22 4:26 PM, Lukasz Florczak wrote:
> > Default config file location could differ depending on OS (e.g.
> > Debian family). This patch takes default config file into
> > consideration when creating mdadm.man file as well as
> > mdadm.conf.man.
> >
> > Rename mdadm.conf.5 to mdadm.conf.5.in. Now mdadm.conf.5 is
> > generated automatically.
> >
> > Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>  
> 
> 
> I test and verify the change under openSUSE.
> 
> 
> Acked-by: Coly Li <colyli@suse.de>
> 
> 
Hi Coly,
Could you please merge it to your master/for-jes branch then?
We have additional CI at Intel, based on our internal IMSM scope.
I would like to switch it to your master/for-jes branch. Also I want to
base future development on your tree.

Could you also elaborate more, what kind of testing are you doing?
I think that is a good moment to give new life to mdadm test suite, if
you are using it.

Thanks,
Mariusz

Re: [PATCH 1/4] mdadm: Respect config file location in man

[Coly Li]

On 3/21/22 4:14 PM, Mariusz Tkaczyk wrote:
> On Sun, 20 Mar 2022 17:54:56 +0800
> Coly Li <colyli@suse.de> wrote:
>
>> On 3/18/22 4:26 PM, Lukasz Florczak wrote:
>>> Default config file location could differ depending on OS (e.g.
>>> Debian family). This patch takes default config file into
>>> consideration when creating mdadm.man file as well as
>>> mdadm.conf.man.
>>>
>>> Rename mdadm.conf.5 to mdadm.conf.5.in. Now mdadm.conf.5 is
>>> generated automatically.
>>>
>>> Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>
>>
>> I test and verify the change under openSUSE.
>>
>>
>> Acked-by: Coly Li <colyli@suse.de>
>>
>>
> Hi Coly,
> Could you please merge it to your master/for-jes branch then?

Sure, I will do it.

Just to confirm, for this situation, do you want me to add the patch 
directly to for-jes branch with my Acked-by: tag, or you will post 
another version with the Acked-by: tag?


> We have additional CI at Intel, based on our internal IMSM scope.
> I would like to switch it to your master/for-jes branch. Also I want to
> base future development on your tree.


Copied.


> Could you also elaborate more, what kind of testing are you doing?


Currently I only compile the patches, and create simple md raid1 
with/without container, and show them with mdadm -D and -E.

For the manual modification, it is checked by myself. I compile the man 
page, and check the CONFFILE and CONFFILE2 replacement in man page is 
correct on openSUSE. Then I run checkpatch.pl from Linux kernel with 
--codespell to check the patch style and basic spelling. And finally 
read the changed content of the man page.


> I think that is a good moment to give new life to mdadm test suite, if
> you are using it.


I am thinking of create another separate git repo, to store all the 
testing scripts, and run them on the mdadm-CI tree.

Thanks.


Coly Li

Re: [PATCH 1/4] mdadm: Respect config file location in man

[Coly Li]

On 3/21/22 10:54 PM, Coly Li wrote:
> On 3/21/22 4:14 PM, Mariusz Tkaczyk wrote:
>>
>>>
>> Hi Coly,
>> Could you please merge it to your master/for-jes branch then?
>
> Sure, I will do it.
>
> Just to confirm, for this situation, do you want me to add the patch 
> directly to for-jes branch with my Acked-by: tag, or you will post 
> another version with the Acked-by: tag?


BTW, just for your information, the patches acked by me are pushed to 
for-jes/20220321 branch of the mdadm-CI tree.


Thanks.


Coly Li

Re: [PATCH 1/4] mdadm: Respect config file location in man

[Mariusz Tkaczyk]

On Mon, 21 Mar 2022 22:54:41 +0800
Coly Li <colyli@suse.de> wrote:

> On 3/21/22 4:14 PM, Mariusz Tkaczyk wrote:
> > On Sun, 20 Mar 2022 17:54:56 +0800
> > Coly Li <colyli@suse.de> wrote:
> >  
> >> On 3/18/22 4:26 PM, Lukasz Florczak wrote:  
> >>> Default config file location could differ depending on OS (e.g.
> >>> Debian family). This patch takes default config file into
> >>> consideration when creating mdadm.man file as well as
> >>> mdadm.conf.man.
> >>>
> >>> Rename mdadm.conf.5 to mdadm.conf.5.in. Now mdadm.conf.5 is
> >>> generated automatically.
> >>>
> >>> Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>  
> >>
> >> I test and verify the change under openSUSE.
> >>
> >>
> >> Acked-by: Coly Li <colyli@suse.de>
> >>
> >>  
> > Hi Coly,
> > Could you please merge it to your master/for-jes branch then?  
> 
> Sure, I will do it.
> 
> Just to confirm, for this situation, do you want me to add the patch 
> directly to for-jes branch with my Acked-by: tag, or you will post 
> another version with the Acked-by: tag?
> 
Please do. Asking author to post another version will bring unnecessary
harm. Just take it and add your tag.

> 
> > We have additional CI at Intel, based on our internal IMSM scope.
> > I would like to switch it to your master/for-jes branch. Also I
> > want to base future development on your tree.  
> 
> 
> Copied.

I can see that you named the branch with the date. Do you plan to
create more for-jes branches?
https://git.kernel.org/pub/scm/linux/kernel/git/colyli/mdadm.git/log/?h=for-jes/20220321

> 
> 
> > Could you also elaborate more, what kind of testing are you doing?  
> 
> 
> Currently I only compile the patches, and create simple md raid1 
> with/without container, and show them with mdadm -D and -E.
> 
> For the manual modification, it is checked by myself. I compile the
> man page, and check the CONFFILE and CONFFILE2 replacement in man
> page is correct on openSUSE. Then I run checkpatch.pl from Linux
> kernel with --codespell to check the patch style and basic spelling.
> And finally read the changed content of the man page.
> 
> 
> > I think that is a good moment to give new life to mdadm test suite,
> > if you are using it.  
> 
> 
> I am thinking of create another separate git repo, to store all the 
> testing scripts, and run them on the mdadm-CI tree.

Make sense.

Thanks,
Mariusz

Re: [PATCH 1/4] mdadm: Respect config file location in man

[Jes Sorensen]

On 3/18/22 04:26, Lukasz Florczak wrote:
> Default config file location could differ depending on OS (e.g. Debian family).
> This patch takes default config file into consideration when creating mdadm.man
> file as well as mdadm.conf.man.
> 
> Rename mdadm.conf.5 to mdadm.conf.5.in. Now mdadm.conf.5 is generated automatically.
> 
> Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>
> ---


Applied!

Thanks,
Jes

[PATCH 2/4] mdadm: Update ReadMe

[Lukasz Florczak]

Instead of hardcoded config file path give reference to config manual.

Add missing monitordelay and homecluster parameters.

Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>
---
 ReadMe.c | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/ReadMe.c b/ReadMe.c
index 81399765..8f873c48 100644
--- a/ReadMe.c
+++ b/ReadMe.c
@@ -613,7 +613,6 @@ char Help_incr[] =
 ;
 
 char Help_config[] =
-"The /etc/mdadm.conf config file:\n\n"
 " The config file contains, apart from blank lines and comment lines that\n"
 " start with a hash(#), array lines, device lines, and various\n"
 " configuration lines.\n"
@@ -636,10 +635,12 @@ char Help_config[] =
 " than a device must match all of them to be considered.\n"
 "\n"
 " Other configuration lines include:\n"
-"  mailaddr, mailfrom, program     used for --monitor mode\n"
-"  create, auto                    used when creating device names in /dev\n"
-"  homehost, policy, part-policy   used to guide policy in various\n"
-"                                  situations\n"
+"  mailaddr, mailfrom, program, monitordelay    used for --monitor mode\n"
+"  create, auto                                 used when creating device names in /dev\n"
+"  homehost, homecluster, policy, part-policy   used to guide policy in various\n"
+"                                               situations\n"
+"\n"
+"For more details see mdadm.conf(5).\n"
 "\n"
 ;
 
-- 
2.27.0

Re: [PATCH 2/4] mdadm: Update ReadMe

[Coly Li]

On 3/18/22 4:26 PM, Lukasz Florczak wrote:
> Instead of hardcoded config file path give reference to config manual.
>
> Add missing monitordelay and homecluster parameters.
>
> Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>


Tested and verified on openSUSE,

Acked-by: Coly Li <colyli@suse.de>


Thanks.


Coly Li


> ---
>   ReadMe.c | 11 ++++++-----
>   1 file changed, 6 insertions(+), 5 deletions(-)
>
> diff --git a/ReadMe.c b/ReadMe.c
> index 81399765..8f873c48 100644
> --- a/ReadMe.c
> +++ b/ReadMe.c
> @@ -613,7 +613,6 @@ char Help_incr[] =
>   ;
>   
>   char Help_config[] =
> -"The /etc/mdadm.conf config file:\n\n"
>   " The config file contains, apart from blank lines and comment lines that\n"
>   " start with a hash(#), array lines, device lines, and various\n"
>   " configuration lines.\n"
> @@ -636,10 +635,12 @@ char Help_config[] =
>   " than a device must match all of them to be considered.\n"
>   "\n"
>   " Other configuration lines include:\n"
> -"  mailaddr, mailfrom, program     used for --monitor mode\n"
> -"  create, auto                    used when creating device names in /dev\n"
> -"  homehost, policy, part-policy   used to guide policy in various\n"
> -"                                  situations\n"
> +"  mailaddr, mailfrom, program, monitordelay    used for --monitor mode\n"
> +"  create, auto                                 used when creating device names in /dev\n"
> +"  homehost, homecluster, policy, part-policy   used to guide policy in various\n"
> +"                                               situations\n"
> +"\n"
> +"For more details see mdadm.conf(5).\n"
>   "\n"
>   ;
>   

Re: [PATCH 2/4] mdadm: Update ReadMe

[Jes Sorensen]

On 3/18/22 04:26, Lukasz Florczak wrote:
> Instead of hardcoded config file path give reference to config manual.
> 
> Add missing monitordelay and homecluster parameters.
> 
> Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>
> ---

Applied!

Thanks,
Jes

[PATCH 3/4] mdadm: Update config man regarding default files and multi-keyword behavior

[Lukasz Florczak]

Simplify default and alternative config file and directory location references
from mdadm(8) as references to mdadm.conf(5). Add FILE section in config man
and explain order and conditions in which default and alternative config files
and directories are used.

Update config man behavior regarding parsing order when multiple keywords/config
files are involved.

Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>
---
 mdadm.8.in      | 30 +++++++++--------------
 mdadm.conf.5.in | 65 ++++++++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 71 insertions(+), 24 deletions(-)

diff --git a/mdadm.8.in b/mdadm.8.in
index d41b3ca7..d6af73b7 100644
--- a/mdadm.8.in
+++ b/mdadm.8.in
@@ -266,14 +266,11 @@ the exact meaning of this option in different contexts.
 
 .TP
 .BR \-c ", " \-\-config=
-Specify the config file or directory.  Default is to use
-.B {CONFFILE}
-and
-.BR {CONFFILE}.d ,
-or if those are missing then
-.B {CONFFILE2}
-and
-.BR {CONFFILE2}.d .
+Specify the config file or directory.  If not specified, default config file
+and default conf.d directory will be used.  See
+.BR mdadm.conf (5)
+for more details.
+
 If the config file given is
 .B "partitions"
 then nothing will be read, but
@@ -2008,11 +2005,9 @@ The config file is only used if explicitly named with
 .B \-\-config
 or requested with (a possibly implicit)
 .BR \-\-scan .
-In the later case,
-.B {CONFFILE}
-or
-.B {CONFFILE2}
-is used.
+In the later case, default config file is used.  See
+.BR mdadm.conf (5)
+for more details.
 
 If
 .B \-\-scan
@@ -3341,16 +3336,15 @@ on Monitor mode.
 
 .SS {CONFFILE} (or {CONFFILE2})
 
-The config file lists which devices may be scanned to see if
-they contain MD super block, and gives identifying information
-(e.g. UUID) about known MD arrays.  See
+Default config file.  See
 .BR mdadm.conf (5)
 for more details.
 
 .SS {CONFFILE}.d (or {CONFFILE2}.d)
 
-A directory containing configuration files which are read in lexical
-order.
+Default directory containing configuration files.  See
+.BR mdadm.conf (5)
+for more details.
 
 .SS {MAP_PATH}
 When
diff --git a/mdadm.conf.5.in b/mdadm.conf.5.in
index 83edd008..dd331a6a 100644
--- a/mdadm.conf.5.in
+++ b/mdadm.conf.5.in
@@ -88,7 +88,8 @@ but only the major and minor device numbers.  It scans
 .I /dev
 to find the name that matches the numbers.
 
-If no DEVICE line is present, then "DEVICE partitions containers" is assumed.
+If no DEVICE line is present in any config file,
+then "DEVICE partitions containers" is assumed.
 
 For example:
 .IP
@@ -272,6 +273,10 @@ catenated with spaces to form the address.
 Note that this value cannot be set via the
 .I mdadm
 commandline.  It is only settable via the config file.
+There should only be one
+.B MAILADDR
+line and it should have only one address.  Any subsequent addresses
+are silently ignored.
 
 .TP
 .B PROGRAM
@@ -286,7 +291,8 @@ device.
 
 There should only be one
 .B program
-line and it should be give only one program.
+line and it should be given only one program.  Any subsequent programs
+are silently ignored.
 
 
 .TP
@@ -295,7 +301,14 @@ The
 .B create
 line gives default values to be used when creating arrays, new members
 of arrays, and device entries for arrays.
-These include:
+
+There should only be one
+.B create
+line.  Any subsequent lines will override the previous settings.
+
+Keywords used in the
+.I CREATE
+line and supported values are:
 
 .RS 4
 .TP
@@ -475,8 +488,8 @@ The known metadata types are
 
 .B AUTO
 should be given at most once.  Subsequent lines are silently ignored.
-Thus an earlier config file in a config directory will over-ride
-the setting in a later config file.
+Thus a later config file in a config directory will not overwrite
+the setting in an earlier config file.
 
 .TP
 .B POLICY
@@ -594,6 +607,7 @@ The
 line lists custom values of MD device's sysfs attributes which will be
 stored in sysfs after the array is assembled. Multiple lines are allowed and each
 line has to contain the uuid or the name of the device to which it relates.
+Lines are applied in reverse order.
 .RS 4
 .TP
 .B uuid=
@@ -621,7 +635,46 @@ is running in
 .B \-\-monitor
 mode.
 .B \-d/\-\-delay
-command line argument takes precedence over the config file
+command line argument takes precedence over the config file.
+
+If multiple
+.B MINITORDELAY
+lines are provided, only first non-zero value is considered.
+
+.SH FILES
+
+.SS {CONFFILE}
+
+The default config file location, used when
+.I mdadm
+is running without --config option.
+
+.SS {CONFFILE}.d
+
+The default directory with config files. Used when
+.I mdadm
+is running without --config option, after successful reading of the
+.B {CONFFILE}
+default config file. Files in that directory
+are read in lexical order.
+
+
+.SS {CONFFILE2}
+
+Alternative config file that is read, when
+.I mdadm
+is running without --config option and the
+.B {CONFFILE}
+default config file was not opened successfully.
+
+.SS {CONFFILE2}.d
+
+The alternative directory with config files. Used when
+.I mdadm
+is runninng without --config option, after reading the
+.B {CONFFILE2}
+alternative config file whether it was successful or not. Files in
+that directory are read in lexical order.
 
 .SH EXAMPLE
 DEVICE /dev/sd[bcdjkl]1
-- 
2.27.0

Re: [PATCH 3/4] mdadm: Update config man regarding default files and multi-keyword behavior

[Coly Li]

On 3/18/22 4:26 PM, Lukasz Florczak wrote:
> Simplify default and alternative config file and directory location references
> from mdadm(8) as references to mdadm.conf(5). Add FILE section in config man
> and explain order and conditions in which default and alternative config files
> and directories are used.
>
> Update config man behavior regarding parsing order when multiple keywords/config
> files are involved.
>
> Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>


Tested and verified on openSUSE,

Acked-by: Coly Li <colyli@suse.de>


Thanks.


Coly Li


> ---
>   mdadm.8.in      | 30 +++++++++--------------
>   mdadm.conf.5.in | 65 ++++++++++++++++++++++++++++++++++++++++++++-----
>   2 files changed, 71 insertions(+), 24 deletions(-)
>
> diff --git a/mdadm.8.in b/mdadm.8.in
> index d41b3ca7..d6af73b7 100644
> --- a/mdadm.8.in
> +++ b/mdadm.8.in
> @@ -266,14 +266,11 @@ the exact meaning of this option in different contexts.
>   
>   .TP
>   .BR \-c ", " \-\-config=
> -Specify the config file or directory.  Default is to use
> -.B {CONFFILE}
> -and
> -.BR {CONFFILE}.d ,
> -or if those are missing then
> -.B {CONFFILE2}
> -and
> -.BR {CONFFILE2}.d .
> +Specify the config file or directory.  If not specified, default config file
> +and default conf.d directory will be used.  See
> +.BR mdadm.conf (5)
> +for more details.
> +
>   If the config file given is
>   .B "partitions"
>   then nothing will be read, but
> @@ -2008,11 +2005,9 @@ The config file is only used if explicitly named with
>   .B \-\-config
>   or requested with (a possibly implicit)
>   .BR \-\-scan .
> -In the later case,
> -.B {CONFFILE}
> -or
> -.B {CONFFILE2}
> -is used.
> +In the later case, default config file is used.  See
> +.BR mdadm.conf (5)
> +for more details.
>   
>   If
>   .B \-\-scan
> @@ -3341,16 +3336,15 @@ on Monitor mode.
>   
>   .SS {CONFFILE} (or {CONFFILE2})
>   
> -The config file lists which devices may be scanned to see if
> -they contain MD super block, and gives identifying information
> -(e.g. UUID) about known MD arrays.  See
> +Default config file.  See
>   .BR mdadm.conf (5)
>   for more details.
>   
>   .SS {CONFFILE}.d (or {CONFFILE2}.d)
>   
> -A directory containing configuration files which are read in lexical
> -order.
> +Default directory containing configuration files.  See
> +.BR mdadm.conf (5)
> +for more details.
>   
>   .SS {MAP_PATH}
>   When
> diff --git a/mdadm.conf.5.in b/mdadm.conf.5.in
> index 83edd008..dd331a6a 100644
> --- a/mdadm.conf.5.in
> +++ b/mdadm.conf.5.in
> @@ -88,7 +88,8 @@ but only the major and minor device numbers.  It scans
>   .I /dev
>   to find the name that matches the numbers.
>   
> -If no DEVICE line is present, then "DEVICE partitions containers" is assumed.
> +If no DEVICE line is present in any config file,
> +then "DEVICE partitions containers" is assumed.
>   
>   For example:
>   .IP
> @@ -272,6 +273,10 @@ catenated with spaces to form the address.
>   Note that this value cannot be set via the
>   .I mdadm
>   commandline.  It is only settable via the config file.
> +There should only be one
> +.B MAILADDR
> +line and it should have only one address.  Any subsequent addresses
> +are silently ignored.
>   
>   .TP
>   .B PROGRAM
> @@ -286,7 +291,8 @@ device.
>   
>   There should only be one
>   .B program
> -line and it should be give only one program.
> +line and it should be given only one program.  Any subsequent programs
> +are silently ignored.
>   
>   
>   .TP
> @@ -295,7 +301,14 @@ The
>   .B create
>   line gives default values to be used when creating arrays, new members
>   of arrays, and device entries for arrays.
> -These include:
> +
> +There should only be one
> +.B create
> +line.  Any subsequent lines will override the previous settings.
> +
> +Keywords used in the
> +.I CREATE
> +line and supported values are:
>   
>   .RS 4
>   .TP
> @@ -475,8 +488,8 @@ The known metadata types are
>   
>   .B AUTO
>   should be given at most once.  Subsequent lines are silently ignored.
> -Thus an earlier config file in a config directory will over-ride
> -the setting in a later config file.
> +Thus a later config file in a config directory will not overwrite
> +the setting in an earlier config file.
>   
>   .TP
>   .B POLICY
> @@ -594,6 +607,7 @@ The
>   line lists custom values of MD device's sysfs attributes which will be
>   stored in sysfs after the array is assembled. Multiple lines are allowed and each
>   line has to contain the uuid or the name of the device to which it relates.
> +Lines are applied in reverse order.
>   .RS 4
>   .TP
>   .B uuid=
> @@ -621,7 +635,46 @@ is running in
>   .B \-\-monitor
>   mode.
>   .B \-d/\-\-delay
> -command line argument takes precedence over the config file
> +command line argument takes precedence over the config file.
> +
> +If multiple
> +.B MINITORDELAY
> +lines are provided, only first non-zero value is considered.
> +
> +.SH FILES
> +
> +.SS {CONFFILE}
> +
> +The default config file location, used when
> +.I mdadm
> +is running without --config option.
> +
> +.SS {CONFFILE}.d
> +
> +The default directory with config files. Used when
> +.I mdadm
> +is running without --config option, after successful reading of the
> +.B {CONFFILE}
> +default config file. Files in that directory
> +are read in lexical order.
> +
> +
> +.SS {CONFFILE2}
> +
> +Alternative config file that is read, when
> +.I mdadm
> +is running without --config option and the
> +.B {CONFFILE}
> +default config file was not opened successfully.
> +
> +.SS {CONFFILE2}.d
> +
> +The alternative directory with config files. Used when
> +.I mdadm
> +is runninng without --config option, after reading the
> +.B {CONFFILE2}
> +alternative config file whether it was successful or not. Files in
> +that directory are read in lexical order.
>   
>   .SH EXAMPLE
>   DEVICE /dev/sd[bcdjkl]1

Re: [PATCH 3/4] mdadm: Update config man regarding default files and multi-keyword behavior

[Jes Sorensen]

On 3/18/22 04:26, Lukasz Florczak wrote:
> Simplify default and alternative config file and directory location references
> from mdadm(8) as references to mdadm.conf(5). Add FILE section in config man
> and explain order and conditions in which default and alternative config files
> and directories are used.
> 
> Update config man behavior regarding parsing order when multiple keywords/config
> files are involved.
> 
> Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>
> ---
>  mdadm.8.in      | 30 +++++++++--------------
>  mdadm.conf.5.in | 65 ++++++++++++++++++++++++++++++++++++++++++++-----
>  2 files changed, 71 insertions(+), 24 deletions(-)


Applied!

Thanks,
Jes

[PATCH 4/4] mdadm: Update config manual

[Lukasz Florczak]

Add missing HOMECLUSTER keyword description.

Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>
---
 mdadm.conf.5.in | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/mdadm.conf.5.in b/mdadm.conf.5.in
index dd331a6a..cd4e6a9d 100644
--- a/mdadm.conf.5.in
+++ b/mdadm.conf.5.in
@@ -439,6 +439,23 @@ from any possible local name. e.g.
 .B /dev/md/1_1
 or
 .BR /dev/md/home_0 .
+
+.TP
+.B HOMECLUSTER
+The
+.B homcluster
+line gives a default value for the
+.B \-\-homecluster=
+option to mdadm.  It specifies  the  cluster name for the md device.
+The md device can be assembled only on the cluster which matches
+the name specified. If
+.B homcluster
+is not provided, mdadm tries to detect the cluster name automatically.
+
+There should only be one
+.B homecluster
+line.  Any subsequent lines will be silently ignored.
+
 .TP
 .B AUTO
 A list of names of metadata format can be given, each preceded by a
-- 
2.27.0

Re: [PATCH 4/4] mdadm: Update config manual

[Coly Li]

On 3/18/22 4:26 PM, Lukasz Florczak wrote:
> Add missing HOMECLUSTER keyword description.
>
> Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>

Tested and verified on openSUSE,

Acked-by: Coly Li <colyli@suse.de>


Thanks.


Coly Li


> ---
>   mdadm.conf.5.in | 17 +++++++++++++++++
>   1 file changed, 17 insertions(+)
>
> diff --git a/mdadm.conf.5.in b/mdadm.conf.5.in
> index dd331a6a..cd4e6a9d 100644
> --- a/mdadm.conf.5.in
> +++ b/mdadm.conf.5.in
> @@ -439,6 +439,23 @@ from any possible local name. e.g.
>   .B /dev/md/1_1
>   or
>   .BR /dev/md/home_0 .
> +
> +.TP
> +.B HOMECLUSTER
> +The
> +.B homcluster
> +line gives a default value for the
> +.B \-\-homecluster=
> +option to mdadm.  It specifies  the  cluster name for the md device.
> +The md device can be assembled only on the cluster which matches
> +the name specified. If
> +.B homcluster
> +is not provided, mdadm tries to detect the cluster name automatically.
> +
> +There should only be one
> +.B homecluster
> +line.  Any subsequent lines will be silently ignored.
> +
>   .TP
>   .B AUTO
>   A list of names of metadata format can be given, each preceded by a

Re: [PATCH 4/4] mdadm: Update config manual

[Jes Sorensen]

On 3/18/22 04:26, Lukasz Florczak wrote:
> Add missing HOMECLUSTER keyword description.
> 
> Signed-off-by: Lukasz Florczak <lukasz.florczak@linux.intel.com>
> ---
>  mdadm.conf.5.in | 17 +++++++++++++++++
>  1 file changed, 17 insertions(+)
> 

Applied!

Thanks,
Jes