Provided by: ganeti2_2.0.5-1_all bug


       ganeti-os-interface - specifications for guest OS types


       The  method of supporting guest operating systems in Ganeti is to have,
       for each guest OS type, a directory containing  a  number  of  required


       There   are   five  required  files:  create,  import,  export,  rename
       (executables) and ganeti_api_version (text file).

       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.

              The OS api version that the rest of the environment conforms to.

              The instance name the script should operate on.

              The  name  os  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.

              The hypervisor of this instance.

              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.

              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 losetup (if they need to mount it). E.g.  the
              first    disk   of   the   instance   might   be   exported   as

              This is how the  hypervisor  will  export  the  instance  disks:
              either read-write (rw) or read-only (ro).

              (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 paravirtual or

              How files are visible on the node side. This can be either block
              (when  using  block  devices) or file:type, where type is either
              loop blktap depending on how the hypervisor will be  configured.
              Note that not all backend types apply to all hypervisors.

              Similar to the DISK_COUNT, this represents the number of NICs of
              the instance.

              The MAC address associated with this interface.

              The IP address, if any, associated with  the  N-th  NIC  of  the

              The bridge to which this NIC will be attached to.

              (Optional)  If  applicable,  the type of the exported NIC to the
              instance, this can be one of of:  rtl8139,  ne2k_pci,  ne2k_isa,

              If non-zero, this should cause the OS script to generate verbose
              logs of its execution, for troubleshooting  purposes.  Currently
              only 0 and 1 are valid values.

       The create command is used for creating a new instance from scratch. It
       has no additional environment variables bside the common ones.

       The INSTANCE_NAME 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.

       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
       import command.

       The specific disk to backup is denoted by  two  additional  environment
       variables:  EXPORT_INDEX  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  EXPORT_PATH  which  has  the  same  value as
       DISK_N_PATH but is duplicate here for easier  usage  by  shell  scripts
       (rather than parse the DISK_... variables).

       The  import  command is used for restoring an instance from a backup as
       done by export. The arguments  are  the  similar  to  those  passed  to
       export, whose output will be provided on stdin.

       The  difference  in  variables  is  that  the current disk is called by
       IMPORT_DEVICE and IMPORT_IDX (instead of EXPORT_).

       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.

       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 gnt-instance list shows you and the actual hostname of the

       The script will be passed one additional  environment  variable  called
       OLD_INSTANCE_NAME  which holds the old instance name. The INSTANCE_NAME
       variable holds the new instance name.

       A very simple rename script should at least change the hostname and  IP
       address  of the instance, leaving the administrator to update the other

       The ganeti_api_version  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  10,  so  this
       file  must  contain  the  number  10 followed by a newline if only this
       version is supported. A script compatible  with  both  Ganeti  1.2  and
       Ganeti  2.0  should  contain  the  most recent version first (i.e. 10),
       followed by the old version(s) (in this case, 5).


       All the scripts should display an usage  message  when  called  with  a
       wrong number of arguments or when the first argument is -h or --help.

   VERSION 5 TO 10
       The  method  os  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
       auxiliary script.

       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.

       The rename 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 rename script simply as:


       exit 0

       Note that the script must be executable.


       Report bugs to  <URL:> or  contact  the
       developers using the ganeti mailing list <>.


       Ganeti  overview  and  specifications:  ganeti(7)  (general  overview),
       ganeti-os-interface(7) (guest OS definitions).

       Ganeti commands:  gnt-cluster(8)  (cluster-wide  commands),  gnt-job(8)
       (job-related   commands),  gnt-node(8)  (node-related  commands),  gnt-
       instance(8) (instance commands), gnt-os(8) (guest  OS  commands),  gnt-
       backup(8)   (instance   import/export  commands),  gnt-debug(8)  (debug

       Ganeti  daemons:  ganeti-watcher(8)  (automatic  instance   restarter),
       ganeti-cleaner(8)  (job  queue cleaner), ganeti-noded(8) (node daemon),
       ganeti-masterd(8) (master daemon), ganeti-rapi(8) (remote API  daemon).


       Copyright  (C) 2006, 2007, 2008, 2009 Google Inc. Permission is granted
       to copy, distribute and/or modify under the terms of  the  GNU  General
       Public  License  as  published  by the Free Software Foundation; either
       version 2 of the License, or (at your option) any later version.

       On Debian systems, the complete text of the GNU General Public  License
       can be found in /usr/share/common-licenses/GPL.