Synnefo » snf-ganeti

ganeti-os-interface(7) Ganeti | Version @GANETI_VERSION@

========================================================

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

Since Ganeti version 2.5, the environment will be cleaned up before

being passed to scripts, therefore they will not inherit the environment

in with which the ganeti node daemon was started. If you depend on any

environment variables (non-Ganeti), then you will need to define or

source them appropriately.

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_UUID

    The uuid associated with the N-th disk of the instance.

DISK_%N_NAME

    (Optional) The name, if any, associated with the N-th disk of the instance.

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`` or ``blktap2``, 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_UUID

    The uuid associated with the N-th NIC of the instance.

NIC_%N_NAME

    (Optional) The name, if any, associated with the N-th NIC of the instance.

NIC_%N_IP

    The IP address, if any, associated with the N-th NIC of the

    instance.

NIC_%N_MODE

    The NIC mode, routed, bridged or openvswitch

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

    In bridged or openvswitch mode, this is the interface to which the

    NIC will be attached (same as ``NIC_%N_BRIDGE`` for bridged). In

    routed mode it is 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``.

NIC_%d_NETWORK_NAME

    (Optional) If a NIC network is specified, the network's name.

NIC_%d_NETWORK_UUID

    (Optional) If a NIC network is specified, the network's uuid.

NIC_%d_NETWORK_FAMILY

    (Optional) If a NIC network is specified, the network's family.

NIC_%d_NETWORK_SUBNET

    (Optional) If a NIC network is specified, the network's IPv4 subnet.

NIC_%d_NETWORK_GATEWAY

    (Optional) If a NIC network is specified, the network's IPv4

    gateway.

NIC_%d_NETWORK_SUBNET6

    (Optional) If a NIC network is specified, the network's IPv6 subnet.

NIC_%d_NETWORK_GATEWAY6

    (Optional) If a NIC network is specified, the network's IPv6

    gateway.

NIC_%d_NETWORK_MAC_PREFIX

    (Optional) If a NIC network is specified, the network's mac prefix.

NIC_%d_NETWORK_TAGS

    (Optional) If a NIC network is specified, the network's tags, space

    separated.

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 an 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_DEVICE`` which has the same value

as ``DISK_N_PATH`` but is duplicated 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 denoted 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 messages in case the validation

fails.

For the ``dhcp`` parameter given as example above, a verification

script could be:

.. code-block:: bash

    #!/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 20,

so this file must contain the number 20 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. 20), followed by the old version(s) (in this case 15 and/or

10).

variants.list

~~~~~~~~~~~~~

variants.list is a plain text file containing all the declared supported

variants for this OS, one per line. If this file is missing or empty,

then the OS won't be considered to support variants.

Empty lines and lines starting with a hash (``#``) are ignored.

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 versions 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. Note that this file is optional;

without it, the variants functionality is disabled.

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:

.. code-block:: bash

    #!/bin/sh

    exit 0

Note that the script must be executable.

.. vim: set textwidth=72 :

.. Local Variables:

.. mode: rst

.. fill-column: 72

.. End: