Provided by:
ganeti2_2.4.5-1_all 
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.