Provided by: ganeti2_2.4.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
       files.  This directory must be present across all nodes (Ganeti doesn't
       replicate it) in order for the OS to be usable by Ganeti.


       There are six required files: create, import,  export,  rename,  verify
       (executables),  ganeti_api_version,  variants.list  and parameters.list
       (text files).

   Common environment
       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.

              Both names point to the name of  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.

              With  OS  API  15  changing  the  script  behavior based on this
              variable is deprecated: OS_VARIANT should be used  instead  (see

              The  variant  of  the OS which should be installed. Each OS must
              support all variants listed under its  variants.list  file,  and
              may support more. Any more supported variants should be properly
              documented in the per-OS documentation.

              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  or  blktap  depending  on  how  the  hypervisor  will   be
              configured.  Note  that  not  all  backend  types  apply  to all

              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 NIC mode, either routed or bridged

              The bridge to which this NIC will be attached. This variable  is
              defined only when the NIC is in bridged mode.

              If   the   NIC   is  in  bridged  mode,  this  is  the  same  as
              NIC_%N_BRIDGE.  If it is in routed mode, the routing table which
              will be used by the hypervisor to insert the appropriate routes.

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

              Each  OS  parameter  (see  below)  will  be  exported in its own
              variable, prefixed with OSP, and  upper-cased.  For  example,  a
              dhcp parameter will be exported as OSP_DHCP.

              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.

       The INSTANCE_REINSTALL variable is set to 1 when this create request is
       reinstalling and existing instance, rather than creating one anew. This
       can  be used, for example, to preserve some data in the old instance in
       an OS-specific way.

       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).

       To provide the user with an estimate on how long the export will  take,
       a  predicted  size  can be written to the file descriptor passed in the
       variable EXP_SIZE_FD.  The value is in bytes and must be terminated  by
       a  newline  character (\n). Older versions of Ganeti don't support this
       feature, hence the variable should be checked before use. Example:

             if test -n "$EXP_SIZE_FD"; then
               blockdev --getsize64 $blockdev >&$EXP_SIZE_FD

       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_INDEX (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  verify  script  is used to verify consistency of the OS parameters
       (see below). The command should take one  or  more  arguments  denoting
       what  checks  should  be  performed,  and  return  a  proper  exit code
       depending on whether the validation failed or succeeded.

       Currently  (API  version  20),  only  one   parameter   is   supported:
       parameters.    This   should  validate  the  OSP_  variables  from  the
       environment, and output  diagnostic  message  in  case  the  validation

       For  the  dhcp  parameter given as example above, a verification script
       could be:


             case $OSP_DHCP in
                 echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2
                 exit 1;

             exit 0


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

       variants.list  is  a  plain  text  file  containing  all  the  declared
       supported variants for this OS, one per line. At least one variant must
       be supported.

       This file declares the parameters supported by the  OS,  one  parameter
       per  line,  with name and description (space and/or tab separated). For

             dhcp Whether to enable (yes) or disable (no) dhcp
             root_size The size of the root partition, in GiB

       The parameters can then be used in instance  add  or  modification,  as

             # gnt-instance add -O dhcp=no,root_size=8 ...


   Backwards compatibility
       Ganeti  2.3 and up is compatible with API version 10, 15 and 20. The OS
       parameters and related scripts (verify) are only supported  in  version
       20. The variants functionality (variants.list, and OS_VARIANT env. var)
       are supported/present only in version 15 and up.

   Common behaviour
       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.

   Upgrading from old versions
   Version 15 to 20
       The  parameters.list  file  and  verify  script have been added. For no
       parameters, an empty parameters file and an empty verify  script  which
       returns success can be used.

   Version 10 to 15
       The  variants.list file has been added, so OSes should support at least
       one variant, declaring it in that file and must be  prepared  to  parse
       the  OS_VARIANT  environment  variable.  OSes  are free to support more
       variants than just the declared ones.

   Version 5 to 10
       The method for 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.

   Version 4 to 5
       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  project website ( 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-
       group(8)  (node  group commands), gnt-backup(8) (instance import/export
       commands), gnt-debug(8) (debug commands).

       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, 2010 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.