Synnefo » snf-ganeti

<!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 20, 2007</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>

      <holder>Google Inc.</holder>

    </copyright>

    &dhdate;

  </refentryinfo>

  <refmeta>

    &dhucpackage;

    &dhsection;

    <refmiscinfo>ganeti 1.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 five required files: <filename>create</filename>,

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

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

      <filename>ganeti_api_version</filename> (text file).

    </para>

    <refsect2>

      <title>create</title>

      <cmdsynopsis>

        <command>create</command>

        <arg choice="req">-i <replaceable>instance_name</replaceable></arg>

        <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>

        <arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>

      </cmdsynopsis>

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

      a new instance from scratch.</para>

      <para>The argument to the <option>-i</option> option is the FQDN

      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 <option>-b</option> and <option>-s</option> options

      denote the block devices which will be visible in the instance

      as <emphasis>sda</emphasis> and <emphasis>sdb</emphasis>. The

      <emphasis>sda</emphasis> block device should be used for the

      root disk (and will be passed as the root device for Linux

      kernels). The <emphasis>sdb</emphasis> device should be setup

      for swap usage.</para>

    </refsect2>

    <refsect2>

      <title>import</title>

      <cmdsynopsis>

        <command>import</command>

        <arg choice="req">-i <replaceable>instance_name</replaceable></arg>

        <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>

        <arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>

      </cmdsynopsis>

      <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 same as for

        <command>create</command> and the output of the

        <command>export</command> will be provided on

        <acronym>stdin</acronym>.

      </para>

    </refsect2>

    <refsect2>

      <title>export</title>

      <cmdsynopsis>

        <command>export</command>

        <arg choice="req">-i <replaceable>instance_name</replaceable></arg>

        <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>

      </cmdsynopsis>

      <para>

        This command is used in order to make a backup of the

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

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

        to the <command>import</command> command.

      </para>

      <para>

        The options have the same meaning as for

        <command>create</command> and <command>import</command>, with

        the exception that the argument to <option>-i</option> denotes

        an existing instance.

      </para>

    </refsect2>

    <refsect2>

      <title>rename</title>

      <cmdsynopsis>

        <command>rename</command>

        <arg choice="req">-o <replaceable>old_name</replaceable></arg>

        <arg choice="req">-n <replaceable>new_name</replaceable></arg>

        <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>

        <arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>

      </cmdsynopsis>

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

        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.

        </screen>

      </para>

    </refsect2>

    <refsect2>

      <title>ganeti_api_version</title>

      <para>

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

        text file containing the version of the guest OS api that this

        OS definition complies with. The version documented by this

        man page is 5, so this file must contain the number 5 followed

        by a newline.

      </para>

    </refsect2>

  </refsect1>

  <refsect1>

    <title>NOTES</title>

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

-->