Initial commit.

[ganeti-local] / man / ganeti-os-interface.sgml

<!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 guest 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 four required files: <filename>create</filename>,
      <filename>import</filename>, <filename>export</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>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 4, so this file must contain 4 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>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:
-->