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.