Provided by: ganeti2_2.4.2-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.