Synnefo » snf-ganeti

  <refsect1>

    <title>REPORTING BUGS</title>

    <para>

      Report bugs to <ulink

      url="http://code.google.com/p/ganeti/"></ulink> or contact the

      developers using the Ganeti mailing list

      <ganeti@googlegroups.com>.

    </para>

  </refsect1>

  <refsect1>

    <title>SEE ALSO</title>

    <para>

      Ganeti overview and specifications:

      <citerefentry>

        <refentrytitle>ganeti</refentrytitle>

        <manvolnum>7</manvolnum>

      </citerefentry> (general overview),

      <citerefentry>

        <refentrytitle>ganeti-os-interface</refentrytitle>

        <manvolnum>7</manvolnum>

      </citerefentry> (guest OS definitions).

    </para>

    <para>Ganeti commands:

      <citerefentry>

        <refentrytitle>gnt-cluster</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (cluster-wide commands),

      <citerefentry>

        <refentrytitle>gnt-job</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (job-related commands),

      <citerefentry>

        <refentrytitle>gnt-node</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (node-related commands),

      <citerefentry>

        <refentrytitle>gnt-instance</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (instance commands),

      <citerefentry>

        <refentrytitle>gnt-os</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (guest OS commands),

      <citerefentry>

        <refentrytitle>gnt-backup</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (instance import/export commands),

      <citerefentry>

        <refentrytitle>gnt-debug</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (debug commands).

    </para>

    <para>Ganeti daemons:

      <citerefentry>

        <refentrytitle>ganeti-watcher</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (automatic instance restarter),

      <citerefentry>

        <refentrytitle>ganeti-cleaner</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (job queue cleaner),

      <citerefentry>

        <refentrytitle>ganeti-noded</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (node daemon),

      <citerefentry>

        <refentrytitle>ganeti-masterd</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (master daemon),

      <citerefentry>

        <refentrytitle>ganeti-rapi</refentrytitle>

        <manvolnum>8</manvolnum>

      </citerefentry> (remote API daemon).

    </para>

  </refsect1>

  <refsect1>

    <title>COPYRIGHT</title>

    <para>

      Copyright (C) 2006, 2007, 2008, 2009, 2010 Google Inc. Permission is

      granted to copy, distribute and/or modify under the terms of the

      &gnu; General Public License as published by the Free Software

      Foundation; either version 2 of the License, or (at your option)

      any later version.

    </para>

    <para>

      On Debian systems, the complete text of the GNU General Public

      License can be found in /usr/share/common-licenses/GPL.

    </para>

  </refsect1>

<!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>June 08, 2010</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-cleaner</refentrytitle>">

  <!ENTITY dhpackage   "ganeti-cleaner">

  <!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>2009</year>

      <year>2010</year>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>Ganeti 2.2</refmiscinfo>

  </refmeta>

  <refnamediv>

    <refname>&dhpackage;</refname>

    <refpurpose>Ganeti job queue cleaner</refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&dhpackage;</command>

    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1>

    <title>DESCRIPTION</title>

    <para>

      The <command>&dhpackage;</command> is a periodically run script to clean

      old job files from the job queue archive and to remove expired X509

      certificates and keys.

    </para>

    <para>

      <command>&dhpackage;</command> automatically removes all files older than

      21 days from

      <filename>@LOCALSTATEDIR@/lib/ganeti/queue/archive</filename> and all

      expired certificates and keys from

      <filename>@LOCALSTATEDIR@/run/ganeti/crypto</filename>

    </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:

-->

<!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [

  <!-- Please adjust the date whenever revising the manpage. -->

  <!ENTITY dhdate      "<date>June 08, 2010</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-confd</refentrytitle>">

  <!ENTITY dhpackage   "ganeti-confd">

  <!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>2009</year>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>Ganeti 2.2</refmiscinfo>

  </refmeta>

  <refnamediv>

    <refname>&dhpackage;</refname>

    <refpurpose>Ganeti conf daemon</refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&dhpackage; </command>

      <arg>-f</arg>

      <arg>-d</arg>

    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1>

    <title>DESCRIPTION</title>

    <para>

      <command>&dhpackage;</command> is a daemon used to answer queries related

      to the configuration of a Ganeti 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 conf daemon is to make sure we have a highly available

        and very fast way to query cluster configuration values. This daemon is

        automatically active on all master candidates, and so has no single

        point of failure. It communicates via UDP so each query can easily be

        sent to multiple servers, and it answers queries from a cached copy of

        the config it keeps in memory, so no disk access is required to get an

        answer.

      </para>

      <para>

        The config is reloaded from disk automatically when it changes, with a

        rate limit of once per second.

      </para>

      <para>

        If the conf daemon is stopped on all nodes, its clients won't be able

        to get query answers.

      </para>

    </refsect2>

    <refsect2>

      <title>COMMUNICATION PROTOCOL</title>

      <para>

        The confd protocol is an HMAC authenticated json-encoded custom format,

        over UDP. A client library is provided to make it easy to write

        software to query confd. More information can be found in the Ganeti

        2.1 design doc, and an example usage can be seen in the (external) NBMA

        daemon for 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 08, 2010</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>

      <year>2010</year>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>Ganeti 2.2</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

        master-failover</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 08, 2010</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-noded</refentrytitle>">

  <!ENTITY dhpackage   "ganeti-noded">

  <!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>2006</year>

      <year>2007</year>

      <year>2008</year>

      <year>2009</year>

      <year>2010</year>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>Ganeti 2.2</refmiscinfo>

  </refmeta>

  <refnamediv>

    <refname>&dhpackage;</refname>

    <refpurpose>Ganeti node daemon</refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&dhpackage; </command>

      <arg>-f</arg>

      <arg>-d</arg>

    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1>

    <title>DESCRIPTION</title>

    <para>

      The <command>&dhpackage;</command> is the daemon which is

      responsible for the node functions in the Ganeti system.

    </para>

    <para>

      By default, in order to be able to support features such as node

      powercycling even on systems with a very damaged root disk,

      <command>ganeti-noded</command> locks itself in RAM using

      <citerefentry>

        <refentrytitle>mlockall</refentrytitle>

        <manvolnum>2</manvolnum>

      </citerefentry>. You can disable this feature by passing in the

      <option>--no-mlock</option> to the daemon.

    </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>

    <para>

      Logging to syslog, rather than its own log file, can be enabled by

      passing in the <option>--syslog</option> option.

    </para>

    <para>

      The <command>ganeti-noded</command> daemon listens to port 1811 TCP, on

      all interfaces, by default. This can be overridden by an entry the

      services database (<filename>/etc/services</filename>) or by passing the

      <option>-p</option> option. The <option>-b</option> option can be used to

      specify the address to bind to (defaults to 0.0.0.0).

    </para>

    <para>

      Ganeti noded communication is protected via SSL, with a key generated at

      cluster init time. This can be disabled with the

      <option>--no-ssl</option> option, or a different SSL key and certificate

      can be specified using the <option>-K</option> and <option>-C</option>

      options.

    </para>

    <refsect2>

      <title>ROLE</title>

      <para>

        The role of the node daemon is to do almost all the actions

        that change the state of the node. Things like creating disks

        for instances, activating disks, starting/stopping instance

        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.

      </para>

    </refsect2>

    <refsect2>

      <title>COMMUNICATION PROTOCOL</title>

      <para>

        Currently the master-node RPC is done using a simple RPC protocol built

        using JSON over HTTP(S).

      </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" [

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->

  <!-- Please adjust the date whenever revising the manpage. -->

  <!ENTITY dhdate      "<date>June 08, 2010</date>">

  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are

       allowed: see man(7), man(1). -->

  <!ENTITY dhsection   "<manvolnum>7</manvolnum>">

  <!ENTITY dhucpackage "<refentrytitle>ganeti-os-interface</refentrytitle>">

  <!ENTITY dhpackage   "ganeti">

  <!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>2006</year>

      <year>2007</year>

      <year>2008</year>

      <year>2009</year>

      <year>2010</year>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>Ganeti 2.2</refmiscinfo>

  </refmeta>

  <refnamediv>

    <refname>ganeti-os-interface</refname>

    <refpurpose>Specifications for guest OS types</refpurpose>

  </refnamediv>

  <refsect1>

    <title>DESCRIPTION</title>

    <para>

      The method of supporting guest operating systems in Ganeti is to

      have, for each guest OS type, a directory containing a number of

      required files.

    </para>

  </refsect1>

  <refsect1>

    <title>REFERENCE</title>

    <para>

      There are six required files: <filename>create</filename>,

      <filename>import</filename>, <filename>export</filename>,

      <filename>rename</filename> (executables),

      <filename>ganeti_api_version</filename> and

      <filename>variants.list</filename> (text file).

    </para>

    <refsect2>

      <title>Common environment</title>

      <para>

        All commands will get their input via environment variables. A

        common set of variables will be exported for all commands, and

        some of them might have extra ones. Note that all counts are

        zero-based.

      </para>

      <variablelist>

        <varlistentry>

          <term>OS_API_VERSION</term>

          <listitem>

            <simpara>The OS API version that the rest of the

            environment conforms to.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>INSTANCE_NAME</term>

          <listitem>

            <simpara>The instance name the script should operate

            on.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>INSTANCE_OS</term>

          <term>OS_NAME</term>

          <listitem>

            <simpara>Both names point to the name of the instance's OS

            as Ganeti knows it. This can simplify the OS scripts by

            providing the same scripts under multiple names, and then

            the scripts can use this name to alter their

            behaviour.</simpara> <simpara>With OS API 15 changing the

            script behavior based on this variable is deprecated:

            OS_VARIANT should be used instead (see below).</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>OS_VARIANT</term>

          <listitem>

            <simpara>The variant of the OS which should be installed. Each OS

            must support all variants listed under its

            <filename>variants.list</filename> file, and may support more.

            Any more supported variants should be properly documented in the

            per-OS  documentation.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>HYPERVISOR</term>

          <listitem>

            <simpara>The hypervisor of this instance.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>DISK_COUNT</term>

          <listitem>

            <simpara>The number of disks the instance has. The actual

            disk defitions are in a set of additional variables. The

            instance's disk will be numbered from 0 to this value

            minus one.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>DISK_%N_PATH</term>

          <listitem>

            <simpara>The path to the storage for disk N of the

            instance. This might be either a block device or a regular

            file, in which case the OS scripts should use

            <emphasis>losetup</emphasis> (if they need to mount

            it). E.g. the first disk of the instance might be exported

            as <envar>DISK_0_PATH=/dev/drbd0</envar>.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>DISK_%N_ACCESS</term>

          <listitem>

            <simpara>This is how the hypervisor will export the

            instance disks: either read-write (<emphasis>rw</emphasis>) or

            read-only (<emphasis>ro</emphasis>).</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>DISK_%N_FRONTEND_TYPE</term>

          <listitem>

            <simpara>(Optional) If applicable to the current

            hypervisor type: the type of the device exported by the

            hypervisor. For example, the Xen HVM hypervisor can export

            disks as either <emphasis>paravirtual</emphasis> or

            <emphasis>ioemu</emphasis>.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>DISK_%N_BACKEND_TYPE</term>

          <listitem>

            <simpara>How files are visible on the node side. This can

            be either <emphasis>block</emphasis> (when using block

            devices) or <emphasis>file:type</emphasis>, where

            <emphasis>type</emphasis> is either

            <emphasis>loop</emphasis> <emphasis>blktap</emphasis>

            depending on how the hypervisor will be configured. Note

            that not all backend types apply to all

            hypervisors.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>NIC_COUNT</term>

          <listitem>

            <simpara>Similar to the <envar>DISK_COUNT</envar>, this

            represents the number of NICs of the instance.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>NIC_%N_MAC</term>

          <listitem>

            <simpara>The MAC address associated with this

            interface.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>NIC_%N_IP</term>

          <listitem>

            <simpara>The IP address, if any, associated with the N-th

            NIC of the instance.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>NIC_%N_MODE</term>

          <listitem>

            <simpara>The NIC mode, either routed or bridged</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>NIC_%N_BRIDGE</term>

          <listitem>

            <simpara>The bridge to which this NIC will be attached. This

            variable is defined only when the NIC is in bridged mode.</simpara>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>NIC_%N_LINK</term>

          <listitem>

           <simpara>If the NIC is in bridged mode, this is the same as

            NIC_%N_BRIDGE. If it is in routed mode, the routing table

            which will be used by the hypervisor to insert the appropriate

            routes.</simpara> </listitem>

        </varlistentry>

        <varlistentry>

          <term>NIC_%N_FRONTEND_TYPE</term>

          <listitem>

            <para>(Optional) If applicable, the type of the exported

            NIC to the instance, this can be one of of: <simplelist

            type="inline"> <member>rtl8139</member>

            <member>ne2k_pci</member> <member>ne2k_isa</member>

            <member>paravirtual</member> </simplelist>.

              </para>

          </listitem>

        </varlistentry>

        <varlistentry>

          <term>DEBUG_LEVEL</term>

          <listitem>

            <simpara>If non-zero, this should cause the OS script to

            generate verbose logs of its execution, for

            troubleshooting purposes. Currently only

            <emphasis>0</emphasis> and <emphasis>1</emphasis> are

            valid values.</simpara>

          </listitem>

        </varlistentry>

      </variablelist>

    </refsect2>

    <refsect2>

      <title>create</title>

      <para>The <command>create</command> command is used for creating

      a new instance from scratch. It has no additional environment

      variables bside the common ones.</para>

      <para>The <envar>INSTANCE_NAME</envar> variable denotes the name

      of the instance, which is guaranteed to resolve to an IP

      address. The create script should configure the instance

      according to this name. It can configure the IP statically or

      not, depending on the deployment environment.</para>

      <para>The <envar>INSTANCE_REINSTALL</envar> variable is set to '1' when

      this create request is reinstalling and existing instance, rather than

      creating one anew. This can be used, for example, to preserve some

      data in the old instance in an OS-specific way.</para>

    </refsect2>

    <refsect2>

      <title>export</title>

      <para>

        This command is used in order to make a backup of a given disk

        of the instance. The command should write to stdout a dump of

        the given block device. The output of this program will be

        passed during restore to the <command>import</command>

        command.

      </para>

      <para>

        The specific disk to backup is denoted by two additional

        environment variables: <envar>EXPORT_INDEX</envar> which

        denotes the index in the instance disks structure (and could

        be used for example to skip the second disk if not needed for

        backup) and <envar>EXPORT_PATH</envar> which has the same

        value as <emphasis>DISK_N_PATH</emphasis> but is duplicate

        here for easier usage by shell scripts (rather than parse the

        DISK_... variables).

      </para>

      <para>

        To provide the user with an estimate on how long the export will take,

        a predicted size can be written to the file descriptor passed in the

        variable <envar>EXP_SIZE_FD</envar>. The value is in bytes and must be

        terminated by a newline character (\n). Older versions of Ganeti don't

        support this feature, hence the variable should be checked before use.

        Example: <screen>

if test -n "$EXP_SIZE_FD"; then

  blockdev --getsize64 $blockdev >&$EXP_SIZE_FD

fi

</screen>

      </para>

    </refsect2>

    <refsect2>

      <title>import</title>

      <para>

        The <command>import</command> command is used for restoring an

        instance from a backup as done by

        <command>export</command>. The arguments are the similar to

        those passed to <command>export</command>, whose output will

        be provided on <acronym>stdin</acronym>.

      </para>

      <para>

        The difference in variables is that the current disk is called

        by <envar>IMPORT_DEVICE</envar> and <envar>IMPORT_INDEX</envar>

        (instead of <emphasis>EXPORT_</emphasis>).

      </para>

    </refsect2>

    <refsect2>

      <title>rename</title>

      <para>

        This command is used in order to perform a rename at the

        instance OS level, after the instance has been renamed in

        Ganeti. The command should do whatever steps are required to

        ensure that the instance is updated to use the new name, if

        the operating system supports it.

      </para>

      <para>

        Note that it is acceptable for the rename script to do nothing

        at all, however be warned that in this case, there will be a

        desynchronization between what <computeroutput>gnt-instance

        list</computeroutput> shows you and the actual hostname of the

        instance.

      </para>

      <para>The script will be passed one additional environment

      variable called <envar>OLD_INSTANCE_NAME</envar> which holds the

      old instance name. The <envar>INSTANCE_NAME</envar> variable

      holds the new instance name.</para>

      <para>

        A very simple rename script should at least change the

        hostname and IP address of the instance, leaving the

        administrator to update the other services.

      </para>

    </refsect2>

    <refsect2>

      <title>ganeti_api_version</title>

      <para>

        The <filename>ganeti_api_version</filename> file is a plain

        text file containing the version(s) of the guest OS API that

        this OS definition complies with, one per line. The version

        documented by this man page is 15, so this file must contain

        the number 15 followed by a newline if only this version is

        supported. A script compatible with more than one Ganeti version

        should contain the most recent version first (i.e. 15),

        followed by the old version(s) (in this case 10 and/or 5).

      </para>

    </refsect2>

    <refsect2>

      <title>variants.list</title>

      <para>

        <filename>variants.list</filename> is a plain text file

        containing all the declared supported variants for this

        OS, one per line. At least one variant must be supported.

      </para>

    </refsect2>

  </refsect1>

  <refsect1>

    <title>NOTES</title>

    <refsect2>

      <title>Backwards compatibility</title>

      <para>

        Ganeti 2.2 is compatible with both API version 10, and 15.

        In API version 10 the <filename>variants.list</filename>

        file is ignored and no OS_VARIANT environment variable is

        passed.

      </para>

    </refsect2>

    <refsect2>

      <title>Common behaviour</title>

      <para>All the scripts should display an usage message when

      called with a wrong number of arguments or when the first

      argument is <option>-h</option> or

      <option>--help</option>.</para>

    </refsect2>

    <refsect2>

      <title>Upgrading from old versions</title>

      <refsect3>

        <title>Version 10 to 15</title>

        <para>

          The <filename>variants.list</filename> file has been

          added, so OSes should support at least one variant,

          declaring it in that file and must be prepared to parse

          the OS_VARIANT environment variable. OSes are free to

          support more variants than just the declared ones.

        </para>

      </refsect3>

      <refsect3>

        <title>Version 5 to 10</title>

        <para>

          The method for passing data has changed from command line

          options to environment variables, so scripts should be

          modified to use these. For an example of how this can be

          done in a way compatible with both versions, feel free to

          look at the debootstrap instance's

          <filename>common.sh</filename> auxiliary script.

        </para>

        <para>

          Also, instances can have now a variable number of disks, not

          only two, and a variable number of NICs (instead of fixed

          one), so the scripts should deal with this. The biggest

          change is in the import/export, which are called once per

          disk, instead of once per instance.

        </para>

      </refsect3>

      <refsect3>

        <title>Version 4 to 5</title>

        <para>

          The <filename>rename</filename> script has been added. If

          you don't want to do any changes on the instances after a

          rename, you can migrate the OS definition to version 5 by

          creating the <filename>rename</filename> script simply as:

          <screen>

#!/bin/sh

exit 0

          </screen>

        </para>

        <para>Note that the script must be executable.</para>

      </refsect3>

    </refsect2>

    <!--

    <refsect2>

      <title>Export/import format</title>

      <para>

        It is up to the export and import scripts to define the format

        they use. It is only required for these two to work

        together. It is not recommended that

      </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" [

  <!-- Fill in your name for FIRSTNAME and SURNAME. -->

  <!-- Please adjust the date whenever revising the manpage. -->

  <!ENTITY dhdate      "<date>June 08, 2010</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>

      <year>2010</year>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>Ganeti 2.2</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>--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 to the "ganeti-rapi" tcp port, as listed in the

      system services database, or to port 5080 by default.

    </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>

  <refsect1>

    <title>ACCESS CONTROLS</title>

    <para>

      All query operations are allowed without authentication. Only

      the modification operations require authentication, in the form

      of basic authentication.

    </para>

    <para>

      The users and their rights are defined in a file named

      <filename>rapi_users</filename>, located in the <filename

      class="directory">@LOCALSTATEDIR@/lib/ganeti</filename>

      directory. The users should be listed one per line, in the

      following format:

    </para>

    <screen>username password options</screen>

    <para>

      Currently the <replaceable>options</replaceable> field should

      equal the string <emphasis>write</emphasis> in order to actually

      give write permission for the given users. Example:

    </para>

    <screen>rclient   secret    write

guest   tespw

</screen>

    <para>The first user (<userinput>rclient</userinput>) will have

    read-write rights, whereas the second user does only have read

    (query) rights, and as such is no different than not using

    authentication at all.</para>

    <para>More details (including on how to use hashed passwords) can be found

      in the Ganeti documentation.</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:

-->

<!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>June 08, 2010</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-watcher</refentrytitle>">

  <!ENTITY dhpackage   "ganeti-watcher">

  <!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>2007</year>

      <year>2008</year>

      <year>2009</year>

      <year>2010</year>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>Ganeti 2.2</refmiscinfo>

  </refmeta>

  <refnamediv>

    <refname>&dhpackage;</refname>

    <refpurpose>Ganeti cluster watcher</refpurpose>

  </refnamediv>

  <refsynopsisdiv>

    <cmdsynopsis>

      <command>&dhpackage; </command>

      <arg><option>--debug</option></arg>

      <arg><option>--job-age=<replaceable>age</replaceable></option></arg>

      <arg><option>--ignore-pause</option></arg>

    </cmdsynopsis>

  </refsynopsisdiv>

  <refsect1>

    <title>DESCRIPTION</title>

    <para>

      The <command>&dhpackage;</command> is a periodically run script

      which is responsible for keeping the instances in the correct

      status. It has two separate functions, one for the master node

      and another one that runs on every node.

    </para>

    <para>

      If the watcher is disabled at cluster level (via

      the <command>gnt-cluster watcher pause</command> command), it

      will exit without doing anything. The cluster-level pause can be

      overriden via the <option>--ignore-pause</option> option, for

      example if during a maintenance the watcher needs to be disabled

      in general, but the administrator wants to run it just once.

    </para>

    <para>

      The <option>--debug</option> option will increase the verbosity

      of the watcher and also activate logging to the standard error.

    </para>

    <refsect2>

      <title>Master operations</title>

      <para>

        Its primary function is to try to keep running all instances

        which are marked as <emphasis>up</emphasis> in the configuration

        file, by trying to start them a limited number of times.

      </para>

      <para>

        Another 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>

        The watcher will also archive old jobs (older than the age

        given via the <option>--job-age</option> option, which

        defaults to 6 hours), in order to keep the job queue

        manageable.

      </para>

    </refsect2>

    <refsect2>

      <title>Node operations</title>

      <para>

        The watcher will restart any down daemons that are appropriate

        for the current node.

      </para>

      <para>

        In addition, it will execute any scripts which exist under the

        <quote>watcher</quote> directory in the Ganeti hooks directory

        (@SYSCONFDIR@/ganeti/hooks). This should be used for

        lightweight actions, like starting any extra daemons.

      </para>

      <para>

        If the cluster

        parameter <literal>maintain_node_health</literal> is enabled,

        then the watcher will also shutdown instances and DRBD devices

        if the node is declared as offline by known master candidates.

      </para>

      <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 submits them.

      </para>

    </refsect2>

  </refsect1>

  <refsect1>

    <title>FILES</title>

    <para>

      The command has a state file located at

      <filename>@LOCALSTATEDIR@/lib/ganeti/watcher.data</filename>

      (only used on the master) and a log file at

      <filename>@LOCALSTATEDIR@/log/ganeti/watcher.log</filename>. Removal of

      either file will not affect correct operation; the removal of

      the state file will just cause the restart counters for the

      instances to reset to zero.

    </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:

-->

<!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>June 08, 2010</date>">

  <!-- SECTION should be 1-8, maybe w/ subsection other parameters are

       allowed: see man(7), man(1). -->

  <!ENTITY dhsection   "<manvolnum>7</manvolnum>">

  <!ENTITY dhucpackage "<refentrytitle>ganeti</refentrytitle>">

  <!ENTITY dhpackage   "ganeti">

  <!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>2006</year>

      <year>2007</year>

      <year>2008</year>

      <year>2009</year>

      <year>2010</year>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>Ganeti 2.2</refmiscinfo>

  </refmeta>

  <refnamediv>

    <refname>&dhpackage;</refname>

    <refpurpose>cluster-based virtualization management</refpurpose>