Improve the man pages

This patch does some small fixes to the man pages and adds descriptions for a few missing options. Reviewed-by: ultrotter

Improve the man pages
This patch does some small fixes to the man pages and adds descriptions for a few missing options. Reviewed-by: ultrotter
f69dab6d · Iustin Pop · 2395c322 · f69dab6d · f69dab6d · f69dab6d
Commit f69dab6d authored 17 years ago by Iustin Pop
--- a/man/ganeti-watcher.sgml
+++ b/man/ganeti-watcher.sgml
@@ -50,9 +50,15 @@
    </para>
    <para>
-      Its function is to try to keep running all instances which are
+      Its primary function is to try to keep running all instances
-      marked as <emphasis>up</emphasis> in the configuration file, by
+      which are marked as <emphasis>up</emphasis> in the configuration
-      trying to start them a limited number of times.
+      file, by trying to start them a limited number of times.
+    </para>
+    <para>
+      Its other function is to <quote>repair</quote> DRBD links by
+      reactivating the block devices of instances which have
+      secondaries on nodes that have been rebooted.
    </para>
    <para>In order to prevent piling up commands, all the
@@ -72,20 +78,6 @@
  </refsect1>
-  <refsect1>
-    <title>KNOWN BUGS</title>
-    <para>
-      Due to the way we initialize DRBD peers, restarting a secondary
-      node for an instance will cause the DRBD endpoints on that node
-      to disappear, thus all instances which have that node as a
-      secondary will lose redundancy. The watcher does not detect this
-      situation. The workaround is to manually run
-      <command>gnt-instance activate-disks</command> for all the
-      affected instances.
-    </para>
-  </refsect1>
  &footer;
 </refentry>

--- a/man/ganeti.sgml
+++ b/man/ganeti.sgml
@@ -51,7 +51,7 @@
    <para>
      The ganeti software manages physical nodes and virtual instances
      of a cluster based on a virtualization software. The current
-      version (1.2) supports Xen 3.0.
+      version (1.2) supports Xen 3.0 (also tested with 3.1).
    </para>
  </refsect1>

--- a/man/gnt-backup.sgml
+++ b/man/gnt-backup.sgml
@@ -66,9 +66,10 @@
      </cmdsynopsis>
      <para>
-        Exports an instance to the target node. All the instance
+        Exports an instance to the target node. All the instance data
-        data and its configuration will be exported under the
+        and its configuration will be exported under the
-        /srv/ganeti/exports/instance directory on the target node.
+        /srv/ganeti/exports/<replaceable>instance</replaceable>
+        directory on the target node.
      </para>
      <para>
@@ -102,8 +103,10 @@
            <arg>plain</arg>
            <arg>local_raid1</arg>
            <arg>remote_raid1</arg>
+            <arg>drbd</arg>
          </group>
        </arg>
+        <sbr>
        <arg choice="req">--src-node=<replaceable>source-node</replaceable></arg>
        <arg choice="req">--src-dir=<replaceable>source-dir</replaceable></arg>
        <arg choice="req"><replaceable>instance</replaceable></arg>
@@ -119,7 +122,7 @@
      <para>
        The <option>-s</option> option specifies the disk size for
-        the instance, in gigibytes (defaults to 20 GiB).
+        the instance, in gibibytes (defaults to 20 GiB).
      </para>
      <para>
@@ -130,7 +133,7 @@
      <para>
        The <option>-m</option> option specifies the memory size for
-        the instance, in megibytes (defaults to 128 MiB).
+        the instance, in mebibytes (defaults to 128 MiB).
      </para>
      <para>
@@ -171,13 +174,26 @@
            <term>remote_raid1</term>
            <listitem>
              <para>
-                Disk devices will be md raid1 arrays with one component (so
+                Disk devices will be md raid1 arrays with one
-                it's not actually raid1): a drbd device between the instance's
+                component (so it's not actually raid1): a drbd (0.7.x)
-                primary node and the node given by the second value of the
+                device between the instance's primary node and the
+                node given by the second value of the
                <option>--node</option> option.
              </para>
            </listitem>
          </varlistentry>
+          <varlistentry>
+            <term>drbd</term>
+            <listitem>
+              <para>
+                Disk devices will be drbd (version 8.x) on top of lvm
+                volumes. They are equivalent in functionality to
+                <replaceable>remote_raid1</replaceable>, but are
+                recommended for new instances (if you have drbd 8.x
+                installed).
+              </para>
+            </listitem>
+          </varlistentry>
        </variablelist>
      </para>
@@ -208,11 +224,18 @@
      </cmdsynopsis>
      <para>
-        Lists the exports currently available in the default directory in all
+        Lists the exports currently available in the default directory
-        the nodes of the current cluster, or optionally only a subset of them
+        in all the nodes of the current cluster, or optionally only a
-        specified by the <option>--nodes</option> option.
+        subset of them specified by the <option>--nodes</option>
+        option (use this option multiple times to select multiple
+        nodes).
      </para>
+      <para>
+      Example:
+<screen>
+# gnt-backup list --nodes node1 --nodes node2
+</screen>
    </refsect2>
  </refsect1>

--- a/man/gnt-cluster.sgml
+++ b/man/gnt-cluster.sgml
@@ -148,6 +148,7 @@
      <cmdsynopsis>
        <command>destroy</command>
+        <arg choice="req">--yes-do-it</arg>
      </cmdsynopsis>
      <para>
@@ -155,6 +156,11 @@
        a <command>gnt-cluster init</command> can be done again
        afterwards.
      </para>
+      <para>
+        Since this is a dangerous command, you are required to pass
+        the argument <replaceable>--yes-do-it.</replaceable>
+      </para>
    </refsect2>
    <refsect2>

--- a/man/gnt-instance.sgml
+++ b/man/gnt-instance.sgml
@@ -74,6 +74,7 @@
              <arg>plain</arg>
              <arg>local_raid1</arg>
              <arg>remote_raid1</arg>
+              <arg>drbd</arg>
            </group>
          </arg>
          <sbr>
@@ -155,10 +156,23 @@
              <term>remote_raid1</term>
              <listitem>
                <para>
-                  Disk devices will be md raid1 arrays with one component (so
+                  Disk devices will be md raid1 arrays with one
-                  it's not actually raid1): a drbd device between the
+                  component (so it's not actually raid1): a drbd
-                  instance's primary node and the node given by the second
+                  (0.7.x) device between the instance's primary node
-                  value of the <option>--node</option> option.
+                  and the node given by the second value of the
+                  <option>--node</option> option.
+                </para>
+              </listitem>
+            </varlistentry>
+            <varlistentry>
+              <term>drbd</term>
+              <listitem>
+                <para>
+                  Disk devices will be drbd (version 8.x) on top of
+                  lvm volumes. They are equivalent in functionality to
+                  <replaceable>remote_raid1</replaceable>, but are
+                  recommended for new instances (if you have drbd 8.x
+                  installed).
                </para>
              </listitem>
            </varlistentry>

--- a/man/gnt-node.sgml
+++ b/man/gnt-node.sgml
@@ -382,6 +382,11 @@
      <cmdsynopsis>
        <command>volumes</command>
+        <arg>--no-headers</arg>
+        <arg>--human-readable</arg>
+        <arg>--separator=<replaceable>SEPARATOR</replaceable></arg>
+        <arg>--output=<replaceable>FIELDS</replaceable></arg>
+        <sbr>
        <arg rep="repeat"><replaceable>node</replaceable></arg>
      </cmdsynopsis>
@@ -390,6 +395,59 @@
        provided.
      </para>
+      <para>
+        The <option>--no-headers</option> option will skip the initial
+        header line. The <option>--separator</option> option takes an
+        argument which denotes what will be used between the output
+        fields. Both these options are to help scripting.
+      </para>
+      <para>
+        The <option>-o</option> option takes a comma-separated list of
+        output fields. The available fields and their meaning are:
+        <variablelist>
+          <varlistentry>
+            <term>node</term>
+            <listitem>
+              <simpara>the node name on which the volume exists</simpara>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>phys</term>
+            <listitem>
+              <simpara>the physical drive (on which the LVM physical
+              volume lives)</simpara>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>vg</term>
+            <listitem>
+              <simpara>the volume group name</simpara>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>name</term>
+            <listitem>
+              <simpara>the logical volume name</simpara>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>size</term>
+            <listitem>
+              <simpara>the logical volume size</simpara>
+            </listitem>
+          </varlistentry>
+          <varlistentry>
+            <term>instance</term>
+            <listitem>
+              <simpara>The name of the instance to which this volume
+              belongs, or (in case it's an orphan volume) the
+              character <quote>-</quote></simpara>
+            </listitem>
+          </varlistentry>
+        </variablelist>
+      </para>
      <para>
        Example:
        <screen>