Bug 434671 - mdadm.8 says "mdadm -G -x" is valid, but it is rejected.
mdadm.8 says "mdadm -G -x" is valid, but it is rejected.
Status: CLOSED ERRATA
Product: Red Hat Enterprise Linux 5
Classification: Red Hat
Component: mdadm (Show other bugs)
5.1
All Linux
low Severity low
: rc
: ---
Assigned To: Doug Ledford
BaseOS QE
:
Depends On:
Blocks:
  Show dependency treegraph
 
Reported: 2008-02-24 01:14 EST by Chris Pepper
Modified: 2009-09-02 07:52 EDT (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
The mdadm man page contained several typos and was not clear on the proper usage of a number of mdadm options. The typos have been removed and notes and clarifications have been added so that the man page now better reflects the proper usage and limitations of the mdadm command.
Story Points: ---
Clone Of:
Environment:
Last Closed: 2009-09-02 07:52:33 EDT
Type: ---
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:


Attachments (Terms of Use)

  None (edit)
Description Chris Pepper 2008-02-24 01:14:12 EST
Description of problem:
mdadm.8 says "mdadm -G -x" is valid, but it is rejected my the mdadm command.

Version-Release number of selected component (if applicable):
v2.5.4

How reproducible:
Always

Steps to Reproduce:
1.[root@inspector ~]# mdadm /dev/md4 -v -G -x 0
  
Actual results:
mdadm: option -x not valid in grow mode

Expected results:
Spare (component #3) should be changed to active.

Additional info:
Workaround is to use -G -n, e.g., "mdadm /dev/md4 -v -G -n 3"
Comment 1 Chris Pepper 2008-02-24 01:14:47 EST
Forgot the snippet of mdadm.8:

For create, build, or grow:
       -n, --raid-devices=
	      Specify  the  number of active devices in the array.  This, plus
	      the number of spare devices (see below) must equal the number of
	      component-devices  (including "missing" devices) that are listed
	      on the command line for --create.  Setting a value of 1 is prob-
	      ably  a mistake and so requires that --force be specified first.
	      A value of 1 will then be allowed for linear,  multipath,  raid0
	      and raid1.  It is never allowed for raid4 or raid5.
	      This  number  can only be changed using --grow for RAID1 arrays,
	      and only on kernels which provide necessary support.


       -x, --spare-devices=
	      Specify the number of  spare  (eXtra)  devices  in  the  initial
	      array.   Spares can also be added and removed later.  The number
	      of component devices listed on the command line must  equal  the
	      number of raid devices plus the number of spare devices.
Comment 2 Doug Ledford 2008-02-25 13:14:46 EST
You are correct that the man page is misleading here.  Use of -x during grow
operations is *not* supported.  The man page was not clear as it didn't list -x
as an exception to the "For create, build, grow:" header.  The purpose of the -x
option is only to set the number of spare devices "in the initial array.", which
implies at array creation/build time.  Later, there is no need to set the spare
devices as you simply add devices to the array and the array will automatically
grow to include the new device as a spare device if the array is already fully
populated with devices.

So, just to be clear, once an array is already created, there is no need to grow
the spare devices, just using manage mode to add extra devices will
automatically add them as spares.
Comment 3 Chris Pepper 2008-02-25 17:04:25 EST
No, I had a legitimate use for -x post-creation. I created a 2-disk mirror, added a component, and 
wanted to use synch data onto that component, so I wanted -x0; the workaround was to use -n3 instead, 
which accomplished the same thing from the opposite direction.

Either -x should work with --grow (which would be best) or the manual page should be corrected.

Thanks!
Comment 4 RHEL Product and Program Management 2008-07-21 19:06:15 EDT
This request was evaluated by Red Hat Product Management for
inclusion, but this component is not scheduled to be updated in
the current Red Hat Enterprise Linux release. If you would like
this request to be reviewed for the next minor release, ask your
support representative to set the next rhel-x.y flag to "?".
Comment 9 Doug Ledford 2009-05-19 11:59:30 EDT
(In reply to comment #3)
> No, I had a legitimate use for -x post-creation. I created a 2-disk mirror,
> added a component, and 
> wanted to use synch data onto that component, so I wanted -x0; the workaround
> was to use -n3 instead, 
> which accomplished the same thing from the opposite direction.

Actually, that's not the work around, that *is* the correct way to do what you wanted.  You wanted to expand the array to include three active disks instead of two, so the proper way to do that is to grow the active disk count to 3 (-n3).

> Either -x should work with --grow (which would be best) or the manual page
> should be corrected.

I've updated the man page:

       -x, --spare-devices=
              Specify the number of  spare  (eXtra)  devices  in  the  initial
              array.   The  number  of component devices listed on the command
              line must equal the number of raid devices plus  the  number  of
              spare devices.

              After initial array creation, new devices are added to the array
              using the --add command.  If you add devices in  excess  of  the
              number  needed  for the array, they are automatically treated as
              spare devices.  For grow mode, it is not possible  to  grow  the
              number  of  spare  devices, instead you need to grow (or shrink)
              the number of active devices in the array.   Spare  devices  are
              handled automatically after initial array creation.
Comment 11 Ruediger Landmann 2009-05-21 01:53:25 EDT
Release note added. If any revisions are required, please set the 
"requires_release_notes" flag to "?" and edit the "Release Notes" field accordingly.
All revisions will be proofread by the Engineering Content Services team.

New Contents:
The mdadm man page documents the use of the "-x" option under the heading "For create, build, or grow" but did not explain that the use of -x during grow operations is not supported. The man page now explains the correct use and limitations of this option.
Comment 12 Ruediger Landmann 2009-05-21 19:46:12 EDT
Release note updated. If any revisions are required, please set the 
"requires_release_notes"  flag to "?" and edit the "Release Notes" field accordingly.
All revisions will be proofread by the Engineering Content Services team.

Diffed Contents:
@@ -1 +1 @@
-The mdadm man page documents the use of the "-x" option under the heading "For create, build, or grow" but did not explain that the use of -x during grow operations is not supported. The man page now explains the correct use and limitations of this option.+The mdadm man page contained several typos and was not clear on the proper usage of a number of mdadm options. The typos have been removed and notes and clarifications have been added so that the man page now better reflects the proper usage and limitations of the mdadm command.
Comment 15 errata-xmlrpc 2009-09-02 07:52:33 EDT
An advisory has been issued which should help the problem
described in this bug report. This report is therefore being
closed with a resolution of ERRATA. For more information
on therefore solution and/or where to find the updated files,
please follow the link below. You may reopen this bug report
if the solution does not work for you.

http://rhn.redhat.com/errata/RHBA-2009-1382.html

Note You need to log in before you can comment on or make changes to this bug.