<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="re-drbdadm">
  <refentryinfo>
    <date>6 May 2011</date>

    <productname>DRBD</productname>

    <productnumber>8.4.0</productnumber>
  </refentryinfo>

  <refmeta>
    <refentrytitle>drbdadm</refentrytitle>

    <manvolnum>8</manvolnum>

    <refmiscinfo class="manual">System Administration</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>drbdadm</refname>

    <refpurpose>Administration tool for DRBD <indexterm significance="normal">
        <primary>drbdadm</primary>
      </indexterm></refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis sepchar=" ">
      <command moreinfo="none">drbdadm</command>

      <arg choice="opt" rep="norepeat">-d</arg>

      <arg choice="opt" rep="norepeat">-c<arg choice="req"
      rep="norepeat"><replaceable>file</replaceable></arg></arg>

      <arg choice="opt" rep="norepeat">-t<arg choice="req"
      rep="norepeat"><replaceable>file</replaceable></arg></arg>

      <arg choice="opt" rep="norepeat">-s<arg choice="req"
      rep="norepeat"><replaceable>cmd</replaceable></arg></arg>

      <arg choice="opt" rep="norepeat">-m<arg choice="req"
      rep="norepeat"><replaceable>cmd</replaceable></arg></arg>

      <arg choice="opt" rep="norepeat">-S</arg>

      <arg choice="opt" rep="norepeat">-h<arg choice="req"
      rep="norepeat"><replaceable>host</replaceable></arg></arg>

      <arg choice="opt" rep="norepeat">--<arg choice="req"
      rep="norepeat"><replaceable>backend-options</replaceable></arg></arg>

      <arg choice="req" rep="norepeat"><replaceable>command</replaceable></arg>

      <group choice="opt" rep="norepeat">
        <arg choice="req" rep="norepeat">all</arg>

        <arg choice="req" rep="repeat"><replaceable>resource<arg choice="opt"
        rep="norepeat">/volume&gt;</arg></replaceable></arg>
      </group>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><option>Drbdadm</option> is the high level tool of the DRBD program suite.
    <option>Drbdadm</option> is to <option>drbdsetup</option> and <option>drbdmeta</option> what
    <option>ifup</option>/<option>ifdown</option> is to <option>ifconfig</option>.
    <option>Drbdadm</option> reads its configuration file and performs the specified commands by
    calling the <option>drbdsetup</option> and/or the <option>drbdmeta</option> program.</para>

    <para><option>Drbdadm</option> can operate on whole resources or on individual volumes in a
    resource. The sub commands: <option>attach</option>, <option>detach</option>,
    <option>primary</option>, <option>secondary</option>, <option>invalidate</option>,
    <option>invalidate-remote</option>, <option>outdate</option>, <option>resize</option>,
    <option>verify</option>, <option>pause-sync</option>, <option>resume-sync</option>,
    <option>role</option>, <option>csytate</option>, <option>dstate</option>,
    <option>create-md</option>, <option>show-gi</option>, <option>get-gi</option>,
    <option>dump-md</option>, <option>wipe-md</option> work on whole resources and on
    individual volumes. </para>

    <para>Resource level only commands are: <option>connect</option>, <option>disconnect</option>,
    <option>up</option>, <option>down</option>, <option>wait-connect</option> and
    <option>dump</option>.</para>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <variablelist>
      <varlistentry>
        <term><option>-d</option>, <option>--dry-run</option></term>

        <listitem>
          <para>Just prints the calls of <option>drbdsetup</option> to stdout, but does not run
          the commands.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-c</option>, <option>--config-file</option>
        <replaceable>file</replaceable></term>

        <listitem>
          <para>Specifies the configuration file drbdadm will use. If this parameter is not
          specified, drbdadm will look for <option>/etc/drbd-84.conf</option>,
          <option>/etc/drbd-83.conf</option>, <option>/etc/drbd-08.conf</option> and
          <option>/etc/drbd.conf</option>.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-t</option>, <option>--config-to-test</option>
        <replaceable>file</replaceable></term>

        <listitem>
          <para>Specifies an additional configuration file drbdadm to check. This option is only
          allowed with the dump and the sh-nop commands.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-s</option>, <option>--drbdsetup</option>
        <replaceable>file</replaceable></term>

        <listitem>
          <para>Specifies the full path to the <option>drbdsetup</option> program. If this option
          is omitted, drbdadm will look for it beneath itself first, and then in the PATH.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-m</option>, <option>--drbdmeta</option>
        <replaceable>file</replaceable></term>

        <listitem>
          <para>Specifies the full path to the <option>drbdmeta</option> program. If this option
          is omitted, drbdadm will look for it beneath itself first, and then in the PATH.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-S</option>, <option>--stacked</option></term>

        <listitem>
          <para>Specifies that this command should be performed on a stacked resource.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>-P</option>, <option>--peer</option></term>

        <listitem>
          <para>Specifies to which peer node to connect. Only necessary if there are more than two
          host sections in the resource you are working on.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>--</option> <replaceable>backend-options</replaceable></term>

        <listitem>
          <para>All options following the doubly hyphen are considered
          <replaceable>backend-options</replaceable>. These are passed through to the backend
          command. I.e. to <option>drbdsetup</option>, <option>drbdmeta</option> or
          <option>drbd-proxy-ctl</option>.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Commands</title>

    <variablelist>
      <varlistentry>
        <term>attach</term>

        <listitem>
          <para>Attaches a local backing block device to the DRBD resource's device.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>detach</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>detach</secondary>
            </indexterm> Removes the backing storage device from a DRBD resource's device.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>connect</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>connect</secondary>
            </indexterm> Sets up the network configuration of the resource's device. If the peer
          device is already configured, the two DRBD devices will connect. If there are more than
          two host sections in the resource you need to use the <option>--peer</option> option to
          select the peer you want to connect to.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>disconnect</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>disconnect</secondary>
            </indexterm> Removes the network configuration from the resource. The device will then
          go into StandAlone state.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>syncer</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>syncer</secondary>
            </indexterm> Loads the resynchronization parameters into the device.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>up</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>up</secondary>
            </indexterm> Is a shortcut for attach and connect.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>down</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>down</secondary>
            </indexterm> Is a shortcut for disconnect and detach.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>primary</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>primary</secondary>
            </indexterm> Promote the resource's device into primary role. You need to do this
          before any access to the device, such as creating or mounting a file system.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>secondary</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>secondary</secondary>
            </indexterm> Brings the device back into secondary role. This is needed since in a
          connected DRBD device pair, only one of the two peers may have primary role (except if
          <option>allow-two-primaries</option> is explicitly set in the configuration
          file).</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>invalidate</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>invalidate</secondary>
            </indexterm> Forces DRBD to consider the data on the <emphasis>local</emphasis> backing
	  storage device as out-of-sync. Therefore DRBD will copy each
	  and every block from its peer, to bring the local storage
	  device back in sync.
	  To avoid races, you need an established replication link,
	  or be disconnected Secondary.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>invalidate-remote</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>invalidate-remote</secondary>
            </indexterm> This command is similar to the invalidate command, however, the
	  <emphasis>peer's</emphasis> backing storage is invalidated and hence rewritten
	  with the data of the local node.
	  To avoid races, you need an established replication link,
	  or be disconnected Primary.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>resize</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>resize</secondary>
            </indexterm> Causes DRBD to re-examine all sizing constraints, and resize the
          resource's device accordingly. For example, if you increased the size of your backing
          storage devices (on both nodes, of course), then DRBD will adopt the new size after you
          called this command on one of your nodes. Since new storage space must be synchronised
          this command only works if there is at least one primary node present.</para>
          <para>Note that all of the following options are <option>backend-options</option> (i.e., separated via "--").</para>

	  <para>The <option>--size</option> option can be used to online shrink the usable
	  size of a drbd device. It's the users responsibility to make sure that a file system
	  on the device is not truncated by that operation.
	  Example:
          <programlisting format="linespecific">
# drbdadm -- --size=10G resize r0</programlisting></para>


          <para>The <option>--assume-peer-has-space</option> allows you to resize a device which
          is currently not connected to the peer. Use with care, since if you do not resize the
          peer's disk as well, further connect attempts of the two will fail.</para>

	  <para>The <option>--assume-clean</option> allows you to resize an existing device and avoid
          syncing the new space. This is useful when adding addtional blank storage to your device.
          Example:
          <programlisting format="linespecific">
# drbdadm -- --assume-clean resize r0</programlisting>
          </para>
	  <para>The options <option>--al-stripes</option> and <option>--al-stripe-size-kB</option> may
	  be used to change the layout of the activity log online. In case of internal meta data
	  this may invovle shrinking the user visible size at the same time (unsing the
	  <option>--size</option>) or increasing the avalable space on the backing devices.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>check-resize</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>check-resize</secondary>
            </indexterm> Calls drbdmeta to eventually move internal meta data. If the backing
          device was resized, while DRBD was not running, meta data has to be moved to the end of
          the device, so that the next <option>attach</option> command can succeed.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>create-md</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>create-md</secondary>
            </indexterm> Initializes the meta data storage. This needs to be done before a DRBD
          resource can be taken online for the first time. In case of issues with that command
          have a look at <citerefentry>
              <refentrytitle>drbdmeta</refentrytitle>

              <manvolnum>8</manvolnum>
            </citerefentry></para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>get-gi</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>get-gi</secondary>
            </indexterm> Shows a short textual representation of the data generation
          identifiers.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>show-gi</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>show-gi</secondary>
            </indexterm> Prints a textual representation of the data generation identifiers
          including explanatory information.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>dump-md</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>dump-md</secondary>
            </indexterm> Dumps the whole contents of the meta data storage, including the stored
          bit-map and activity-log, in a textual representation.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>outdate</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>outdate</secondary>
            </indexterm> Sets the outdated flag in the meta data.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>adjust</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>adjust</secondary>
            </indexterm> Synchronizes the configuration of the device with your configuration
          file. You should always examine the output of the dry-run mode before actually executing
          this command.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>wait-connect</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>wait-connect</secondary>
            </indexterm> Waits until the device is connected to its peer device.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>role</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>role</secondary>
            </indexterm> Shows the current roles of the devices (local/peer). E.g.
          Primary/Secondary</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>state</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>state</secondary>
            </indexterm> Deprecated alias for "role", see above.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>cstate</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>cstate</secondary>
            </indexterm> Shows the current connection state of the devices.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>dump</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>dump</secondary>
            </indexterm> Just parse the configuration file and dump it to stdout. May be used to
          check the configuration file for syntactic correctness.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>outdate</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>outdate</secondary>
            </indexterm> Used to mark the node's data as outdated. Usually used by the peer's
          fence-peer handler.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>verify</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>verify</secondary>
            </indexterm> Starts online verify. During online verify, data on both nodes is
          compared for equality. See <filename moreinfo="none">/proc/drbd</filename> for online
          verify progress. If out-of-sync blocks are found, they are <emphasis>not</emphasis>
          resynchronized automatically. To do that, <command moreinfo="none">disconnect</command>
          and <command moreinfo="none">connect</command> the resource when verification has
          completed.</para>

          <para>See also the notes on data integrity on the drbd.conf manpage.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>pause-sync</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>pause-sync</secondary>
            </indexterm> Temporarily suspend an ongoing resynchronization by setting the local
          pause flag. Resync only progresses if neither the local nor the remote pause flag is
          set. It might be desirable to postpone DRBD's resynchronization until after any
          resynchronization of the backing storage's RAID setup.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>resume-sync</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>resume-sync</secondary>
            </indexterm> Unset the local sync pause flag.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>new-current-uuid</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>new-current-uuid</secondary>
            </indexterm> Generates a new currend UUID and rotates all other UUID values.</para>

          <para>This can be used to shorten the initial resync of a cluster. See the
          <option>drbdsetup</option> manpage for a more details.</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>dstate</term>

        <listitem>
          <para><indexterm significance="normal">
              <primary>drbdadm</primary>

              <secondary>dstate</secondary>
            </indexterm> Show the current state of the backing storage devices.
          (local/peer)</para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>hidden-commands</term>

        <listitem>
          <para>Shows all commands undocumented on purpose.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Version</title>

    <simpara>This document was revised for version 8.4.0 of the DRBD distribution.</simpara>
  </refsect1>

  <refsect1>
    <title>Author</title>

    <simpara>Written by Philipp Reisner <email>philipp.reisner@linbit.com</email> and Lars
    Ellenberg <email>lars.ellenberg@linbit.com</email></simpara>
  </refsect1>

  <refsect1>
    <title>Reporting Bugs</title>

    <simpara>Report bugs to <email>drbd-user@lists.linbit.com</email>.</simpara>
  </refsect1>

  <refsect1>
    <title>Copyright</title>

    <simpara>Copyright 2001-2011 LINBIT Information Technologies, Philipp Reisner, Lars Ellenberg.
    This is free software; see the source for copying conditions. There is NO warranty; not even
    for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.</simpara>
  </refsect1>

  <refsect1>
    <title>See Also</title>

    <para><citerefentry>
        <refentrytitle>drbd.conf</refentrytitle>

        <manvolnum>5</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>drbd</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>drbddisk</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>drbdsetup</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry>, <citerefentry>
        <refentrytitle>drbdmeta</refentrytitle>

        <manvolnum>8</manvolnum>
      </citerefentry> and the
      <ulink url="http://www.drbd.org/"><citetitle>DRBD project web site</citetitle></ulink></para>

  </refsect1>
</refentry>