<?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>20 Mar 2020</date>
    <productname>DRBD</productname>
    <productnumber>8.4.11</productnumber>
  </refentryinfo>
  <refmeta>
    <refentrytitle>drbdmeta</refentrytitle>
    <manvolnum>8</manvolnum>
    <refmiscinfo class="manual">System Administration</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname>drbdmeta</refname>
    <refpurpose>DRBD's meta data management tool
    <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>
      </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>      Drbdmeta is used to create, display and modify the contents of
      DRBD's meta data storage. Usually you do not want to use this
      command directly, but start it via the frontend
      <citerefentry><refentrytitle>drbdadm</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
    </para>
    <para>      This command only works if the DRBD resource is currently down,
      or at least detached from its backing storage. The first parameter
      is the device node associated to the resource. With the second
      parameter you can select the version of the meta data. Currently
      all major DRBD releases (0.6, 0.7 and 8) are supported.
    </para>
  </refsect1>
  <refsect1>
    <title>Options</title>
    <variablelist>
      <varlistentry>
        <term>--force</term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>--force</secondary></indexterm>
            All questions that get asked by drbdmeta are treated as if
	    the user answered 'yes'.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>--ignore-sanity-checks</term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>--ignore-sanity-checks</secondary></indexterm>
            Some sanity checks cause drbdmeta to terminate. E.g. if a file system image would get
	    destroyed by creating the meta data. By using that option you can force drbdmeta
	    to ignore these checks.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Commands</title>
    <variablelist>
      <varlistentry>
	<term>create-md
	  <option>--peer-max-bio-size <replaceable>val</replaceable></option>
	  <option>--al-stripes <replaceable>val</replaceable></option>
	  <option>--al-stripe-size-kB <replaceable>val</replaceable></option>
	</term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>create-md</secondary></indexterm>
          Create-md initializes the meta data storage. This needs to be
	  done before a DRBD resource can be taken online for the first
	  time. In case there is already a meta data signature of an
	  older format in place, drbdmeta will ask you if it should
	  convert the older format to the selected format.
	</para>
	<para>
	  If you will use the resource before it is connected to its peer
	  for the first time DRBD may perform better if you use the
	  <option>--peer-max-bio-size</option> option. For DRBD versions of
	  the peer use up to these values: &lt;8.3.7 -&gt; 4k, 8.3.8 -&gt; 32k, 8.3.9 -&gt; 128k, 8.4.0 -&gt; 1M.
	</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 64k</command>
	</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>get-gi</term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>get-gi</secondary></indexterm>
          Get-gi shows a short textual representation of the data generation
	  identifier. In version 0.6 and 0.7 these are generation counters,
	  while in version 8 it is a set of UUIDs.
	</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>show-gi</term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>show-gi</secondary></indexterm>
	  Show-gi 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>drbdmeta</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>drbdmeta</primary><secondary>outdate</secondary></indexterm>
          Sets the outdated flag in the meta data. This is used by the
	  peer node when it wants to become primary, but cannot
	  communicate with the DRBD stack on this host.
        </para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>dstate</term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>dstate</secondary></indexterm>
          Prints the state of the data on the  backing storage. The output
	  is always followed by '/DUnknown' since drbdmeta only looks
	  at the local meta data.
        </para>
        </listitem>
      </varlistentry>

      <varlistentry>
        <term>check-resize</term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>check-resize</secondary></indexterm>
          Examines the device size of a backing device, and it's last known device size,
	  recorded in a file /var/lib/drbd/drbd-minor-??.lkbd. In case the size of the
	  backing device changed, and the meta data can be found at the old position,
	  it moves the meta data to the right position at the end of the block device.
        </para>
        </listitem>
      </varlistentry>

    </variablelist>
  </refsect1>
  <refsect1>
    <title>Expert's commands</title>
    <para>      Drbdmeta allows you to modify the meta data as well. This is
      intentionally omitted for the command's usage output, since you
      should only use it if you really know what you are doing.
      By setting the generation identifiers to wrong values, you
      risk to overwrite your up-to-data data with an older version
      of your data.
    </para>
    <variablelist>
      <varlistentry>
        <term>set-gi <replaceable>gi</replaceable></term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>set-gi </secondary></indexterm>
          Set-gi allows you to set the generation identifier.
	  <replaceable>Gi</replaceable> needs to be a generation
	  counter for the 0.6 and 0.7 format, and a UUID set for 8.x.
	  Specify it in the same way as get-gi shows it.
	</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>restore-md <replaceable>dump_file</replaceable></term>
        <listitem>
          <para><indexterm significance="normal"><primary>drbdmeta</primary><secondary>restore-md </secondary></indexterm>
          Reads the <replaceable>dump_file</replaceable> and writes
	  it to the meta data.
	</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </refsect1>
  <refsect1>
    <title>Version</title>
    <simpara>This document was revised for version 8.3.2 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 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>
    </para>
  </refsect1>
</refentry>
