<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<refentry id="re-drbdmeta">
  <refentryinfo>
    <date>6 December 2012</date>
    <productname>DRBD</productname>
    <productnumber>9.0.0</productnumber>
  </refentryinfo>
  <refmeta>
    <refentrytitle>drbdmeta</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class="manual">System Administration</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>drbdmeta</refname>
    <refpurpose>Manipulate the DRBD on-disk metadata<indexterm significance="normal">
      <primary>drbdmeta</primary>
    </indexterm>
    </refpurpose>
  </refnamediv>
  <refsynopsisdiv>
    <cmdsynopsis sepchar=" ">
      <command moreinfo="none">drbdmeta</command>
      <arg choice="opt" rep="norepeat">--force</arg>
      <arg choice="opt" rep="norepeat">--ignore-sanity-checks</arg>
      <arg choice="req" rep="norepeat">
        <replaceable>device</replaceable>
      </arg>
      <group choice="req" rep="norepeat">
        <arg choice="plain" rep="norepeat">v06 <replaceable>minor</replaceable></arg>
        <arg choice="plain" rep="norepeat">v07 <replaceable>meta_dev index</replaceable></arg>
        <arg choice="plain" rep="norepeat">v08 <replaceable>meta_dev index</replaceable></arg>
        <arg choice="plain" rep="norepeat">v09 <replaceable>meta_dev index</replaceable></arg>
      </group>
      <arg choice="req" rep="norepeat">
        <replaceable>command</replaceable>
      </arg>
      <arg choice="opt" rep="repeat">
        <replaceable>cmd args</replaceable>
      </arg>
    </cmdsynopsis>
  </refsynopsisdiv>
  <refsect1>
    <title>Description</title>
    <para>The <option>drbdmeta</option> utility is used for creating,
      displaying, and modifying DRBD's on-disk metadata.  Users usually
      interact with the <option>drbdadm</option> utility, which provides a more
      high-level interface to DRBD than <option>drbdmeta</option>.  (See
      <option>drbdadm</option>'s <option>--dry-run</option> option to see how
      <option>drbdadm</option> uses <option>drbdmeta</option>.)</para>

    <para>This utility can only be used on devices which are not currently in
      use by the kernel.</para>

    <para>The first argument (<replaceable>device</replaceable>) specifies the
      drbd device associated with a volume, or <quote>-</quote> if no device is
      associated with that volume.  If the drbd device is specified, the
      <option>drbdmeta</option> utility makes sure that the drbd device does
      not currently have a volume attached to prevent meta-data of an active
      volume from being destroyed.</para>

    <para>The second argument specifies the
      metadata version to use (v06, v07, v08, v09).  In most metadata versions,
      the third argument (<replaceable>meta_dev</replaceable>) specifies the
      device which contains the metadata; this argument can be the same as
      <replaceable>device</replaceable>.  The fourth argument
      (<replaceable>index</replaceable>) can be one of the keywords
      <option>internal</option> (for internal metadata),
      <option>flex-internal</option> (in v07 for variable-sized metadata; v07
      otherwise defaults to fixed-size internal metadata),
      <option>flex-external</option> (for variable-sized external metadata), or
      a numeric matadata index (for fixed-size external metadata).  See the
      <option>meta-disk</option> parameter in <citerefentry>
	<refentrytitle>drbd.conf</refentrytitle> <manvolnum>5</manvolnum>
        </citerefentry>.</para>
  </refsect1>
  <refsect1>
    <title>Options</title>
    <variablelist>
      <varlistentry>
        <term>--force</term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>--force</secondary></indexterm>
	    Assume yes as the answer to all questions drbdmeta would ask.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>--ignore-sanity-checks</term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>--ignore-sanity-checks</secondary></indexterm>
	    Normally, <option>drbdmeta</option> performs some sanity checks
	    before writing to the metadata device: for example, if the device
	    appears to contain a file system, it refuses to destroy the file
	    system by writing into it.  Use this option to ignore these
	    checks.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Commands</title>
    <variablelist>
      <varlistentry>
	<term><option>create-md</option>
	  <arg choice="opt" rep="norepeat"><option>--peer-max-bio-size=</option><replaceable>val</replaceable></arg> (metadata versions v06, v07, and v08)</term>
	<term><option>create-md</option>
          <arg choice="req" rep="norepeat">number-of-bitmap-slots</arg>
	  <arg choice="opt" rep="norepeat"><option>--peer-max-bio-size=</option><replaceable>val</replaceable></arg>
	  <arg choice="opt" rep="norepeat"><option>--initialize-bitmap-mode=</option><replaceable>{automatic|zeroout|pwrite|skip}</replaceable></arg>
	  <arg choice="opt" rep="norepeat"><option>--al-stripes=</option><replaceable>val</replaceable></arg>
	  <arg choice="opt" rep="norepeat"><option>--al-stripe-size-kB=</option><replaceable>val</replaceable></arg> (metadata version v09)</term>
        <listitem>
	  <para><indexterm
	      significance="normal"><primary>drbdmeta</primary><secondary>create-md</secondary></indexterm>
	    Initialize the metadata. This is necessary before a DRBD resource
	    can be attached.  If <option>drbdmeta</option> finds an older
	    version of DRBD metadata on the device, it asks if the format
	    should be converted.</para>

	  <para>When <option>drbdadm</option> calls <option>drbdmeta</option>'s
	    <option>create-md</option> command for a device, it sets the
	    <replaceable>number-of-bitmap-slots</replaceable> argument to the
	    number of peers in the resource.  To reserve additional bitmap
	    slots (which allows to add more peers in the future), call
	    <option>drbdmeta</option> directly instead.</para>

	  <para>When a device is used before being connected to its peers the
	    first time, DRBD assumes that peers can only handle 4 KiB requests
	    by default.  The <option>--peer-max-bio-size</option> option allows
	    to set more optimistic values; use this if the versions of DRBD
	    that this device will connect to are known.  DRBD supports a
	    maximum bio size of 32 KiB since version 8.3.8, of 128 KiB since
	    version 8.3.9, and of 1 MiB since version 8.4.0.</para>
	  <para>By default, we explicitly initialize the bitmap area to all zero.
	    With <option>--initialize-bitmap-mode</option> you can chose to
	    only try the fast method (<option>zeroout</option>, try ioctl
	    BLKZEROOUT only), only use explicit <option>pwrite</option> calls,
	    or <option>skip</option> this bitmap initialization phase
	    completely.  If you intend to do an initial full sync anyways, you
	    can use <option>skip</option> to leave the bitmap initialization to
	    the kernel. This can make a noticable difference when initializing
	    huge volumes. Default is <option>automatic</option>, which is
	    zeroout with an implicit fallback to pwrite.
	    </para>
	  <para>
	    If you want to use more than 6433 activity log extents, or live on
	    top of a spriped RAID, you may specify the number of stripes
	    (<option>--al-stripes</option>, default 1), and the stripe size
	    (<option>--al-stripe-size-kB</option>, default 32).
	    To just use a larger linear on-disk ring-buffer, leave
	    the number of stripes at 1, and increase the size only:
	    <?linebreak?>
	    <command>drbdmeta 0 v08 /dev/vg23/lv42 internal create-md --al-stripe-size 1M</command>
	  </para>
	  <para>
	    To avoid a single "spindle" from becoming a bottleneck,
	    increase the number of stripes, to achieve an interleaved layout
	    of the on-disk activity-log transactions.
	    What you give as "stripe-size" should be what is a.k.a. "chunk size"
	    or "granularity" or "strip unit": the minimum skip to the next
	    "spindle".
	    <?linebreak?>
	    <command>drbdmeta 0 v08 /dev/vg23/lv42 internal create-md --al-stripes 7 --al-stripe-size 64</command>
	  </para>
        </listitem>
      </varlistentry>
      <varlistentry>
	<term><option>get-gi</option>
	  <arg rep="norepeat"><option>--node-id=</option><replaceable>id</replaceable></arg>
        </term>
        <listitem>
	  <para><indexterm
	      significance="normal"><primary>drbdmeta</primary><secondary>get-gi</secondary></indexterm>
	    Show the data generation identifiers for a device on a particular
	    connection.  DRBD version 9.0.0 and beyond support multiple peers;
	    use the <replaceable>node-id</replaceable> option to define which
	    peer's data generation identifiers to show.
	</para>
        </listitem>
      </varlistentry>
      <varlistentry>
	<term><option>show-gi</option>
	  <arg rep="norepeat"><option>--node-id=</option><replaceable>id</replaceable></arg>
        </term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>show-gi</secondary></indexterm>
	    Similar to <option>get-gi</option>, but with explanatory information.
        </para>
        </listitem>
      </varlistentry>
      <varlistentry>
	<term><option>dump-md</option></term>
        <listitem>
	  <para><indexterm
	      significance="normal"><primary>drbdmeta</primary><secondary>dump-md</secondary></indexterm>
	    Dump the metadata of a device in text form, including the bitmap
	    and activity log.
        </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>outdate</option></term>
        <listitem>
	  <para>
	    Mark the data on a lower-level device as outdated. See
	    <citerefentry> <refentrytitle>drbdsetup</refentrytitle>
	      <manvolnum>8</manvolnum> </citerefentry> for details.
        </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>dstate</option></term>
        <listitem>
	  <para>
	    Show the current disk state of a lower-level device.
	  </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>check-resize</option></term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>check-resize</secondary></indexterm>
          Examine the device size of a lower-level device and its last known device size
	  (saved in <option>/var/lib/drbd/drbd-minor-<replaceable>minor</replaceable>.lkbd</option>
	  by <option>drbdsetup check-resize</option>).  For internal metadata,
	  if the size of the lower-level device has changed and the metadata
	  can be found at the previous position, move the metadata to the new
	  position at the end of the block device.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term><option>apply-al</option></term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>apply-al</secondary></indexterm>
	  Apply the activity log of the specified device.  This is necessary
	  before the device can be attached by the kernel again.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>
          <option>repair-md</option>
          <arg rep="norepeat"><option>--tentative</option></arg>
        </term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>repair-md</secondary></indexterm>
            Repair known problems in metadata.  Only problems that can be
            automatically fixed in a safe manner will be repaired.  When
            <option>--tentative</option> is set, the metadata will only be
            checked, it will not be changed.
          </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>
  <refsect1>
    <title>Expert commands</title>
    <para>The <option>drbdmeta</option> utility can be used to fine tune
      metdata.  Please note that this can lead to destroyed metadata or even
      silent data corruption; use with great care only.
    </para>
    <variablelist>
      <varlistentry>
        <term><option>set-gi</option> <replaceable>gi</replaceable>
	  <arg rep="norepeat"><option>--node-id=</option><replaceable>id</replaceable></arg>
        </term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>set-gi </secondary></indexterm>
	  Set the generation identifiers.  The <replaceable>gi</replaceable>
	  argument is a generation counter for the v06 and v07 formats, and a
	  set of UUIDs for v08 and beyond.  Accepts the same syntax as in the
	  <option>get-gi</option> output.  DRBD version 9.0.0 and beyond
	  support multiple peers; use the <replaceable>--node-id</replaceable>
	  option to define which peer's data generation identifiers to set.
          <!-- FIXME: only the bitmap value taken? or current overwritten, too? -->
	</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term><option>restore-md</option> <replaceable>dump_file</replaceable></term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>restore-md </secondary></indexterm>
	    Replace the metadata on the device with the contents of
	    <replaceable>dump_file</replaceable>.  The dump file format is
	    defined by the output of the <option>dump-md</option> command.
	</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Version</title>
    <simpara>This document was revised for version 9.0.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-2008,2012 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>drbdadm</refentrytitle>
        <manvolnum>8</manvolnum>
      </citerefentry>
      <citerefentry>
        <refentrytitle>drbd.conf</refentrytitle>
        <manvolnum>5</manvolnum>
      </citerefentry>
    </para>
  </refsect1>
</refentry>
