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

          <listitem>

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

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

-->