Provided by: ganeti2_2.0.5-1_all bug

NAME

       ganeti-os-interface - specifications for guest OS types

DESCRIPTION

       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.

REFERENCE

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

   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.

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

       INSTANCE_NAME
              The instance name the script should operate on.

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

       HYPERVISOR
              The hypervisor of this instance.

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

       DISK_%N_PATH
              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
              DISK_0_PATH=/dev/drbd0.

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

       DISK_%N_FRONTEND_TYPE
              (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
              ioemu.

       DISK_%N_BACKEND_TYPE
              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.

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

       NIC_%N_MAC
              The MAC address associated with this interface.

       NIC_%N_IP
              The IP address, if any, associated with  the  N-th  NIC  of  the
              instance.

       NIC_%N_BRIDGE
              The bridge to which this NIC will be attached to.

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

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

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

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

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

   RENAME
       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
       instance.

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

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

NOTES

   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 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  common.sh
       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:

       #!/bin/sh

       exit 0

       Note that the script must be executable.

REPORTING BUGS

       Report bugs to  <URL:http://code.google.com/p/ganeti/> or  contact  the
       developers using the ganeti mailing list <ganeti@googlegroups.com>.

SEE ALSO

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

       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.