Man page updates for the ganeti daemons.

This patch adds new man pages for the master and RAPI daemons, and
updates the node daemon and watcher man pages.

Reviewed-by: ultrotter

Makefile.am

@@ -179,8 +179,10 @@ EXTRA_DIST = \
 
 man_MANS = \
 	man/ganeti.7 \
+	man/ganeti-masterd.8 \
 	man/ganeti-noded.8 \
 	man/ganeti-os-interface.7 \
+	man/ganeti-rapi.8 \
 	man/ganeti-watcher.8 \
 	man/gnt-backup.8 \
 	man/gnt-cluster.8 \

man/ganeti-masterd.sgml

+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+
+  <!-- Please adjust the date whenever revising the manpage. -->
+  <!ENTITY dhdate      "<date>February 11, 2009</date>">
+  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
+       allowed: see man(7), man(1). -->
+  <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
+  <!ENTITY dhucpackage "<refentrytitle>ganeti-masterd</refentrytitle>">
+  <!ENTITY dhpackage   "ganeti-masterd">
+
+  <!ENTITY debian      "<productname>Debian</productname>">
+  <!ENTITY gnu         "<acronym>GNU</acronym>">
+  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
+  <!ENTITY footer SYSTEM "footer.sgml">
+]>
+
+<refentry>
+  <refentryinfo>
+    <copyright>
+      <year>2008</year>
+      <year>2009</year>
+      <holder>Google Inc.</holder>
+    </copyright>
+    &dhdate;
+  </refentryinfo>
+  <refmeta>
+    &dhucpackage;
+
+    &dhsection;
+    <refmiscinfo>ganeti 2.0</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>&dhpackage;</refname>
+
+    <refpurpose>ganeti master daemon</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>&dhpackage; </command>
+      <arg>-f</arg>
+      <arg>-d</arg>
+      <arg>--no-voting</arg>
+
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+
+    <para>
+      The <command>&dhpackage;</command> is the daemon which is
+      responsible for the overall cluster coordination. Without it, no
+      change can be performed on the cluster.
+    </para>
+
+    <para>
+      For testing purposes, you can give the <option>-f</option>
+      option and the program won't detach from the running terminal.
+    </para>
+
+    <para>
+      Debug-level message can be activated by giving the
+      <option>-d</option> option.
+    </para>
+    <refsect2>
+      <title>ROLE</title>
+      <para>
+        The role of the master daemon is to coordinate all the actions
+        that change the state of the cluster. Things like accepting
+        new jobs, coordinating the changes on nodes (via RPC calls to
+        the respective node daemons), maintaining the configuration
+        and so on are done via this daemon.
+      </para>
+
+      <para>
+        The only action that can be done without the master daemon is
+        the failover of the master role to another node in the
+        cluster, via the <command>gnt-cluster masterfailover</command>
+        command.
+      </para>
+
+      <para>
+        If the master daemon is stopped, the instances are not
+        affected, but they won't be restarted automatically in case of
+        failure.
+      </para>
+    </refsect2>
+
+    <refsect2>
+      <title>STARTUP</title>
+      <para>
+        At startup, the master daemon will confirm with the node
+        daemons that the node it is running is indeed the master node
+        of the cluster. It will abort if it doesn't get half plus one
+        positive answers (offline nodes are queried too, just in case
+        our configuration is stale).
+      </para>
+
+      <para>
+        For small clusters with a number of nodes down, and especially
+        for two-node clusters where the other has gone done, this
+        creates a problem. In this case the
+        <option>--no-voting</option> option can be used to skip this
+        process. The option requires interactive confirmation, as
+        having two masters on the same cluster is a very dangerous
+        situation and will most likely lead to data loss.
+      </para>
+    </refsect2>
+
+    <refsect2>
+      <title>JOB QUEUE</title>
+      <para>
+        The master daemon maintains a job queue (located under
+        <filename
+        class="directory">@LOCALSTATEDIR@/lib/ganeti/queue</filename>) in
+        which all current jobs are stored, one job per file serialized
+        in JSON format; in this directory a subdirectory called
+        <filename class="directory">archive</filename> holds archived
+        job files.
+      </para>
+
+      <para>
+        The moving of jobs from the current to the queue directory is
+        done via a request to the master; this can be accomplished
+        from the command line with the <command>gnt-job
+        archive</command> or <command>gnt-job autoarchive</command>
+        commands. In case of problems with the master, a job file can
+        simply be moved away or deleted (but this might leave the
+        cluster inconsistent).
+      </para>
+
+    </refsect2>
+
+    <refsect2>
+      <title>COMMUNICATION PROTOCOL</title>
+      <para>
+        The master accepts commands over a Unix socket, using JSON
+        serialized messages separated by a specific byte sequence. For
+        more details, see the design documentation supplied with
+        Ganeti.
+      </para>
+    </refsect2>
+
+  </refsect1>
+
+  &footer;
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->

man/ganeti-noded.sgml

 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
 
   <!-- Please adjust the date whenever revising the manpage. -->
-  <!ENTITY dhdate      "<date>June 16, 2007</date>">
+  <!ENTITY dhdate      "<date>February 11, 2009</date>">
   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
        allowed: see man(7), man(1). -->
   <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
@@ -19,6 +19,8 @@
     <copyright>
       <year>2006</year>
       <year>2007</year>
+      <year>2008</year>
+      <year>2009</year>
       <holder>Google Inc.</holder>
     </copyright>
     &dhdate;
@@ -27,17 +29,18 @@
     &dhucpackage;
 
     &dhsection;
-    <refmiscinfo>ganeti 1.2</refmiscinfo>
+    <refmiscinfo>ganeti 2.0</refmiscinfo>
   </refmeta>
   <refnamediv>
     <refname>&dhpackage;</refname>
 
-    <refpurpose>ganeti daemon</refpurpose>
+    <refpurpose>ganeti node daemon</refpurpose>
   </refnamediv>
   <refsynopsisdiv>
     <cmdsynopsis>
       <command>&dhpackage; </command>
       <arg>-f</arg>
+      <arg>-d</arg>
 
     </cmdsynopsis>
   </refsynopsisdiv>
@@ -46,13 +49,18 @@
 
     <para>
       The <command>&dhpackage;</command> is the daemon which is
-      responsible for the cluster functions in the ganeti system.
+      responsible for the node functions in the ganeti system.
     </para>
 
     <para>
       For testing purposes, you can give the <option>-f</option>
       option and the program won't detach from the running terminal.
     </para>
+
+    <para>
+      Debug-level message can be activated by giving the
+      <option>-d</option> option.
+    </para>
     <refsect2>
       <title>ROLE</title>
       <para>
@@ -62,6 +70,12 @@
         and so on are done via the node daemon.
       </para>
 
+      <para>
+        Also, in some cases the startup/shutdown of the master daemon
+        are done via the node daemon, and the cluster IP address is
+        also added/removed to the master node via it.
+      </para>
+
       <para>
         If the node daemon is stopped, the instances are not affected,
         but the master won't be able to talk to that node.
@@ -71,8 +85,8 @@
     <refsect2>
       <title>COMMUNICATION PROTOCOL</title>
       <para>
-        Currently the master-node protocol is done using the Twisted
-        perspective broker libraries.
+        Currently the master-node RPC is done using a simple json-RPC
+        over HTTP(S).
       </para>
     </refsect2>
 

man/ganeti-rapi.sgml

+<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
+
+  <!-- Fill in your name for FIRSTNAME and SURNAME. -->
+  <!-- Please adjust the date whenever revising the manpage. -->
+  <!ENTITY dhdate      "<date>February 11, 2009</date>">
+  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
+       allowed: see man(7), man(1). -->
+  <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
+  <!ENTITY dhucpackage "<refentrytitle>ganeti-rapi</refentrytitle>">
+  <!ENTITY dhpackage   "ganeti-rapi">
+
+  <!ENTITY debian      "<productname>Debian</productname>">
+  <!ENTITY gnu         "<acronym>GNU</acronym>">
+  <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
+  <!ENTITY footer SYSTEM "footer.sgml">
+]>
+
+<refentry>
+  <refentryinfo>
+    <copyright>
+      <year>2008</year>
+      <year>2009</year>
+      <holder>Google Inc.</holder>
+    </copyright>
+    &dhdate;
+  </refentryinfo>
+  <refmeta>
+    &dhucpackage;
+
+    &dhsection;
+    <refmiscinfo>ganeti 2.0</refmiscinfo>
+  </refmeta>
+  <refnamediv>
+    <refname>&dhpackage;</refname>
+
+    <refpurpose>ganeti remote API daemon</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <cmdsynopsis>
+      <command>&dhpackage; </command>
+      <arg>-d</arg>
+      <arg>-f</arg>
+      <arg>-p <replaceable>PORT</replaceable></arg>
+      <arg>--no-ssl</arg>
+      <arg>-K <replaceable>SSL_KEY_FILE</replaceable></arg>
+      <arg>-C <replaceable>SSL_CERT_FILE</replaceable></arg>
+
+    </cmdsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>DESCRIPTION</title>
+
+    <para>
+      <command>&dhpackage;</command> is the daemon providing a remote
+      API for Ganeti clusters.
+    </para>
+
+    <para>
+      It is automatically started on the master node, and by default
+      it uses SSL encryption. This can be disabled by passing the
+      <option>--no-ssl</option> option, or alternatively the
+      certificate used can be changed via the <option>-C</option>
+      option and the key via the <option>-K</option> option.
+    </para>
+
+    <para>
+      The daemon will listen by default on the port 5080, but this can
+      be changed via the <option>-p</option> option.
+    </para>
+
+    <para>
+      See the <emphasis>Ganeti remote API</emphasis> documentation for
+      further information.
+    </para>
+
+    <para>
+      Requests are logged to
+      <filename>@LOCALSTATEDIR@/log/ganeti/rapi-daemon.log</filename>,
+      in the same format as for the node and master daemon.
+    </para>
+
+  </refsect1>
+
+  &footer;
+
+</refentry>
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-default-dtd-file:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->

man/ganeti-watcher.sgml

@@ -2,7 +2,7 @@
 
   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
   <!-- Please adjust the date whenever revising the manpage. -->
-  <!ENTITY dhdate      "<date>June 20, 2007</date>">
+  <!ENTITY dhdate      "<date>February 11, 2009</date>">
   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
        allowed: see man(7), man(1). -->
   <!ENTITY dhsection   "<manvolnum>8</manvolnum>">
@@ -19,6 +19,8 @@
   <refentryinfo>
     <copyright>
       <year>2007</year>
+      <year>2008</year>
+      <year>2009</year>
       <holder>Google Inc.</holder>
     </copyright>
     &dhdate;
@@ -27,7 +29,7 @@
     &dhucpackage;
 
     &dhsection;
-    <refmiscinfo>ganeti 1.2</refmiscinfo>
+    <refmiscinfo>ganeti 2.0</refmiscinfo>
   </refmeta>
   <refnamediv>
     <refname>&dhpackage;</refname>
@@ -61,9 +63,10 @@
       secondaries on nodes that have been rebooted.
     </para>
 
-    <para>In order to prevent piling up commands, all the
-    <emphasis>gnt-*</emphasis> commands executed by ganeti-watcher are
-    run with a timeout of 15 seconds.
+    <para>
+      The watcher does synchronous queries but will submit jobs for
+      executing the changes. Due to locking, it could be that the jobs
+      execute much later than the watcher executes them.
     </para>
 
     <para>