[DRBD-cvs] documentation by phil; * Forwarded some documentation for drbd-...
drbd-user@lists.linbit.com
drbd-user@lists.linbit.com
Mon, 9 Feb 2004 17:21:03 +0100 (CET)
DRBD CVS committal
Author : phil
Project : drbd
Module : documentation
Dir : drbd/documentation
Modified Files:
Tag: rel-0_7-branch
Makefile drbd.conf.sgml drbdsetup.sgml
Log Message:
* Forwarded some documentation for drbd-0.6.11
* Fixed a typo in the Makefile
===================================================================
RCS file: /var/lib/cvs/drbd/drbd/documentation/Makefile,v
retrieving revision 1.17.2.8
retrieving revision 1.17.2.9
diff -u -3 -r1.17.2.8 -r1.17.2.9
--- Makefile 3 Feb 2004 08:41:57 -0000 1.17.2.8
+++ Makefile 9 Feb 2004 16:20:58 -0000 1.17.2.9
@@ -94,7 +94,7 @@
cd HOWTO ; $(DB2HTML) DRBD-HOWTO.sgml ; cd ..
install:
- @ok=true; for f in $(MANGAOES) ; \
+ @ok=true; for f in $(MANPAGES) ; \
do [ -e $$f ] || { echo $$f missing ; ok=false; } ; \
done ; $$ok
@ set -e; for f in $(MANPAGES) ; do \
===================================================================
RCS file: /var/lib/cvs/drbd/drbd/documentation/drbd.conf.sgml,v
retrieving revision 1.9.2.1
retrieving revision 1.9.2.2
diff -u -3 -r1.9.2.1 -r1.9.2.2
--- drbd.conf.sgml 22 May 2003 11:48:14 -0000 1.9.2.1
+++ drbd.conf.sgml 9 Feb 2004 16:20:58 -0000 1.9.2.2
@@ -1,6 +1,6 @@
<!DOCTYPE RefEntry PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
<refentry>
-<docinfo><date>6 Apr 2003</date></docinfo>
+<docinfo><date>15 Apr 2001</date></docinfo>
<refmeta>
<refentrytitle>drbd.conf</refentrytitle>
@@ -9,22 +9,22 @@
<refnamediv>
<refname>drbd.conf</refname>
- <refpurpose>The configuration file for DRBD's devices</refpurpose>
+ <refpurpose>Configuration file for DRBD's devices</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para>
-The file <option>/etc/drbd.conf</option>, is read by
+The file <option>/etc/drbd.conf</option> is read by
<option>/etc/init.d/drbd</option> and
-<option>/etc/ha.d/resrouce.d/datadisk</option>
-which are included in the drbd distribution.
+<option>/etc/ha.d/resource.d/datadisk</option>
+which are included in the DRBD distribution.
</para>
<para>
The file format was designed as to allow to have
-a verbatim copy of the file on both nodes of the cluster,
-and in order to keep your configuration manageable you should also
-do so.
+a verbatim copy of the file on both nodes of the cluster.
+It is highly recommended to do so in order to keep your configuration
+manageable.
<example>
<title>A small drbd.conf file</title>
<programlisting>
@@ -48,7 +48,7 @@
}
</programlisting>
</example>
-In this example there is a singe DRBD resource (called drbd0) which uses
+In this example there is a single DRBD resource (called drbd0) which uses
protocol C for the connection between its devices. The application
of this resource is an ext2 file system, since the command to restart
it is <replaceable>fsck.ext2 -p -y</replaceable>.
@@ -59,14 +59,14 @@
The IP addresses are used to specify the networking interfaces to use.
</para>
<para>
-There may be multiple resource sections in a singe drbd.conf file.
+There may be multiple resource sections in a single drbd.conf file.
</para>
</refsect1>
<refsect1>
<title>File Format</title>
<para>
The file consists of sections and parameter lines.
-A section begins with a keyword, sometimes an additional name and an
+A section begins with a keyword, sometimes an additional name, and an
opening brace.
A section ends with a closing brace.
</para>
@@ -74,9 +74,9 @@
A parameter line starts with the identifier of the parameter followed
by an equal sign (<quote>=</quote>). Every subsequent character on
that line is considered
-as part of the parameters value. There must not be a single white space
-between the identifier and the equal sing. A special case are Boolean
-parameters which only consists of the identifier.
+as part of the parameters value. White space surrounding the equal
+sign is ignored. A special case are Boolean
+parameters which only consist of the identifier.
</para>
<para>
Comment lines may be placed into the configuration file and must
@@ -86,15 +86,25 @@
<title>Sections</title>
<variablelist>
<varlistentry>
+ <term><option>global</option></term>
+ <listitem><para>
+ Configures some global parameters. Currently only
+ minor_count=number and disable_io_hints are allowed
+ here. You may only have one global section, preferably
+ as the first section.
+ </para>
+ </listitem>
+</varlistentry>
+ <varlistentry>
<term><option>resource <replaceable>name</replaceable></option></term>
<listitem><para>
Configures a DRBD resource.
Each resource section needs to have two host sections
(keyword <option>on</option>) and may have
a <option>net</option> and a <option>disk</option> section.
- Required parameter in this section: <option>protocol</option>,
- <option>fsckcmd</option>. Optinal parameters are <option>inittimeout
- </option>, <option>skip-wait</option> and
+ Required parameters in this section: <option>protocol</option>,
+ <option>fsckcmd</option>. Optional parameters are <option>inittimeout
+ </option>, <option>skip-wait</option>, <option>load-only</option>, and
<option>incon-degr-cmd</option>.
</para>
</listitem>
@@ -130,10 +140,10 @@
of this section's parameters.
Allowed parameters: <option>sync-rate</option>,
<option>sync-max</option>, <option>sync-min</option>,
- <option>sync-nice</option>, <option>skip-sync</option>,
+ <option>sync-nice</option>, <option>sync-group</option>, <option>skip-sync</option>,
<option>connect-int</option>, <option>ping-int</option>,
<option>timeout</option>, <option>tl-size</option>,
- <option>sndbuf-size</option>.
+ <option>sndbuf-size</option>, <option>ko-count</option>.
</para>
</listitem>
</varlistentry>
@@ -165,20 +175,38 @@
<varlistentry>
<term><option>inittimeout=<replaceable>value</replaceable></option></term>
<listitem><para>
- If the other node does not show up within the specified time, this
- node will start the resource in degraded mode.</para>
- <para>Only use this option if availabiliy is more important to you then
- the consitency of your data.
+ If <replaceable>value</replaceable> is positive, and the other node does
+ not show up within the specified time (seconds), this node will start the
+ resource in degraded mode, read: forces primary status on this node.</para>
+ <para>Only use this option if availability is more important to you than
+ the consistency of your data.</para>
+ <para>If <replaceable>value</replaceable> is negative, and the other node
+ does not show up within the specified time (seconds), this node stays in
+ WFConnection:Secondary/Unknown state, and just lets the boot process
+ continue. Use this if you expect a reboot of the remaining node of a
+ degraded cluster, and you think your clustermanager is able to handle this
+ better.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><option>skip-wait</option></term>
<listitem><para>
- If you want startup of drbd to proceed without waiting for
+ If you want startup of DRBD to proceed without waiting for
synchronisation to finish, you can set this option. WARNING:
- only do this if whatever software you're using to manage drbd can
- correctly handle a syncing drbd device (no failover possible).
+ only do this if whatever software you're using to manage DRBD can
+ correctly handle a syncing DRBD device (no failover possible), or a cluster in
+ degraded mode.
+ </para>
+ </listitem>
+</varlistentry>
+ <varlistentry>
+ <term><option>load-only</option></term>
+ <listitem><para>
+ If you want the resource script to load the
+ configuration into the module ONLY, use this.
+ It will not even wait for connection of the devices.
+ WARNING: see above.
</para>
</listitem>
</varlistentry>
@@ -188,7 +216,7 @@
In case a node starts up in degraded mode (inittimeout is set) and
its local replica of the data is inconsistent it executes the
<replaceable>command</replaceable>. If the command exits without
- error, datadisk expects the drbd device to be in primary state.
+ error, datadisk expects the DRBD device to be in primary state.
</para>
</listitem>
</varlistentry>
@@ -241,13 +269,18 @@
</refsect2>
</refsect1>
<refsect1>
+<title>Version</title>
+<simpara>This document is correct for version 0.6.11 of the DRBD distribution.
+</simpara>
+</refsect1>
+<refsect1>
<title>Author</title>
<simpara>Written by Philipp Reisner <email>philipp.reisner@gmx.at</email>.
</simpara>
</refsect1>
<refsect1>
<title>Reporting Bugs</title>
-<simpara>Report bugs to <email>drbd-devel@lists.sourceforge.net</email>.
+<simpara>Report bugs to <email>drbd-user@lists.linbit.com</email>.
</simpara>
</refsect1>
<refsect1>
@@ -255,7 +288,7 @@
<simpara>
Copyright (c) 2001 Philipp Reisner. This is free software;
see the source for copying conditions. There is NO warranty;
-not even for MERCHANTABILIT or FITNESS FOR A PARTICULAR PURPOSE.
+not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
</simpara>
</refsect1>
<refsect1>
===================================================================
RCS file: /var/lib/cvs/drbd/drbd/documentation/drbdsetup.sgml,v
retrieving revision 1.9.2.1
retrieving revision 1.9.2.2
diff -u -3 -r1.9.2.1 -r1.9.2.2
--- drbdsetup.sgml 22 May 2003 11:48:14 -0000 1.9.2.1
+++ drbdsetup.sgml 9 Feb 2004 16:20:58 -0000 1.9.2.2
@@ -36,8 +36,11 @@
<arg>-s<arg choice=req><replaceable>size</replaceable></arg></arg>
<arg>-c<arg choice=req><replaceable>time</replaceable></arg></arg>
<arg>-i<arg choice=req><replaceable>time</replaceable></arg></arg>
+ <arg>-t<arg choice=req><replaceable>val</replaceable></arg></arg>
<arg>-k</arg>
+ <arg>-g<arg choice=req><replaceable>group</replaceable></arg></arg>
<arg>-S<arg choice=req><replaceable>size</replaceable></arg></arg>
+ <arg>-K<arg choice=req><replaceable>count</replaceable></arg></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>drbdsetup</command>
@@ -102,18 +105,18 @@
<refsect1>
<title>Description</title>
<para>
-drbdsetup is used to associate drbd devices with their lower
-level block devices, to set up drbd device pairs to mirror their
-lower level block devices and to inspect the configuration of
-running drbd devices.
+drbdsetup is used to associate DRBD devices with their lower
+level block devices, to set up DRBD device pairs to mirror their
+lower level block devices, and to inspect the configuration of
+running DRBD devices.
</para>
</refsect1>
<refsect1>
<title>Note</title>
<para>
-drbdsetup is a low level tool of the drbd program suite. It is
-used by the drbd, datadisk and drbdc scripts to communicate with
+drbdsetup is a low level tool of the DRBD program suite. It is
+used by the datadisk and drbd scripts to communicate with
the device driver.
</para>
</refsect1>
@@ -121,9 +124,9 @@
<refsect1>
<title>Commands</title>
<para>
-Each drbd sub-command might require arguments and bring its own
+Each drbdsetup sub-command might require arguments and bring its own
set of options. All values have default units which might be overruled
-by K, M or G. These units are defined in the usual way (eg. K = 2^10).
+by K, M or G. These units are defined in the usual way (e.g. K = 2^10 = 1024).
</para>
<refsect2>
@@ -146,8 +149,8 @@
<option>--disk-size <replaceable>size</replaceable></option></term>
<listitem><para>
If you need to use the device before connecting, use this option
-to pass the <replaceable>size</replaceable> of the drbd device to
-the driver. Default unit is KB.
+to pass the <replaceable>size</replaceable> of the DRBD device to
+the driver. Default unit is KB (1 KB = 1024 bytes).
</para></listitem>
</varlistentry>
<varlistentry>
@@ -155,11 +158,11 @@
<option>--do-panic</option></term>
<listitem><para>
If the driver of the <replaceable>lower_device</replaceable> reports
-an error to drbd, drbd passes this error on to the upper
+an error to DRBD, DRBD passes this error on to the upper
layers of the operating
system by default. With the <option>-p</option> or
<option>--do-panic</option> you can request that
-drbd triggers a kernel panic instead.
+DRBD triggers a kernel panic instead.
</para></listitem>
</varlistentry>
</variablelist>
@@ -171,25 +174,31 @@
<replaceable>local_addr:port</replaceable> for incoming connections
and to try to connect to <replaceable>remote_addr:port</replaceable>.
If <replaceable>port</replaceable> is omitted, 7788 is used as default.
-On the tcp/ip link the specified <replaceable>protocol</replaceable>
-is used. Valid protocol spezifiers are A, B and C.
</para>
+<para>On the TCP/IP link the specified <replaceable>protocol</replaceable>
+is used. Valid protocol specifiers are A, B, and C.</para>
+<para>Protocol A: write IO is reported as completed, if it has reached
+local disk and local tcp send buffer.</para>
+<para>Protocol B: write IO is reported as completed, if it has reached
+local disk and remote buffer cache.</para>
+<para>Protocol C: write IO is reported as completed, if it has
+reached both local and remote disk.</para>
<variablelist>
<varlistentry>
<term><option>-r</option>,
<option>--sync-rate <replaceable>rate</replaceable></option>,
<option>--sync-max <replaceable>rate</replaceable></option></term>
<listitem><para>
-To ensure smooth operation of the application on top of drbd, it is
+To ensure smooth operation of the application on top of DRBD, it is
possible to limit the bandwidth which may be used by background
-synchronisations. It is well possible that this limit is not fully
+synchronizations. It is well possible that this limit is not fully
utilized while the server is otherwise loaded, because synchronization
runs at a very low priority by default (nicelevel +19; but see below).
-The default is 250 KB/sec, the default unit is KB.
+The default is 250 KB/sec, the default unit is KB/sec.
</para></listitem>
</varlistentry>
<varlistentry>
- <term>
+ <term><option>-n</option>,
<option>--sync-min <replaceable>rate</replaceable></option></term>
<listitem><para>
It is possible to guarantee a minimum throughput for the synchronization.
@@ -197,36 +206,45 @@
sync-daemon reprioritizes itself to the highest possible priority
(nicelevel -20; not RealTime class). As soon as speed is back above the
watermark, it flips back to the normal priority, see above. The default
-is 200 KB/sec, the default unit is KB.
+is 200 KB/sec, the default unit is KB/sec.
</para></listitem>
</varlistentry>
<varlistentry>
- <term>
+ <term><option>-P</option>,
<option>--sync-nice <replaceable>nice-level</replaceable></option></term>
<listitem><para>
This sets the normal nice-level for background synchronization.
Valid values are [-20 to 19], inclusive. Higher number means lower
-priority. This is used for the sync-deamon if the current
+priority. This is used for the sync-daemon if the current
synchronization throughput is between the sync-min and sync-max values,
-see above. The default is 19, i.e. lowest priority.
+see above. The default is 19, i.e. lowest priority.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-k</option>,
<option>--skip-sync </option></term>
<listitem><para>
-This option supresses the automatic start of the resynchronisation
+This option suppresses the automatic start of the resynchronization
process, which
-is triggered as soon as two drbd devices are connected.
+is triggered as soon as two DRBD devices are connected.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><option>-g</option>,
+ <option>--sync-group <replaceable>group</replaceable></option></term>
+ <listitem><para>
+Resynchronization of all devices in one group runs parallel. Groups are
+serialized in ascending order. You should avoid that devices which
+lower devices share one and the same physical disk sync in parallel. The default
+group is 0. I.e. per default all devices sync parallel.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-c</option>,
<option>--connect-int <replaceable>time</replaceable></option></term>
<listitem><para>
-In case it is not possible to connect to the remote drbd device immediately,
-drbd
-keeps on trying to connect. With this option you can set the time
+In case it is not possible to connect to the remote DRBD device immediately,
+DRBD keeps on trying to connect. With this option you can set the time
between two tries. The default value is 10 seconds, the unit is 1 second.
</para></listitem>
</varlistentry>
@@ -234,19 +252,20 @@
<term><option>-i</option>,
<option>--ping-int <replaceable>time</replaceable></option></term>
<listitem><para>
-If the tcp/ip connection linking a drbd device pair is idle for more than
-<replaceable>time</replaceable> seconds, drbd will generate a keep-alive
-packet to check if its partner is still alive. The default is 10 seconds.
+If the TCP/IP connection linking a DRBD device pair is idle for more than
+<replaceable>time</replaceable> seconds, DRBD will generate a keep-alive
+packet to check if its partner is still alive. The default is 10 seconds,
+the unit is 1 second.
</para></listitem>
</varlistentry>
<varlistentry>
<term><option>-t</option>,
<option>--timeout <replaceable>val</replaceable></option></term>
<listitem><para>
-If the partner node failes to send an expected response packet within
+If the partner node fails to send an expected response packet within
<replaceable>val</replaceable> 10<superscript>ths</superscript>
of a second, the partner node
-is considered dead and therefore the tcp/ip connection is abandoned.
+is considered dead and therefore the TCP/IP connection is abandoned.
The default value is 60 = 6 seconds.
</para></listitem>
</varlistentry>
@@ -267,7 +286,7 @@
<option>--sndbuf-size <replaceable>size</replaceable></option></term>
<listitem>
<para>
-The driver uses a socket send buffer to store packets sent to the secondary
+The socket send buffer is used to store packets sent to the secondary
node, which are not yet acknowledged (from a network point of view) by the
secondary node. When using protocol A, it might be necessary to increase
the size of this data structure in order to increase asynchronism between
@@ -276,12 +295,24 @@
The default <replaceable>size</replaceable> is 128 KB. Default unit is KB.
</para></listitem>
</varlistentry>
+ <varlistentry>
+ <term><option>-K</option>,
+ <option>--ko-count <replaceable>count</replaceable></option></term>
+ <listitem>
+<para>
+In case the secondary node fails to complete a single write request
+for <replaceable>count</replaceable> times the
+<replaceable>timeout</replaceable>, it is expelled from the cluster.
+(I.e. the primary node goes into StandAlone mode.)
+The default is 0, which disables this feature.
+ </para></listitem>
+ </varlistentry>
</variablelist>
</refsect2>
<refsect2>
<title>syncer</title>
<para>
-Changes the synchronization deamon parameters of
+Changes the synchronization daemon parameters of
<replaceable>device</replaceable> at runtime.
Not mentioned parameters will not be changed.
</para>
@@ -322,7 +353,7 @@
the device in secondary state.
</para>
<para>
-It is not possible to set both devices of a connected drbd device pair to
+It is not possible to set both devices of a connected DRBD device pair to
primary state.
</para>
<variablelist>
@@ -331,7 +362,7 @@
<option>--human</option></term>
<listitem><para>
Indicates that this state change was issued by an administrator and has
-at cluster restart time precedence over decissions made by other parties.
+at cluster restart time precedence over decisions made by other parties.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -340,7 +371,7 @@
<listitem><para>
Indicates that this state change was caused because a node did not showed
up on cluster startup (The cluster started in degraded mode). At cluster
-restart this this has precedence over decissions made by the cluster manager.
+restart this has precedence over decisions made by the cluster manager.
</para></listitem>
</varlistentry>
<varlistentry>
@@ -362,7 +393,7 @@
the device open for write access.
</para>
<para>
-It is however, possible that both devices of a connected drbd device
+It is however, possible that both devices of a connected DRBD device
pair are in secondary state.
</para>
</refsect2>
@@ -371,14 +402,14 @@
<para>
Tries to set the partner of <replaceable>device</replaceable> into secondary
state. This command will return successfully as long as it is possible
-to communicate with the partner, Its return value does not indicate if the
+to communicate with the partner. Its return value does not indicate if the
partner device could change its state.
</para>
</refsect2>
<refsect2>
<title>replicate</title>
<para>
-This forces the pair of connected drbd devices into SyncAll state, which
+This forces the pair of connected DRBD devices into SyncAll state, which
means that all data blocks of the device in primary state are copied to
the device in secondary state.
Since synchronization runs below the filesystem layer, services on the
@@ -403,7 +434,7 @@
<listitem><para>
This command will fail if the <replaceable>device</replaceable> can not
communicate with its partner for <replaceable>connect_timeout</replaceable>
-seconds. The default value is 0 which disables the timeout machanism.
+seconds. The default value is 0 which disables the timeout mechanism.
</para></listitem>
</varlistentry>
</variablelist>
@@ -412,7 +443,7 @@
<title>wait_sync</title>
<para>
Returns as soon as the <replaceable>device</replaceable> leaves any
-synchronisation state and returns into connected state.
+synchronization state and returns into connected state.
</para>
<variablelist>
<varlistentry>
@@ -433,7 +464,7 @@
Removes the information set by the <option>net</option> command
from the <replaceable>device</replaceable>. This means
that the <replaceable>device</replaceable> goes into unconnected
-states and that it will no longer listen for incomming connections.
+state and that it will no longer listen for incoming connections.
</para>
</refsect2>
<refsect2>
@@ -462,12 +493,12 @@
(on tc1) and
<replaceable>192.168.37.3</replaceable> (on tc2).
We want to turn /dev/hda6 into a virtually shared disk.</para>
-<para>On tc2 we need:</para>
+<para>On tc1 we need:</para>
<screen>
$ drbdsetup /dev/nb0 disk /dev/hda6
$ drbdsetup /dev/nb0 net 192.168.37.2 192.168.37.3 B
</screen>
-<para>On tc1 we need:</para>
+<para>On tc2 we need:</para>
<screen>
$ drbdsetup /dev/nb0 disk /dev/hda6
$ drbdsetup /dev/nb0 net 192.168.37.3 192.168.37.2 B
@@ -479,8 +510,8 @@
1: cs:WFConnection st:Secondary/Unknown ns:0 nr:0 dw:0 dr:0 of:0
</computeroutput>
</screen>
-<para>From /prod/drbd we can see, that our device pair is connected, and
-that the device is ready for use on tc1.</para>
+<para>From /proc/drbd we can see, that our device pair is connected, and
+that the device is ready for use on tc2.</para>
<para>We can now run our application on top of it:</para>
<screen>
$ mkfs -b 4096 /dev/nb0
@@ -509,18 +540,25 @@
$ drbdsetup /dev/nb0 net tc2 tc1 B
$ #drbdsetup /dev/nb0 replicate
</screen>
-<para>With release 0.5.8 drbd's meta-data management can not detect changing
+<para>With release 0.6.x DRBD's meta-data management still can not detect changing
mirroring partners. Therefore you might have to issue
the replicate commands as outlined in the example.</para>
<para>Since the snapshot was taken without bringing the on disk file
-system into a consisten state we need theese commands on tc3:</para>
+system into a consistent state we need these commands on tc3:</para>
<screen>
$ drbdsetup /dev/nb0 down
$ fsck /dev/hda6
-$ mount /dev/hda6 /some/mountpint
+$ mount /dev/hda6 /some/mountpoint
</screen>
</example>
</refsect1>
+
+<refsect1>
+<title>Version</title>
+<simpara>This document is correct for version 0.6.11 of the DRBD distribution.
+</simpara>
+</refsect1>
+
<refsect1>
<title>Author</title>
<simpara>Written by Philipp Reisner <email>philipp.reisner@gmx.at</email>.
@@ -528,7 +566,7 @@
</refsect1>
<refsect1>
<title>Reporting Bugs</title>
-<simpara>Report bugs to <email>drbd-devel@lists.sourceforge.net</email>.
+<simpara>Report bugs to <email>drbd-user@lists.linbit.com</email>.
</simpara>
</refsect1>
<refsect1>
@@ -536,7 +574,7 @@
<simpara>
Copyright (c) 2001 Philipp Reisner. This is free software;
see the source for copying conditions. There is NO warranty;
-not even for MERCHANTABILIT or FITNESS FOR A PARTICULAR PURPOSE.
+not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
</simpara>
</refsect1>
<refsect1>