X-Git-Url: http://git.ipfire.org/?a=blobdiff_plain;f=mdmon.8;h=beb82e035d0c015cfd7827a02a8c8e915cf91a89;hb=69a481166be6df468367378c16c02a2c5dbe5c24;hp=2720b45257bae68e3c4601e48dd7c2d3c748f995;hpb=b5c727dc1a55323f02e5f60a50bcecb866dd51ea;p=thirdparty%2Fmdadm.git

diff --git a/mdmon.8 b/mdmon.8
index 2720b452..beb82e03 100644
--- a/mdmon.8
+++ b/mdmon.8
@@ -1,11 +1,11 @@
 .\" See file COPYING in distribution for details.
-.TH MDMON 8 "" v3.1.1
+.TH MDMON 8 "" v3.3.4
 .SH NAME
 mdmon \- monitor MD external metadata arrays
 
 .SH SYNOPSIS
 
-.BI mdmon " [--all] [--takeover] CONTAINER"
+.BI mdmon " [--all] [--takeover] [--foreground] CONTAINER"
 
 .SH OVERVIEW
 The 2.6.27 kernel brings the ability to support external metadata arrays.
@@ -21,7 +21,7 @@ To service metadata update requests a daemon,
 is introduced.
 .I Mdmon
 is tasked with polling the sysfs namespace looking for changes in
-.BR array_state , 
+.BR array_state ,
 .BR sync_action ,
 and per disk
 .BR state
@@ -101,10 +101,10 @@ call is still required.
 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.  For
-example to create 2 arrays at different raid levels on a single
+relationship between a set of block devices and a RAID array.  For
+example to create 2 arrays at different RAID levels on a single
 set of disks, MD metadata requires the disks be partitioned and then
-each array can created be created with a subset of those partitions.  The
+each array can be created with a subset of those partitions.  The
 supported external formats perform this disk carving internally.
 .P
 Container devices simply hold references to all member disks and allow
@@ -131,6 +131,14 @@ The
 device to monitor.  It can be a full path like /dev/md/container, or a
 simple md device name like md127.
 .TP
+.B \-\-foreground
+Normally,
+.I mdmon
+will fork and continue in the background.  Adding this option will
+skip that step and run
+.I mdmon
+in the foreground.
+.TP
 .B \-\-takeover
 This instructs
 .I mdmon
@@ -157,6 +165,15 @@ This tells mdmon to find any active containers and start monitoring
 each of them if appropriate.  This is normally used with
 .B \-\-takeover
 late in the boot sequence.
+A separate
+.I mdmon
+process is started for each container as the
+.B \-\-all
+argument is over-written with the name of the container.  To allow for
+containers with names longer than 5 characters, this argument can be
+arbitrarily extended, e.g. to
+.BR \-\-all-active-arrays .
+.TP
 
 .PP
 Note that
@@ -164,21 +181,77 @@ Note that
 is automatically started by
 .I mdadm
 when needed and so does not need to be considered when working with
-RAID arrays.  The only times it is run other that by
+RAID arrays.  The only times it is run other than by
 .I  mdadm
 is when the boot scripts need to restart it after mounting the new
 root filesystem.
 
+.SH START UP AND SHUTDOWN
+
+As
+.I mdmon
+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
+.I mdmon
+monitored device.
+Note that in general
+.I mdmon
+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.
+
+When the array is assembled by the
+.B initramfs
+code, mdadm will automatically start
+.I mdmon
+as required.  This means that
+.I mdmon
+must be installed on the
+.B initramfs
+and there must be a writable filesystem (typically tmpfs) in which
+.B mdmon
+can create a
+.B .pid
+and
+.B .sock
+file.  The particular filesystem to use is given to mdmon at compile
+time and defaults to
+.BR /run/mdadm .
+
+This filesystem must persist through to shutdown time.
+
+After the final root filesystem has be instantiated (usually with
+.BR pivot_root )
+.I mdmon
+should be run with
+.I "\-\-all \-\-takeover"
+so that the
+.I mdmon
+running from the
+.B initramfs
+can be replaced with one running in the main root, and so the
+memory used by the initramfs can be released.
+
+At shutdown time,
+.I mdmon
+should not be killed along with other processes.  Also as it holds a
+file (socket actually) open in
+.B /dev
+(by default) it will not be possible to unmount
+.B /dev
+if it is a separate filesystem.
+
 .SH EXAMPLES
 
-.B "  mdmon \-\-all \-\-takeover"
+.B "  mdmon \-\-all-active-arrays \-\-takeover"
 .br
 Any
 .I mdmon
 which is currently running is killed and a new instance is started.
-This should be run late in the boot sequence and particularly after
-.B /var
-is mounted and writable.
+This should be run during in the boot sequence if an initramfs was
+used, so that any mdmon running from the initramfs will not hold
+the initramfs active.
 .SH SEE ALSO
 .IR mdadm (8),
 .IR md (4).