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>October 02, 2009</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       <year>2008</year>
  24       <year>2009</year>
  25       <year>2010</year>
  26       <holder>Google Inc.</holder>
  27     </copyright>
  28     &dhdate;
  29   </refentryinfo>
  30   <refmeta>
  31     &dhucpackage;
  32
  33     &dhsection;
  34     <refmiscinfo>ganeti 2.1</refmiscinfo>
  35   </refmeta>
  36   <refnamediv>
  37     <refname>ganeti-os-interface</refname>
  38
  39     <refpurpose>specifications for guest OS types
  40     </refpurpose>
  41
  42   </refnamediv>
  43
  44   <refsect1>
  45     <title>DESCRIPTION</title>
  46
  47     <para>
  48       The method of supporting guest operating systems in Ganeti is to
  49       have, for each guest OS type, a directory containing a number of
  50       required files.
  51     </para>
  52
  53
  54   </refsect1>
  55   <refsect1>
  56     <title>REFERENCE</title>
  57
  58     <para>
  59       There are six required files: <filename>create</filename>,
  60       <filename>import</filename>, <filename>export</filename>,
  61       <filename>rename</filename> (executables),
  62       <filename>ganeti_api_version</filename> and
  63       <filename>variants.list</filename> (text file).
  64     </para>
  65
  66     <refsect2>
  67       <title>Common environment</title>
  68       <para>
  69         All commands will get their input via environment variables. A
  70         common set of variables will be exported for all commands, and
  71         some of them might have extra ones. Note that all counts are
  72         zero-based.
  73       </para>
  74       <variablelist>
  75         <varlistentry>
  76           <term>OS_API_VERSION</term>
  77           <listitem>
  78             <simpara>The OS api version that the rest of the
  79             environment conforms to.</simpara>
  80           </listitem>
  81         </varlistentry>
  82         <varlistentry>
  83           <term>INSTANCE_NAME</term>
  84           <listitem>
  85             <simpara>The instance name the script should operate
  86             on.</simpara>
  87           </listitem>
  88         </varlistentry>
  89         <varlistentry>
  90           <term>INSTANCE_OS</term>
  91           <listitem>
  92             <simpara>The name os the instance's OS as Ganeti knows
  93             it. This can simplify the OS scripts by providing the same
  94             scripts under multiple names, and then the scripts can use
  95             this name to alter their behaviour.</simpara>
  96             <simpara>Under OS api 15 changing the script behavior based
  97             on this variable is deprecated: OS_VARIANT should be used
  98             instead (see below).</simpara>
  99           </listitem>
 100         </varlistentry>
 101         <varlistentry>
 102           <term>OS_VARIANT</term>
 103           <listitem>
 104             <simpara>The variant of the OS which should be installed. Each OS
 105             must support all variants listed under its
 106             <filename>variants.list</filename> file, and may support more.
 107             Any more supported variants should be properly documented in the
 108             per-os documentation.</simpara>
 109           </listitem>
 110         </varlistentry>
 111         <varlistentry>
 112           <term>HYPERVISOR</term>
 113           <listitem>
 114             <simpara>The hypervisor of this instance.</simpara>
 115           </listitem>
 116         </varlistentry>
 117         <varlistentry>
 118           <term>DISK_COUNT</term>
 119           <listitem>
 120             <simpara>The number of disks the instance has. The actual
 121             disk defitions are in a set of additional variables. The
 122             instance's disk will be numbered from 0 to this value
 123             minus one.</simpara>
 124           </listitem>
 125         </varlistentry>
 126         <varlistentry>
 127           <term>DISK_%N_PATH</term>
 128           <listitem>
 129             <simpara>The path to the storage for disk N of the
 130             instance. This might be either a block device or a regular
 131             file, in which case the OS scripts should use
 132             <emphasis>losetup</emphasis> (if they need to mount
 133             it). E.g. the first disk of the instance might be exported
 134             as <envar>DISK_0_PATH=/dev/drbd0</envar>.</simpara>
 135           </listitem>
 136         </varlistentry>
 137         <varlistentry>
 138           <term>DISK_%N_ACCESS</term>
 139           <listitem>
 140             <simpara>This is how the hypervisor will export the
 141             instance disks: either read-write (<emphasis>rw</emphasis>) or
 142             read-only (<emphasis>ro</emphasis>).</simpara>
 143           </listitem>
 144         </varlistentry>
 145         <varlistentry>
 146           <term>DISK_%N_FRONTEND_TYPE</term>
 147           <listitem>
 148             <simpara>(Optional) If applicable to the current
 149             hypervisor type: the type of the device exported by the
 150             hypervisor. For example, the Xen HVM hypervisor can export
 151             disks as either <emphasis>paravirtual</emphasis> or
 152             <emphasis>ioemu</emphasis>.</simpara>
 153           </listitem>
 154         </varlistentry>
 155         <varlistentry>
 156           <term>DISK_%N_BACKEND_TYPE</term>
 157           <listitem>
 158             <simpara>How files are visible on the node side. This can
 159             be either <emphasis>block</emphasis> (when using block
 160             devices) or <emphasis>file:type</emphasis>, where
 161             <emphasis>type</emphasis> is either
 162             <emphasis>loop</emphasis> <emphasis>blktap</emphasis>
 163             depending on how the hypervisor will be configured. Note
 164             that not all backend types apply to all
 165             hypervisors.</simpara>
 166           </listitem>
 167         </varlistentry>
 168         <varlistentry>
 169           <term>NIC_COUNT</term>
 170           <listitem>
 171             <simpara>Similar to the <envar>DISK_COUNT</envar>, this
 172             represents the number of NICs of the instance.</simpara>
 173           </listitem>
 174         </varlistentry>
 175         <varlistentry>
 176           <term>NIC_%N_MAC</term>
 177           <listitem>
 178             <simpara>The MAC address associated with this
 179             interface.</simpara>
 180           </listitem>
 181         </varlistentry>
 182         <varlistentry>
 183           <term>NIC_%N_IP</term>
 184           <listitem>
 185             <simpara>The IP address, if any, associated with the N-th
 186             NIC of the instance.</simpara>
 187           </listitem>
 188         </varlistentry>
 189         <varlistentry>
 190           <term>NIC_%N_BRIDGE</term>
 191           <listitem>
 192             <simpara>The bridge to which this NIC will be attached
 193             to.</simpara>
 194           </listitem>
 195         </varlistentry>
 196         <varlistentry>
 197           <term>NIC_%N_FRONTEND_TYPE</term>
 198           <listitem>
 199             <para>(Optional) If applicable, the type of the exported
 200             NIC to the instance, this can be one of of: <simplelist
 201             type="inline"> <member>rtl8139</member>
 202             <member>ne2k_pci</member> <member>ne2k_isa</member>
 203             <member>paravirtual</member> </simplelist>.
 204               </para>
 205           </listitem>
 206         </varlistentry>
 207         <varlistentry>
 208           <term>DEBUG_LEVEL</term>
 209           <listitem>
 210             <simpara>If non-zero, this should cause the OS script to
 211             generate verbose logs of its execution, for
 212             troubleshooting purposes. Currently only
 213             <emphasis>0</emphasis> and <emphasis>1</emphasis> are
 214             valid values.</simpara>
 215           </listitem>
 216         </varlistentry>
 217       </variablelist>
 218     </refsect2>
 219
 220     <refsect2>
 221       <title>create</title>
 222
 223       <para>The <command>create</command> command is used for creating
 224       a new instance from scratch. It has no additional environment
 225       variables bside the common ones.</para>
 226
 227       <para>The <envar>INSTANCE_NAME</envar> variable denotes the name
 228       of the instance, which is guaranteed to resolve to an IP
 229       address. The create script should configure the instance
 230       according to this name. It can configure the IP statically or
 231       not, depending on the deployment environment.</para>
 232
 233       <para>The <envar>INSTANCE_REINSTALL</envar> variable is set to '1' when
 234       this create request is reinstalling and existing instance, rather than
 235       creating one anew. This can be used, for example, to preserve some
 236       data in the old instance in an os-specific way.</para>
 237
 238     </refsect2>
 239
 240     <refsect2>
 241       <title>export</title>
 242
 243       <para>
 244         This command is used in order to make a backup of a given disk
 245         of the instance. The command should write to stdout a dump of
 246         the given block device. The output of this program will be
 247         passed during restore to the <command>import</command>
 248         command.
 249       </para>
 250
 251       <para>
 252         The specific disk to backup is denoted by two additional
 253         environment variables: <envar>EXPORT_INDEX</envar> which
 254         denotes the index in the instance disks structure (and could
 255         be used for example to skip the second disk if not needed for
 256         backup) and <envar>EXPORT_PATH</envar> which has the same
 257         value as <emphasis>DISK_N_PATH</emphasis> but is duplicate
 258         here for easier usage by shell scripts (rather than parse the
 259         DISK_... variables).
 260       </para>
 261
 262     </refsect2>
 263
 264     <refsect2>
 265       <title>import</title>
 266
 267       <para>
 268         The <command>import</command> command is used for restoring an
 269         instance from a backup as done by
 270         <command>export</command>. The arguments are the similar to
 271         those passed to <command>export</command>, whose output will
 272         be provided on <acronym>stdin</acronym>.
 273       </para>
 274
 275       <para>
 276         The difference in variables is that the current disk is called
 277         by <envar>IMPORT_DEVICE</envar> and <envar>IMPORT_INDEX</envar>
 278         (instead of <emphasis>EXPORT_</emphasis>).
 279       </para>
 280
 281     </refsect2>
 282
 283     <refsect2>
 284       <title>rename</title>
 285
 286       <para>
 287         This command is used in order to perform a rename at the
 288         instance OS level, after the instance has been renamed in
 289         Ganeti. The command should do whatever steps are required to
 290         ensure that the instance is updated to use the new name, if
 291         the operating system supports it.
 292       </para>
 293
 294       <para>
 295         Note that it is acceptable for the rename script to do nothing
 296         at all, however be warned that in this case, there will be a
 297         desynchronization between what <computeroutput>gnt-instance
 298         list</computeroutput> shows you and the actual hostname of the
 299         instance.
 300       </para>
 301
 302       <para>The script will be passed one additional environment
 303       variable called <envar>OLD_INSTANCE_NAME</envar> which holds the
 304       old instance name. The <envar>INSTANCE_NAME</envar> variable
 305       holds the new instance name.</para>
 306
 307       <para>
 308         A very simple rename script should at least change the
 309         hostname and IP address of the instance, leaving the
 310         administrator to update the other services.
 311       </para>
 312     </refsect2>
 313
 314     <refsect2>
 315       <title>ganeti_api_version</title>
 316       <para>
 317         The <filename>ganeti_api_version</filename> file is a plain
 318         text file containing the version(s) of the guest OS api that
 319         this OS definition complies with, one per line. The version
 320         documented by this man page is 15, so this file must contain
 321         the number 15 followed by a newline if only this version is
 322         supported. A script compatible more than one ganeti version
 323         should contain the most recent version first (i.e. 15),
 324         followed by the old version(s) (in this case 10 and/or 5).
 325       </para>
 326     </refsect2>
 327
 328     <refsect2>
 329       <title>variants.list</title>
 330       <para>
 331         <filename>variants.list</filename> is a plain text file
 332         containing all the declared supported variants for this
 333         OS, one per line. At least one variant must be supported.
 334       </para>
 335     </refsect2>
 336
 337   </refsect1>
 338
 339   <refsect1>
 340     <title>NOTES</title>
 341
 342     <refsect2>
 343       <title>Retrocompatibility</title>
 344
 345       <para>
 346         Ganeti 2.1 is compatible with both api version 10, and 15.
 347         In api version 10 the <filename>variants.list</filename>
 348         file is ignored and no OS_VARIANT environment variable is
 349         passed.
 350       </para>
 351     </refsect2>
 352
 353     <refsect2>
 354       <title>Common behaviour</title>
 355
 356       <para>All the scripts should display an usage message when
 357       called with a wrong number of arguments or when the first
 358       argument is <option>-h</option> or
 359       <option>--help</option>.</para>
 360
 361     </refsect2>
 362
 363     <refsect2>
 364       <title>Upgrading from old versions</title>
 365       <refsect3>
 366
 367         <title>Version 10 to 15</title>
 368
 369         <para>
 370           The <filename>variants.list</filename> file has been
 371           added, so OSes should support at least one variant,
 372           declaring it in that file and must be prepared to parse
 373           the OS_VARIANT environment variable. OSes are free to
 374           support more variants than just the declared ones.
 375         </para>
 376
 377       </refsect3>
 378
 379       <refsect3>
 380
 381         <title>Version 5 to 10</title>
 382
 383         <para>
 384           The method os passing data has changed from command line
 385           options to environment variables, so scripts should be
 386           modified to use these. For an example of how this can be
 387           done in a way compatible with both versions, feel free to
 388           look at the debootstrap instance's
 389           <filename>common.sh</filename> auxiliary script.
 390         </para>
 391
 392         <para>
 393           Also, instances can have now a variable number of disks, not
 394           only two, and a variable number of NICs (instead of fixed
 395           one), so the scripts should deal with this. The biggest
 396           change is in the import/export, which are called once per
 397           disk, instead of once per instance.
 398         </para>
 399
 400       </refsect3>
 401
 402       <refsect3>
 403         <title>Version 4 to 5</title>
 404         <para>
 405           The <filename>rename</filename> script has been added. If
 406           you don't want to do any changes on the instances after a
 407           rename, you can migrate the OS definition to version 5 by
 408           creating the <filename>rename</filename> script simply as:
 409           <screen>
 410 #!/bin/sh
 411
 412 exit 0
 413           </screen>
 414         </para>
 415
 416         <para>Note that the script must be executable.</para>
 417       </refsect3>
 418     </refsect2>
 419
 420     <!--
 421     <refsect2>
 422
 423       <title>Export/import format</title>
 424
 425       <para>
 426         It is up to the export and import scripts to define the format
 427         they use. It is only required for these two to work
 428         together. It is not recommended that
 429       </para>
 430
 431     </refsect2>
 432     -->
 433
 434   </refsect1>
 435
 436   &footer;
 437
 438 </refentry>
 439
 440 <!-- Keep this comment at the end of the file
 441 Local variables:
 442 mode: sgml
 443 sgml-omittag:t
 444 sgml-shorttag:t
 445 sgml-minimize-attributes:nil
 446 sgml-always-quote-attributes:t
 447 sgml-indent-step:2
 448 sgml-indent-data:t
 449 sgml-parent-document:nil
 450 sgml-default-dtd-file:nil
 451 sgml-exposed-tags:nil
 452 sgml-local-catalogs:nil
 453 sgml-local-ecat-files:nil
 454 End:
 455 -->