mdadm: load default sysfs attributes after assemblation

[thirdparty/mdadm.git] / mdmon.8

diff --git a/mdmon.8 b/mdmon.8
index c9cb5de8561b6e618a3afe9067cf117645913506..4cbc2ba7ef5f5b40faef77eeb0051d883ef61c4c 100644 (file)
--- a/mdmon.8
+++ b/mdmon.8
@@ -1,11 +1,11 @@
 .\" See file COPYING in distribution for details.
 .\" See file COPYING in distribution for details.

-.TH MDMON 8 "" v3.0-rc1
+.TH MDMON 8 "" v4.1-rc2

 .SH NAME
 mdmon \- monitor MD external metadata arrays
 
 .SH SYNOPSIS
 
 .SH NAME
 mdmon \- monitor MD external metadata arrays
 
 .SH SYNOPSIS
 

-.BI mdmon " CONTAINER [NEWROOT]"
+.BI mdmon " [--all] [--takeover] [--foreground] CONTAINER"

 
 .SH OVERVIEW
 The 2.6.27 kernel brings the ability to support external metadata arrays.
 
 .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
 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
 .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
 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
 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
 supported external formats perform this disk carving internally.
 .P
 Container devices simply hold references to all member disks and allow


@@ -128,37 +128,130 @@ device>/<member index>" if the array is to remain readonly.
 CONTAINER
 The
 .B container
 CONTAINER
 The
 .B container

-device to monitor.  It can be a full path like /dev/md/container, a simple md
-device name like md127, or /proc/mdstat which tells
+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
 .I mdmon

-to scan for containers and launch an
+will fork and continue in the background.  Adding this option will
+skip that step and run

 .I mdmon
 .I mdmon

-instance for each one found.
+in the foreground.

 .TP
 .TP

-[NEWROOT]
-In order to support an external metadata raid array as the rootfs
+.B \-\-takeover
+This instructs
+.I mdmon
+to replace any active

 .I mdmon
 .I mdmon

-needs to be started in the initramfs environment.  Once the initramfs
-environment mounts the final rootfs
+which is currently monitoring the array.  This is primarily used late
+in the boot process to replace any

 .I mdmon
 .I mdmon

-needs to be restarted in the new namespace.  When NEWROOT is specified
+which was started from an
+.B initramfs
+before the root filesystem was mounted.  This avoids holding a
+reference on that
+.B initramfs
+indefinitely and ensures that the
+.I pid
+and
+.I sock
+files used to communicate with

 .I mdmon
 .I mdmon

-will terminate any
+are in a standard place.
+.TP
+.B \-\-all
+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
 .I mdmon

-instances that are running in the current namespace,
-.IR chroot (2)
-to NEWROOT, and continue monitoring the container.
+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
 .I mdmon
 is automatically started by
 .I mdadm
 when needed and so does not need to be considered when working with
 .PP
 Note that
 .I mdmon
 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.
 
 .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-active-arrays \-\-takeover"
+.br
+Any
+.I mdmon
+which is currently running is killed and a new instance is started.
+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).
 .SH SEE ALSO
 .IR mdadm (8),
 .IR md (4).