Provided by: ganeti2_2.1.2.1-2_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   six   required  files:  create,  import,  export,  rename
       (executables), ganeti_api_version and variants.list (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.

              Under OS api 15 changing  the  script  behavior  based  on  this
              variable  is  deprecated: OS_VARIANT should be used instead (see
              below).

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

       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.

       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.

   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_INDEX (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  15,  so  this
       file  must  contain  the  number  15 followed by a newline if only this
       version is supported. A script compatible 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
       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.

NOTES

   RETROCOMPATIBILITY
       Ganeti 2.1 is compatible with both api version  10,  and  15.   In  api
       version  10  the  variants.list  file  is  ignored  and  no  OS_VARIANT
       environment variable is passed.

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