ganeti-os-interface.rst

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