| <?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>--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> |
| 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> |
| |
| </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> |
