Ubuntu Manpage: mdmon - monitor MD external metadata arrays

Provided by: mdadm_3.2.5-5ubuntu4.4_amd64

NAME

       mdmon - monitor MD external metadata arrays

SYNOPSIS

       mdmon [--all] [--takeover] [--offroot] CONTAINER

OVERVIEW

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

DESCRIPTION

Metadata updates:
To service metadata update requests a daemon, mdmon, is introduced. Mdmon is tasked with polling the
sysfs namespace looking for changes in array_state, sync_action, and per disk state attributes. When a
change is detected it calls a per metadata type handler to make modifications to the metadata. The
following actions are taken:

array_state - inactive
Clear the dirty bit for the volume and let the array be stopped

array_state - write pending
Set the dirty bit for the array and then set array_state to active. Writes are blocked
until userspace writes active.

array_state - active-idle
The safe mode timer has expired so set array state to clean to block writes to the array

array_state - clean
Clear the dirty bit for the volume

array_state - read-only
This is the initial state that all arrays start at. mdmon takes one of the three actions:

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

2/ Transition the array to active if the metadata handler determines a resync or some
other manipulation is necessary

3/ Leave the array read-only if the volume is marked to not be monitored; for example,
the metadata version has been set to "external:-dev/md127" instead of
"external:/dev/md127"

sync_action - resync-to-idle
Notify the metadata handler that a resync may have completed. If a resync process is idled
before it completes this event allows the metadata handler to checkpoint resync.

sync_action - recover-to-idle
A spare 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 is idled before it completes this
event allows the metadata handler to checkpoint recovery.

<disk>/state - faulty
A disk failure kicks off a series of events. 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. After unblocking the kernel this disk is set to be removed+ from the member
array. Finally the disk is marked failed in all other member arrays in the container.

+ Note This behavior differs slightly from native MD arrays where removal is reserved for a
mdadm --remove event. In the external metadata case the container holds the final
reference on a block device and a mdadm --remove <container> <victim> call is still
required.

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. 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 be created with a subset of those partitions. The supported external formats perform this
disk carving internally.

Container devices simply hold references to all member disks and allow tools like mdmon to determine
which active arrays belong to which container. Some array management commands like disk removal and disk
add are now only valid at the container level. Attempts to perform these actions on member arrays are
blocked with error messages like:

"mdadm: Cannot remove disks from a ´member´ array, perform this operation on the parent container"

Containers are identified in /proc/mdstat with a metadata version string "external:<metadata name>".
Member devices are identified by "external:/<container device>/<member index>", or "external:-<container
device>/<member index>" if the array is to remain readonly.

OPTIONS

CONTAINER
The container device to monitor. It can be a full path like /dev/md/container, or a simple md
device name like md127.

--takeover
This instructs mdmon to replace any active mdmon which is currently monitoring the array. This is
primarily used late in the boot process to replace any mdmon 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 sock files used to communicate with mdmon are in a
standard place.

--all This tells mdmon to find any active containers and start monitoring each of them if appropriate.
This is normally used with --takeover late in the boot sequence. A separate mdmon process is
started for each container as the --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 --all-active-arrays.

--offroot
Set first character of argv[0] to @ to indicate mdmon was launched from initrd/initramfs and
should not be shutdown by systemd as part of the regular shutdown process. This option is normally
only used by the system's initscripts. Please see here for more details on how systemd handled
argv[0]:

http://www.freedesktop.org/wiki/Software/systemd/RootStorageDaemons

Note that mdmon is automatically started by mdadm when needed and so does not need to be considered when
working with RAID arrays. The only times it is run other than by mdadm is when the boot scripts need to
restart it after mounting the new root filesystem.

START UP AND SHUTDOWN

       As 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 mdmon monitored device.  Note that in  general
       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 initramfs code, mdadm will  automatically  start  mdmon  as  required.
       This  means  that  mdmon  must  be  installed  on  the  initramfs and there must be a writable filesystem
       (typically tmpfs) in which mdmon can create a .pid and .sock file.  The particular filesystem to  use  is
       given to mdmon at compile time and defaults to /run/mdadm.

       This filesystem must persist through to shutdown time.

       After  the  final  root filesystem has be instantiated (usually with pivot_root) mdmon should be run with
       --all --takeover so that the mdmon running from the 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, mdmon should not be killed along with other processes.  Also as it holds a file (socket
       actually)  open  in  /dev  (by  default)  it  will  not  be  possible to unmount /dev if it is a separate
       filesystem.

EXAMPLES

         mdmon --all-active-arrays --takeover
       Any 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.