From 320d986da8b23088083f627bbc95838180887fb1 Mon Sep 17 00:00:00 2001
From: Iustin Pop <iustin@google.com>
Date: Thu, 12 Feb 2009 07:33:41 +0000
Subject: [PATCH] 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 | 2 +
man/ganeti-masterd.sgml | 164 ++++++++++++++++++++++++++++++++++++++++
man/ganeti-noded.sgml | 26 +++++--
man/ganeti-rapi.sgml | 103 +++++++++++++++++++++++++
man/ganeti-watcher.sgml | 13 ++--
5 files changed, 297 insertions(+), 11 deletions(-)
create mode 100644 man/ganeti-masterd.sgml
create mode 100644 man/ganeti-rapi.sgml
diff --git a/Makefile.am b/Makefile.am
index 8ccbb8784..7d7dcbd6e 100644
--- a/Makefile.am
+++ b/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 \
diff --git a/man/ganeti-masterd.sgml b/man/ganeti-masterd.sgml
new file mode 100644
index 000000000..873dd720f
--- /dev/null
+++ b/man/ganeti-masterd.sgml
@@ -0,0 +1,164 @@
+<!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:
+-->
diff --git a/man/ganeti-noded.sgml b/man/ganeti-noded.sgml
index 7f00e14cf..996d0ed48 100644
--- a/man/ganeti-noded.sgml
+++ b/man/ganeti-noded.sgml
@@ -1,7 +1,7 @@
<!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>
diff --git a/man/ganeti-rapi.sgml b/man/ganeti-rapi.sgml
new file mode 100644
index 000000000..ccc5dea44
--- /dev/null
+++ b/man/ganeti-rapi.sgml
@@ -0,0 +1,103 @@
+<!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:
+-->
diff --git a/man/ganeti-watcher.sgml b/man/ganeti-watcher.sgml
index 30250cedc..b6e946585 100644
--- a/man/ganeti-watcher.sgml
+++ b/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>
--
GitLab