.\" See file COPYING in distribution for details.
-.TH MDMON 8 "" v3.0.2
+.TH MDMON 8 "" v4.1-rc2
.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.
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 /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
-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
-instance for each one found.
+in the foreground.
.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
-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
-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
-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
-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
-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-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).
projects / thirdparty / mdadm.git / blobdiff