.\" See file COPYING in distribution for details.
-.TH MDMON 8 "" v3.1.1
+.TH MDMON 8 "" v3.3.2
.SH NAME
mdmon \- monitor MD external metadata arrays
.SH SYNOPSIS
-.BI mdmon " CONTAINER [NEWROOT | PID]"
+.BI mdmon " [--all] [--takeover] [--foreground] CONTAINER"
.SH OVERVIEW
The 2.6.27 kernel brings the ability to support external metadata arrays.
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
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
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
-.I \-\-all
- which tells
-.I mdmon
-to scan for containers and launch an
-.I mdmon
-instance for each one found.
+device to monitor. It can be a full path like /dev/md/container, or a
+simple md device name like md127.
.TP
-[NEWROOT]
-In order to support an external metadata raid array as the rootfs
-.I mdmon
-needs to be started in the initramfs environment. Once the initramfs
-environment mounts the final rootfs
+.B \-\-foreground
+Normally,
.I mdmon
-needs to be restarted in the new namespace. When NEWROOT is specified
-.I mdmon
-will terminate any
-.I mdmon
-instances that are running in the current namespace,
-.IR chroot (2)
-to NEWROOT, and continue monitoring the container.
-
-Alternately the new
+will fork and continue in the background. Adding this option will
+skip that step and run
.I mdmon
-can be started after the new root has been installed with
-.I pivotroot
-by passing
-.B /
-as the NEWROOT. For
+in the foreground.
+.TP
+.B \-\-takeover
+This instructs
.I mdmon
-to be able to find and kill the old
+to replace any active
.I mdmon
-there must be some part of the filesystem that persists from before
-the
-.I pivotroot
-to afterwards. This can be
-.B /var/run/mdadm
-or some other directory. The default other directory is
-.B /lib/init/rw/mdadm
-but this can easily be changed when
+which is currently monitoring the array. This is primarily used late
+in the boot process to replace any
.I mdmon
-is compiled.
-If
+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
-cannot store the pid file in
-.B /var/run/mdadm
-it will store it in the other directory until
-.B /var/run/mdadm
-becomes available, or until it is killed.
+are in a standard place.
.TP
-[PID]
-If the second argument to
-.I mdmon
-does not start with a slash it is assumed to be the pid of a previous
-instance of
-.I mdmon
-to kill. This is used internally by
+.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
-to pass the pid across a chroot/exec and should not be used otherwise.
+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
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 EXMAPLES
+.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 /"
+.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 early in the boot sequence after a
-.I pivotroot
-to the final root filesystem, but before that filesystem is remounted
-read-write.
+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).