ganeti-os-interface(7)

📦
version 3.1.0~rc2 · 4 versions
, in debian trixie, ubuntu questing, ubuntu resolute

✨ NAME ✨

ganeti-os-interface — specifications for guest OS types, bestie. This is the ganeti-os-interface(7) page, Version 3.1.0~rc2, and it's giving "how do I even OS" energy, but make it iconic. 💖

💖 DESCRIPTION 💖

Okay so the way Ganeti supports guest operating systems is: for every guest OS type, you get a directory, and that directory has a bunch of required files in it. This directory has to be present across all the nodes (Ganeti does not replicate it for you, no cap), otherwise the OS is literally not usable by Ganeti. 🙈

🌈 REFERENCE 🌈

There are eight required files, and they are: create, import, export, rename, verify (these are the executables), plus ganeti_api_version, variants.list and parameters.list (these are text files). Eight files, one slay. 💅

🎀 Common environment 🎀

All the commands get their input through environment variables, okay? There's a common set of variables that gets exported for every command, and some commands might get extra ones on top. Also heads up: all counts are zero-based, so disk 0 is the first disk. ✨

Since Ganeti version 2.5, the environment gets cleaned up before being passed to scripts, which means your scripts will not inherit the environment that the ganeti node daemon was started with. So if you depend on any environment variables (non-Ganeti ones), you're gonna need to define them or source them appropriately yourself. No inheriting, no shortcuts. 😭

  • 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 definitions 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. If the disk is only accessible via a userspace URI, this will not be set.
  • DISK_%N_SIZE — the configured size of disk N in mebibytes (available since Ganeti 3.0).
  • DISK_%N_URI — the userspace URI to the storage for disk N of the instance, if configured.
  • 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 beside 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 a new one. 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 four additional environment variables:

  • EXPORT_INDEX — the index in the instance disks structure (and could be used for example to skip the second disk if not needed for backup).
  • EXPORT_DISK_PATH — alias for DISK_N_PATH. It is duplicated here for easier usage by shell scripts (rather than parse the DISK_... variables).
  • EXPORT_DISK_URI — alias for DISK_N_URI, analagous to EXPORT_DISK_PATH.
  • EXPORT_DEVICE — historical alias for EXPORT_DISK_PATH.

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_DISK_PATH, IMPORT_DISK_URI, 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:

#!/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 📁

okay bestie, so besides the executable scripts, an OS definition also ships a few lil text files that tell Ganeti what's up. here's the whole squad 💖

ganeti_api_version

the ganeti_api_version file is a plain text file, and it holds the version(s) of the guest OS API that this OS definition plays nice with — one per line, no cap. the version this very man page documents is 20, so if you only support this one, this file has to contain the number 20 followed by a newline. periodt.

and if your script is compatible with more than one Ganeti version? then put the most recent one first (i.e. 20), followed by the old version(s) — in this case 15 and/or 10. order matters, queen 👑

variants.list

variants.list is a plain text file with all the declared supported variants for this OS, one per line. and listen: if this file is missing or empty, then the OS won't be considered to support variants at all. no file, no variants, simple as 🫶

empty lines and lines starting with a hash (#) are ignored. so go ahead and leave cute lil comments, it's fine ✨

parameters.list

this file declares the parameters supported by the OS — one parameter per line, with the name and the description separated by a space and/or a tab. for example:

dhcp Whether to enable (yes) or disable (no) dhcp
root_size The size of the root partition, in GiB

and then you can actually use those parameters when adding or modifying an instance, like this:

# gnt-instance add -O dhcp=no,root_size=8 ...

slay. that's the whole point 💅

🗒️ NOTES 🗒️

backwards compatibility

so here's the tea, Ganeti 2.3 and up is compatible with API versions 10, 15 and 20. but the details are a lil uneven:

  • the OS parameters and their related scripts (the verify one) are only supported in version 20.
  • the variants functionality (variants.list, and the OS_VARIANT env. var) is supported/present only in version 15 and up.

so like, know which version you're targeting, bestie 🎀

common behaviour

all the scripts should display a usage message when they get called with a wrong number of arguments, or when the first argument is -h or --help. be polite to your users, it costs nothing 💖

upgrading from old versions

Version 15 to 20

the parameters.list file and the verify script have been added. and if you don't want any parameters at all? easy — just use an empty parameters file and an empty verify script that returns success. boom, done, no notes 🙈

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 though — go off 👑

but note: this file is optional. without it, the variants functionality is just disabled. no drama.

Version 5 to 10

big glow-up here: the method for passing data changed from command line options to environment variables, so scripts should be modified to use those instead. and for an example of how to do it in a way that's compatible with both versions, feel free to look at the debootstrap instance's common.sh auxiliary script. study the icon 🧚

also — and this is a real one — instances can now have a variable number of disks, not only two, and a variable number of NICs (instead of the old fixed one), so the scripts should deal with that. the biggest change is in the import/export, which now get called once per disk, instead of once per instance. not me gasping at that scope change 😭

Version 4 to 5

the rename script has been added. and if you don't wanna 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. don't forget the chmod bestie, or it literally will not run 💀

🐛 REPORTING BUGS 🐛

found a bug? report bugs to the project's issue tracker, or contact the developers using the Ganeti mailing list. they wanna hear from you, fr fr 🫶

👀 SEE ALSO 👀

Ganeti overview and specifications: ganeti(7) (general overview), ganeti-os-interface(7) (guest OS definitions), ganeti-extstorage-interface(7) (external storage providers).

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-storage(8) (storage 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-rapi(8) (remote API daemon).

Ganeti htools: htools(1) (generic binary), hbal(1) (cluster balancer), hspace(1) (capacity calculation), hail(1) (IAllocator plugin), hscan(1) (data gatherer from remote clusters), hinfo(1) (cluster information printer), mon-collector(7) (data collectors interface).

Copyright (C) 2006-2015 Google Inc. All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

and that's a wrap on ganeti-os-interface(7) from the Ganeti crew, version 20 energy, dated 2006-2015 in the copyright and shipped under the Ganeti banner 💖 go write some iconic OS definitions bestie, you got this 👑🦋✨

📦 where this page comes from