MDMON(8)		    System Manager's Manual		      MDMON(8)

NAME
       mdmon - monitor MD external metadata arrays


SYNOPSIS
       mdmon [--all] [--takeover] [--foreground] 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.

       --foreground
	      Normally, mdmon will fork and continue in the background.
	      Adding this option will skip that step and run mdmon in the
	      foreground.

       --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.

       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.

SEE ALSO
       mdadm(8), md(4).

v4.4								      MDMON(8)