Provided by: mdadm_3.3-2ubuntu7_i386 bug

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