Commit 320d986d authored by Iustin Pop's avatar Iustin Pop

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
parent 5de4474d
......@@ -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 \
......
<!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:
-->
<!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>
......
<!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:
-->
......@@ -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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment