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