polishing up mdadm manpages: mdassemble(8), mdmon(8)

[Christoph Anton Mitterer <calestyo@scientia.net>]

[-- Attachment #1: Type: text/plain, Size: 2141 bytes --]

Hi.

Recently I've started to read into MD/mdadm and what started then as
maintaining a quilt patch with several typos and so ended up in a somewhat
"bigger" rework.

- The text iself is (hopefully) largely the same, perhaps apart from some
wording, or ordering.
- More consistent usage of markup:
  -bold for programs, options, files, manpage references (except in the
SEE ALSO section) and text the is somehow set or "entered"
  -italitcs (which is typically displayed as underlined) for any
non-terminals.
- Consistent writing of words like Linux, RAID, program names (which were
previously off mixed) apart from those places where they're options (e.g.
raid1 is still raid1 and not RAID1 for the --level option).
- Completely rewritten the formatting of the manpage (the dozens of .B, .I
... just to format one word made the source file really unreadable IMHO).

In mdmon(8) there were some places where changed things that could
possibly changing the semantics:
- mdadm --remove <container> <victim>   =>   mdadm --remove CONTAINER
DEVICE
- with  a metadata version string "external:<metadata name>"   =>   with a
metadata format string "external:format"
- .pid and .sock files   =>   PID and socket files

I wasn't sure about the following so didn't change it:
- <disk>/state - faulty
  Is <disk> a non-terminal for a device (and thus should I replace it with
an italics "device"?
- (for example, the metadata version has been set to "external:-dev/md127"
instead of "external:/dev/md127")
  Is the "version" correct here?


I've also started to rewrite md(4), mdadm(8) and mdadm.conf(5) manpges...
- unifying many further writings of words like "read-only/readonly",
"read-write/readwrite", etc. pp.
- etc.
but I'm not sure if/when I can finish them.


Sorry for not sending a (easily reviewable) patch, but there were so many
changes (in the line wrapping and so), that this did not make much sense.
Please tell me whether you like and will apply it, so that I can continue
with the remaining manpages.
Anyway, if you merge them, please _really_ read them again for
mistakes/typos I might have accidentally added...!


Thanks,
Chris.

[-- Attachment #2: mdassemble.8 --]
[-- Type: application/octet-stream, Size: 1322 bytes --]

.TH MDASSEMBLE 8 "" v3.2




.SH NAME
mdassemble \- assemble MD devices


.SH SYNOPSIS
\fBmdassemble\fR


.SH DESCRIPTION 
\fBmdassemble\fR is a tiny program that can be used to assemble MD devices
inside an initial ramdisk (initrd) or an initramfs.
.br
It is meant to replace the in-kernel automatic RAID detection and activation.
.P
It can be built statically and linked against lightweight libc implementations
like \fBklibc\fR, \fBuClibc\fR or \fBdietlibc\fR.


.SH USAGE
Invoking \fBmdassemble\fR has the same effect as invoking \fBmdadm \-\-assemble
\-\-scan\fR.
.P
Invoking \fBmdassemble\fR a second time will mark all defined arrays as
"read-write".
.br
This is useful when using the \fBstart_ro\fR parameter to the \fBmd_mod\fR
kernel module.


.SH OPTIONS
There are no options to \fBmdassemble\fR.


.SH FILES
.SS /etc/mdadm.conf
This file lists the devices which may be scanned to see if they contain MD
superblocks and gives identifying information (e.g. an UUID) about known MD
arrays.
.P
\fBmdassemble\fR supports all configuration parameters defined in
\fBmdadm.conf\fR with the exception of the \fBauto=\fR tag which is only
supported if \fBmdadm\fR was built with \fBMDASSEMBLE_AUTO\fR being defined.
.P
See the \fBmdadm.conf\fR(5) manpage for more details.


.SH SEE ALSO
mdadm(8),
mdadm.conf(5),
md(4).

[-- Attachment #3: mdmon.8 --]
[-- Type: application/octet-stream, Size: 7857 bytes --]

.TH MDMON 8 "" v3.2




.SH NAME
mdmon \- monitor MD external metadata arrays


.SH SYNOPSIS
\fBmdmon \fI[\fB--all\fI] [\fB--takeover\fI] CONTAINER\fR


.SH OVERVIEW
Linux 2.6.27 brings the ability to support external metadata arrays.  External
metadata implies that the user-space handles all updates to the metadata.
.P
The kernel's responsibility is to notify the user-space when a "metadata event"
(like disk failures and clean-to-dirty transitions) occurs.
.br
In important cases the kernel waits for the user-space to take action on these
notifications.


.SH DESCRIPTION
.SS Metadata updates:
To serve metadata update requests a daemon (\fBmdmon\fR) is introduced.
\fBmdmon\fR is tasked with polling the sysfs namespace, looking for changes in
\fBarray_state\fR, \fBsync_action\fR, and per-device \fBstate\fR attributes.
When a change is detected it calls a per-metadata type handler to make
modifications to the metadata.
.P
The following actions are taken:
.RS
.TP
.B array_state \- inactive
Clear the dirty bit for the volume and let the array be stopped.
.TP
.B array_state \- write pending
Set the dirty bit for the array and then set \fBarray_state\fR to \fBactive\fR.
Writes are blocked until the user-space writes \fBactive\fR.
.TP
.B array_state \- active\-idle
The safe mode timer has expired so set array state to clean to block writes to
the array.
.TP
.B array_state \- clean
Clear the dirty bit for the volume.
.TP
.B array_state \- read\-only
This is the initial state that all arrays start at.
.RS
.TP
\fBmdmon\fR takes one of these three actions:
.TP
1.
Transition the array to read\-auto keeping the dirty bit clear if the metadata
handler determines that the array does not need resyncing or other modification.
.TP
2.
Transition the array to active if the metadata handler determines a resync or
some other manipulation is necessary.
.TP
3.
Leave the array read\-only if the volume is marked not to be monitored (for
example, the metadata version has been set to "\fBexternal:\-dev/md127\fR"
instead of "\fBexternal:/dev/md127\fR").
.RE
.TP
.B sync_action \- resync\-to\-idle
Notify the metadata handler that a resync may have completed.  If a resync
process has idled before it completes this event allows the metadata handler to
checkpoint resync.
.TP
.B sync_action \- recover\-to\-idle
A spare disk may have completed rebuilding so tell the metadata handler about
the state of each disk.  This is the metadata handler's opportunity to clear any
"out\-of\-sync" bits and clear the volume's degraded status.  If a recovery
process has idled before it completes this event allows the metadata handler to
checkpoint recovery.
.TP
.B <disk>/state \- faulty
A disk failure kicks off a series of events:
.br
First notify the metadata handler that a disk has failed and then notify the
kernel that it can unblock writes that were dependent on this disk.
.br
After unblocking the kernel this disk is set to be removed(*) from the member
array.
.br
Finally the disk is marked as failed in all other member arrays in the
container.
.RS
.IP (*)
This behavior differs slightly from native MD arrays where removal is reserved
for a \fBmdadm --remove\fR event.  In the external metadata case the container
holds the final reference on a block device and a \fBmdadm --remove
\fICONTAINER DEVICE\fR call is still required.
.RE

.SS Containers:
External metadata formats, like DDF, differ from the native MD metadata formats
in that they define a set of disks and a series of sub-arrays within those
disks.  MD metadata in comparison defines a 1:1 relationship between a set of
block devices and a RAID array.
.br
For example to create 2 arrays at different RAID levels on a single set of
disks, MD metadata requires the disks to be partitioned and then each array can
be created with a subset of those partitions.
.br
The supported external formats perform this disk carving internally.
.P
Container devices simply hold references to all member disks and allow
tools like \fBmdmon\fR to determine which active arrays belong to which
container.  Some array management commands (like disk removal or disk addition)
are now only valid at the container level.
.br
Attempts to perform these actions on member arrays are blocked with error
messages like:
.IP
mdadm: Cannot remove disks from a \'member\' array, perform this operation on
the parent container
.P
Containers are identified in \fB/proc/mdstat\fR with a metadata format string
"\fBexternal:\fIformat\fR".
.br
Member devices are identified by
"\fBexternal:/\fIcontainer-device\fB/\fImember-index\fR" or
"\fBexternal:-\fIcontainer-device\fB/\fImember-index\fR" if the array is to
remain read-only.


.SH OPTIONS
.TP
.I CONTAINER
The container device to monitor.
.br
It can be a full path like "\fB/dev/md/container\fR" or a simple MD device name
like "\fBmd127\fR".
.TP
.B \-\-takeover
This instructs \fBmdmon\fR to replace any active \fBmdmon\fR which is currently
monitoring the array.
.IP
This is primarily used in the late boot process to replace any \fBmdmon\fR which
was started from an initramfs before the root filesystem was mounted.  This
avoids holding a reference on that initramfs indefinitely and ensures that the
PID and socket files used to communicate with \fBmdmon\fR are in a standard
place.
.TP
.B \-\-all
This tells \fBmdmon\fR to find any active containers and start monitoring each
of them if appropriate.  This is normally used with \fB\-\-takeover\fR in the
late boot process.
.IP
A separate \fBmdmon\fR process is started for each container with the
\fB\-\-all\fR argument being replaced by the name of the respective container.
.br
To allow for containers with names longer than 5 characters this argument can be
arbitrarily extended, e.g. to \fB\-\-all-active-arrays\fR.
.P
Note that \fBmdmon\fR is automatically started by \fBmdadm\fR when needed and so
does not need to be considered when working with RAID arrays.  The only times it
is run other than by \fBmdadm\fR is when the boot scripts need to restart it
after mounting the new root filesystem.


.SH START UP AND SHUTDOWN
As \fBmdmon\fR needs to be running whenever any filesystem on the monitored
device is mounted there are special considerations when the root filesystem is
mounted from an \fBmdmon\fR monitored device.
.P
Note that in general \fBmdmon\fR is needed even if the filesystem is mounted
read-only as some filesystems can still write to the device in those
circumstances, for example to replay a journal after an unclean shutdown.
.P
When the array is assembled by the initramfs code, \fBmdadm\fR will
automatically start \fBmdmon\fR as required.  This means that \fBmdmon\fR must
be installed within the initramfs and there must be a writable filesystem
(typically tmpfs) in which \fBmdmon\fR can create a PID and socket file.
.br
The particular filesystem to use is given to \fBmdmon\fR at compile time and
defaults to \fB/dev/.mdadm\fR.  This filesystem must persist through to
shutdown time.
.br
After the final root filesystem has be instantiated (usually with
\fBpivot_root\fR) \fBmdmon\fR should be run with \fB\-\-all \-\-takeover\fR so
that the \fBmdmon\fR running from the initramfs can be replaced with one running
in the main root so that the memory used by the initramfs can be released.
.P
At shutdown time, \fBmdmon\fR should not be killed along with other processes.
.br
Also, as it holds a file (of type socket) open in \fB/dev\fR (by default) it
will not be possible to unmount \fB/dev\fR if it is on a separate filesystem.


.SH EXAMPLES
\fBmdmon \-\-all-active-arrays \-\-takeover\fR
.P
Any \fBmdmon\fR which is currently running is killed and a new instance is
started.
.br
This should be run during in the boot sequence if an initramfs was used, so that
any \fBmdmon\fR running from the initramfs will not hold the initramfs active.


.SH SEE ALSO
mdadm(8),
md(4).