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

REFERENCE

       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.

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

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

       NIC_%N_LINK
              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.

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

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

       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.

EXECUTABLE SCRIPTS

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

       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
             fi

   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.

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

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

             #!/bin/sh

             case $OSP_DHCP in
               ""|yes|no)
                   ;;
               *)
                 echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2
                 exit 1;
                 ;;
             esac

             exit 0

TEXT FILES

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

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

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

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

NOTES

   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 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  project  website  (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-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

       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.