code.grnet.gr Git - ganeti-local/blob - man/ganeti-os-interface.sgml

   1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   2
   3   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
   4   <!-- Please adjust the date whenever revising the manpage. -->
   5   <!ENTITY dhdate      "<date>June 20, 2007</date>">
   6   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
   7        allowed: see man(7), man(1). -->
   8   <!ENTITY dhsection   "<manvolnum>7</manvolnum>">
   9   <!ENTITY dhucpackage "<refentrytitle>ganeti-os-interface</refentrytitle>">
  10   <!ENTITY dhpackage   "ganeti">
  11
  12   <!ENTITY debian      "<productname>Debian</productname>">
  13   <!ENTITY gnu         "<acronym>GNU</acronym>">
  14   <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
  15   <!ENTITY footer SYSTEM "footer.sgml">
  16 ]>
  17
  18 <refentry>
  19   <refentryinfo>
  20     <copyright>
  21       <year>2006</year>
  22       <year>2007</year>
  23       <holder>Google Inc.</holder>
  24     </copyright>
  25     &dhdate;
  26   </refentryinfo>
  27   <refmeta>
  28     &dhucpackage;
  29
  30     &dhsection;
  31     <refmiscinfo>ganeti 1.2</refmiscinfo>
  32   </refmeta>
  33   <refnamediv>
  34     <refname>ganeti-os-interface</refname>
  35
  36     <refpurpose>specifications for guest OS types
  37     </refpurpose>
  38
  39   </refnamediv>
  40
  41   <refsect1>
  42     <title>DESCRIPTION</title>
  43
  44     <para>
  45       The method of supporting guest operating systems in Ganeti is to
  46       have, for each guest OS type, a directory containing a number of
  47       required files.
  48     </para>
  49
  50
  51   </refsect1>
  52   <refsect1>
  53     <title>REFERENCE</title>
  54
  55     <para>
  56       There are five required files: <filename>create</filename>,
  57       <filename>import</filename>, <filename>export</filename>,
  58       <filename>rename</filename> (executables) and
  59       <filename>ganeti_api_version</filename> (text file).
  60     </para>
  61
  62     <refsect2>
  63       <title>create</title>
  64       <cmdsynopsis>
  65         <command>create</command>
  66         <arg choice="req">-i <replaceable>instance_name</replaceable></arg>
  67         <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
  68         <arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>
  69       </cmdsynopsis>
  70
  71       <para>The <command>create</command> command is used for creating
  72       a new instance from scratch.</para>
  73
  74       <para>The argument to the <option>-i</option> option is the FQDN
  75       of the instance, which is guaranteed to resolve to an IP
  76       address. The create script should configure the instance
  77       according to this name. It can configure the IP statically or
  78       not, depending on the deployment environment.</para>
  79
  80       <para>The <option>-b</option> and <option>-s</option> options
  81       denote the block devices which will be visible in the instance
  82       as <emphasis>sda</emphasis> and <emphasis>sdb</emphasis>. The
  83       <emphasis>sda</emphasis> block device should be used for the
  84       root disk (and will be passed as the root device for Linux
  85       kernels). The <emphasis>sdb</emphasis> device should be setup
  86       for swap usage.</para>
  87
  88     </refsect2>
  89
  90     <refsect2>
  91       <title>import</title>
  92       <cmdsynopsis>
  93         <command>import</command>
  94         <arg choice="req">-i <replaceable>instance_name</replaceable></arg>
  95         <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
  96         <arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>
  97       </cmdsynopsis>
  98
  99       <para>
 100         The <command>import</command> command is used for restoring an
 101         instance from a backup as done by
 102         <command>export</command>. The arguments are the same as for
 103         <command>create</command> and the output of the
 104         <command>export</command> will be provided on
 105         <acronym>stdin</acronym>.
 106       </para>
 107
 108     </refsect2>
 109
 110     <refsect2>
 111       <title>export</title>
 112       <cmdsynopsis>
 113         <command>export</command>
 114         <arg choice="req">-i <replaceable>instance_name</replaceable></arg>
 115         <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
 116       </cmdsynopsis>
 117
 118       <para>
 119         This command is used in order to make a backup of the
 120         instance. The command should write to stdout a dump of the
 121         given block device. The output of this program will be passed
 122         to the <command>import</command> command.
 123       </para>
 124
 125       <para>
 126         The options have the same meaning as for
 127         <command>create</command> and <command>import</command>, with
 128         the exception that the argument to <option>-i</option> denotes
 129         an existing instance.
 130       </para>
 131
 132     </refsect2>
 133
 134     <refsect2>
 135       <title>rename</title>
 136       <cmdsynopsis>
 137         <command>rename</command>
 138         <arg choice="req">-o <replaceable>old_name</replaceable></arg>
 139         <arg choice="req">-n <replaceable>new_name</replaceable></arg>
 140         <arg choice="req">-b <replaceable>blockdev_sda</replaceable></arg>
 141         <arg choice="req">-s <replaceable>blockdev_sdb</replaceable></arg>
 142       </cmdsynopsis>
 143
 144       <para>
 145         This command is used in order to perform a rename at the
 146         instance OS level, after the instance has been renamed in
 147         Ganeti. The command should do whatever steps are required to
 148         ensure that the instance is updated to use the new name, if
 149         the operating system supports it.
 150       </para>
 151
 152       <para>
 153         Note that it is acceptable for the rename script to do nothing
 154         at all, however be warned that in this case, there will be a
 155         desynchronization between what <computeroutput>gnt-instance
 156         list</computeroutput> shows you and the actual hostname of the
 157         instance.
 158       </para>
 159
 160       <para>
 161         A very simple rename script should at least change the
 162         hostname and IP address of the instance, leaving the
 163         administrator to update the other services.
 164       </para>
 165     </refsect2>
 166
 167     <refsect2>
 168       <title>ganeti_api_version</title>
 169       <para>
 170         The <filename>ganeti_api_version</filename> file is a plain
 171         text file containing the version of the guest OS api that this
 172         OS definition complies with. The version documented by this
 173         man page is 5, so this file must contain the number 5 followed
 174         by a newline.
 175       </para>
 176     </refsect2>
 177
 178   </refsect1>
 179
 180   <refsect1>
 181     <title>NOTES</title>
 182
 183     <refsect2>
 184       <title>Common behaviour</title>
 185
 186       <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>
 187
 188     </refsect2>
 189
 190     <refsect2>
 191       <title>Upgrading from old versions</title>
 192       <refsect3>
 193         <title>Version 4 to 5</title>
 194         <para>
 195           The <filename>rename</filename> script has been added. If
 196           you don't want to do any changes on the instances after a
 197           rename, you can migrate the OS definition to version 5 by
 198           creating the <filename>rename</filename> script simply as:
 199           <screen>
 200 #!/bin/sh
 201
 202 exit 0
 203           </screen>
 204         </para>
 205
 206         <para>Note that the script must be executable.</para>
 207       </refsect3>
 208     </refsect2>
 209
 210     <!--
 211     <refsect2>
 212
 213       <title>Export/import format</title>
 214
 215       <para>
 216         It is up to the export and import scripts to define the format
 217         they use. It is only required for these two to work
 218         together. It is not recommended that
 219       </para>
 220
 221     </refsect2>
 222     -->
 223
 224   </refsect1>
 225
 226   &footer;
 227
 228 </refentry>
 229
 230 <!-- Keep this comment at the end of the file
 231 Local variables:
 232 mode: sgml
 233 sgml-omittag:t
 234 sgml-shorttag:t
 235 sgml-minimize-attributes:nil
 236 sgml-always-quote-attributes:t
 237 sgml-indent-step:2
 238 sgml-indent-data:t
 239 sgml-parent-document:nil
 240 sgml-default-dtd-file:nil
 241 sgml-exposed-tags:nil
 242 sgml-local-catalogs:nil
 243 sgml-local-ecat-files:nil
 244 End:
 245 -->