mdmon(8) — Linux manual page

NAME | SYNOPSIS | OVERVIEW | DESCRIPTION | OPTIONS | START UP AND SHUTDOWN | EXAMPLES | SEE ALSO | COLOPHON

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

NAME         top

       mdmon - monitor MD external metadata arrays

SYNOPSIS         top

       mdmon [--all] [--takeover] [--foreground] CONTAINER

OVERVIEW         top

       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         top

   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         top

       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         top

       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         top

         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         top

       mdadm(8), md(4).

COLOPHON         top

       This page is part of the mdadm (Tool for managing md arrays in
       Linux) project.  Information about the project can be found at 
       ⟨http://neil.brown.name/blog/mdadm⟩.  If you have a bug report for
       this manual page, send it to [email protected].  This
       page was obtained from the project's upstream Git repository
       ⟨https://git.kernel.org/pub/scm/utils/mdadm/mdadm.git/⟩ on
       2024-06-14.  (At that time, the date of the most recent commit
       that was found in the repository was 2024-06-13.)  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for
       the page, or you have corrections or improvements to the
       information in this COLOPHON (which is not part of the original
       manual page), send a mail to [email protected]

v4.3                                                            MDMON(8)

Pages that refer to this page: md(4)mdadm(8)raid6check(8)