Commit 4db3647e authored by Iustin Pop's avatar Iustin Pop
Browse files

Add RST version of ganeti-os-interface man page

Signed-off-by: default avatarIustin Pop <>
Reviewed-by: default avatarRené Nussbaumer <>
parent 9896f38d
ganeti-os-interface(7) Ganeti | Version @GANETI_VERSION@
ganeti-os-interface - Specifications for guest OS types
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.
There are six required files: *create*, *import*, *export*, *rename*
(executables), *ganeti_api_version* and *variants.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
The OS API version that the rest of the environment conforms to.
The instance name the script should operate on.
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).
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.
The hypervisor of this instance.
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.
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
This is how the hypervisor will export the instance disks: either
read-write (``rw``) or read-only (``ro``).
(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
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.
Similar to the ``DISK_COUNT``, this represents the number of NICs
of the instance.
The MAC address associated with this interface.
The IP address, if any, associated with the N-th NIC of the
The NIC mode, either routed or bridged
The bridge to which this NIC will be attached. This variable is
defined only when the NIC is in bridged mode.
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
(Optional) If applicable, the type of the exported NIC to the
instance, this can be one of: ``rtl8139``, ``ne2k_pci``,
``ne2k_isa``, ``paravirtual``.
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.
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
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.
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
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
The difference in variables is that the current disk is called by
``IMPORT_DEVICE`` and ``IMPORT_INDEX`` (instead of ``EXPORT_...``).
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.
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
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.
Backwards compatibility
Ganeti 2.2 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
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 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 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
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::
exit 0
Note that the script must be executable.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment