source: postlfs/filesystems/mdadm.xml@ cfde9651

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY mdadm-download-http "&kernel-dl;/linux/utils/raid/mdadm/mdadm-&mdadm-version;.tar.xz">
  <!ENTITY mdadm-download-ftp " ">
  <!ENTITY mdadm-md5sum        "a304eb0a978ca81045620d06547050a6">
  <!ENTITY mdadm-size          "444 KB">
  <!ENTITY mdadm-buildsize     "5.0 MB">
  <!ENTITY mdadm-time          "0.1 SBU">
<!--  <!ENTITY mdadm-time          "0.1 SBU (tests take about an hour, only partially processor dependent)">-->
]>

<sect1 id="mdadm" xreflabel="mdadm-&mdadm-version;">
  <?dbhtml filename="mdadm.html"?>


  <title>mdadm-&mdadm-version;</title>

  <indexterm zone="mdadm">
    <primary sortas="a-mdadm">mdadm</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to mdadm</title>

    <para>
      The <application>mdadm</application> package contains administration
      tools for software RAID.
    </para>

    &lfs113_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&mdadm-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&mdadm-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &mdadm-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &mdadm-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &mdadm-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &mdadm-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">mdadm Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      A <xref linkend="server-mail"/>
    </para>
    <!-- Contains -DSendmail=/usr/sbin/sendmail in the build procedure -->

    <caution>
      <para>
        Kernel versions in series 4.1 through 4.4.1 have a broken RAID
        implementation. Use a kernel with version at or above 4.4.2.
      </para>
    </caution>

  </sect2>

  <sect2 role="kernel" id='mdadm-kernel'>
    <title>Kernel Configuration</title>

    <para>
      Enable the following options in the kernel configuration
      and recompile the kernel, if necessary.  Only the RAID types desired
      are required.
    </para>

<screen><literal>Device Drivers ---&gt;
  [*] Multiple devices driver support (RAID and LVM) ---&gt; [CONFIG_MD]
    &lt;*&gt; RAID support                                      [CONFIG_BLK_DEV_MD]
    [*]   Autodetect RAID arrays during kernel boot       [CONFIG_MD_AUTODETECT]
    &lt;*/M&gt;  Linear (append) mode                           [CONFIG_MD_LINEAR]
    &lt;*/M&gt;  RAID-0 (striping) mode                         [CONFIG_MD_RAID0]
    &lt;*/M&gt;  RAID-1 (mirroring) mode                        [CONFIG_MD_RAID1]
    &lt;*/M&gt;  RAID-10 (mirrored striping) mode               [CONFIG_MD_RAID10]
    &lt;*/M&gt;  RAID-4/RAID-5/RAID-6 mode                      [CONFIG_MD_RAID456]</literal></screen>

    <indexterm zone="mdadm mdadm-kernel">
      <primary sortas="d-mdadm">mdadm</primary>
    </indexterm>

  </sect2>

  <sect2 role="installation">
    <title>Installation of mdadm</title>
<!--
    <para>
      Fix a build error introduced by gcc-7.1:
    </para>

<screen><userinput>sed 's@-Werror@@' -i Makefile</userinput></screen>
-->
    <para>
      Build <application>mdadm</application> by running the following
      command:
    </para>

<screen><userinput>make</userinput></screen>

    <para>
      This package does not come with a working test suite.
    </para>

<!--
    The test suite errors out after about half the tests are run.
    Of those tests, about half fail.
    There are tests that indicate failure when the test is clearly wrong
    for the current code.
    I asked about it at linux-raid@vger.kernel.org, but did not get
    a responsive answer.
      - bdubbs 6 January 22


    <para>
      If you wish to run the tests, ensure that your kernel supports RAID
      and that a version of mdadm is not already running.  As many as 9 out
      of 124 tests may fail.
    </para>

    <caution>
      <para>
        The tests edit values in /proc and run tests on software raid devices.
        They shouldn't be run on systems with active software RAID devices.
      </para>
    </caution>

    <para>
      Run the tests as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"
        remap="test"><userinput>./test - -keep-going - -logdir=test-logs - -save-logs</userinput></screen>
-->
    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>make BINDIR=/usr/sbin install</userinput></screen>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>make everything</command>: This optional target creates extra
      programs, particularly a statically-linked version of
      <command>mdadm</command>. <!-- and also versions of
      <command>mdassemble</command>. These all need to be manually installed.-->
      This needs to be manually installed.
    </para>

    <para>
      <parameter>--keep-going</parameter>: Run the tests to the end, even if one
      or more tests fail.
    </para>

    <para>
      <parameter>--logdir=test-logs</parameter>: Defines the directory
      where test logs are saved.
    </para>

    <para>
      <parameter>--save-logs</parameter>:
      Instructs the test suite to save the logs.
    </para>

    <para>
      <option>--tests=<replaceable>&lt;test1,test2,...&gt;</replaceable></option>:
      Optional comma separated list of tests to be executed
      (all tests, if this option is not passed).
    </para>

  </sect2>


  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directory</segtitle>

      <seglistitem>
        <seg>mdadm and mdmon <!--and optionally mdassemble--></seg>
        <seg>None</seg>
        <seg>None</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="mdadm-prog">
        <term><command>mdadm</command></term>
        <listitem>
          <para>
            manages MD devices aka Linux Software RAID
          </para>
          <indexterm zone="mdadm mdadm-prog">
            <primary sortas="b-mdadm-prog">mdadm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="mdmon">
        <term><command>mdmon</command></term>
        <listitem>
          <para>
            monitors MD external metadata arrays
          </para>
          <indexterm zone="mdadm mdmon">
            <primary sortas="b-mdmon">mdmon</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <!-- Seems to be removed without a trace in 4.1
      <varlistentry id="mdassemble">
        <term><command>mdassemble</command></term>
        <listitem>
          <para>
            is a tiny program that can be used to assemble MD devices
            inside an initial ramdisk (initrd) or initramfs
          </para>
          <indexterm zone="mdadm mdassemble">
            <primary sortas="b-mdassemble">mdassemble</primary>
          </indexterm>
        </listitem>
      </varlistentry>
      -->

    </variablelist>

  </sect2>

</sect1>