1 ganeti-os-interface(7) Ganeti | Version @GANETI_VERSION@
2 ========================================================
7 ganeti-os-interface - Specifications for guest OS types
12 The method of supporting guest operating systems in Ganeti is to have,
13 for each guest OS type, a directory containing a number of required
14 files. This directory must be present across all nodes (Ganeti doesn't
15 replicate it) in order for the OS to be usable by Ganeti.
21 There are eight required files: *create*, *import*, *export*, *rename*,
22 *verify* (executables), *ganeti_api_version*, *variants.list* and
23 *parameters.list* (text files).
28 All commands will get their input via environment variables. A
29 common set of variables will be exported for all commands, and some
30 of them might have extra ones. Note that all counts are
33 Since Ganeti version 2.5, the environment will be cleaned up before
34 being passed to scripts, therefore they will not inherit the environment
35 in with which the ganeti node daemon was started. If you depend on any
36 environment variables (non-Ganeti), then you will need to define or
37 source them appropriately.
40 The OS API version that the rest of the environment conforms to.
43 The instance name the script should operate on.
46 Both names point to the name of the instance's OS as Ganeti knows
47 it. This can simplify the OS scripts by providing the same scripts
48 under multiple names, and then the scripts can use this name to
49 alter their behaviour.
51 With OS API 15 changing the script behavior based on this variable
52 is deprecated: OS_VARIANT should be used instead (see below).
55 The variant of the OS which should be installed. Each OS must
56 support all variants listed under its variants.list file, and may
57 support more. Any more supported variants should be properly
58 documented in the per-OS documentation.
61 The hypervisor of this instance.
64 The number of disks the instance has. The actual disk defitions are
65 in a set of additional variables. The instance's disk will be
66 numbered from 0 to this value minus one.
69 The path to the storage for disk N of the instance. This might be
70 either a block device or a regular file, in which case the OS
71 scripts should use ``losetup`` (if they need to mount it). E.g. the
72 first disk of the instance might be exported as
73 ``DISK_0_PATH=/dev/drbd0``.
76 This is how the hypervisor will export the instance disks: either
77 read-write (``rw``) or read-only (``ro``).
80 (Optional) If applicable to the current hypervisor type: the type
81 of the device exported by the hypervisor. For example, the Xen HVM
82 hypervisor can export disks as either ``paravirtual`` or
86 How files are visible on the node side. This can be either
87 ``block`` (when using block devices) or ``file:type``, where
88 ``type`` is either ``loop`` or ``blktap`` depending on how the
89 hypervisor will be configured. Note that not all backend types
90 apply to all hypervisors.
93 Similar to the ``DISK_COUNT``, this represents the number of NICs
97 The MAC address associated with this interface.
100 The IP address, if any, associated with the N-th NIC of the
104 The NIC mode, routed, bridged or openvswitch
107 The bridge to which this NIC will be attached. This variable is
108 defined only when the NIC is in bridged mode.
111 In bridged or openvswitch mode, this is the interface to which the
112 NIC will be attached (same as ``NIC_%N_BRIDGE`` for bridged). In
113 routed mode it is the routing table which will be used by the
114 hypervisor to insert the appropriate routes.
117 (Optional) If applicable, the type of the exported NIC to the
118 instance, this can be one of: ``rtl8139``, ``ne2k_pci``,
119 ``ne2k_isa``, ``paravirtual``.
122 (Optional) If a NIC network is specified, the network's name.
125 (Optional) If a NIC network is specified, the network's uuid.
127 NIC_%d_NETWORK_FAMILY
128 (Optional) If a NIC network is specified, the network's family.
130 NIC_%d_NETWORK_SUBNET
131 (Optional) If a NIC network is specified, the network's IPv4 subnet.
133 NIC_%d_NETWORK_GATEWAY
134 (Optional) If a NIC network is specified, the network's IPv4
137 NIC_%d_NETWORK_SUBNET6
138 (Optional) If a NIC network is specified, the network's IPv6 subnet.
140 NIC_%d_NETWORK_GATEWAY6
141 (Optional) If a NIC network is specified, the network's IPv6
144 NIC_%d_NETWORK_MAC_PREFIX
145 (Optional) If a NIC network is specified, the network's mac prefix.
148 (Optional) If a NIC network is specified, the network's tags, space
152 Each OS parameter (see below) will be exported in its own
153 variable, prefixed with ``OSP_``, and upper-cased. For example, a
154 ``dhcp`` parameter will be exported as ``OSP_DHCP``.
157 If non-zero, this should cause the OS script to generate verbose
158 logs of its execution, for troubleshooting purposes. Currently
159 only ``0`` and ``1`` are valid values.
169 The **create** command is used for creating a new instance from
170 scratch. It has no additional environment variables bside the
173 The ``INSTANCE_NAME`` variable denotes the name of the instance,
174 which is guaranteed to resolve to an IP address. The create script
175 should configure the instance according to this name. It can
176 configure the IP statically or not, depending on the deployment
179 The ``INSTANCE_REINSTALL`` variable is set to ``1`` when this create
180 request is reinstalling an existing instance, rather than creating
181 one anew. This can be used, for example, to preserve some data in the
182 old instance in an OS-specific way.
187 This command is used in order to make a backup of a given disk of
188 the instance. The command should write to stdout a dump of the
189 given block device. The output of this program will be passed
190 during restore to the **import** command.
192 The specific disk to backup is denoted by two additional environment
193 variables: ``EXPORT_INDEX`` which denotes the index in the instance
194 disks structure (and could be used for example to skip the second disk
195 if not needed for backup) and ``EXPORT_DEVICE`` which has the same value
196 as ``DISK_N_PATH`` but is duplicated here for easier usage by shell
197 scripts (rather than parse the ``DISK_...`` variables).
199 To provide the user with an estimate on how long the export will take,
200 a predicted size can be written to the file descriptor passed in the
201 variable ``EXP_SIZE_FD``. The value is in bytes and must be terminated
202 by a newline character (``\n``). Older versions of Ganeti don't
203 support this feature, hence the variable should be checked before
206 if test -n "$EXP_SIZE_FD"; then
207 blockdev --getsize64 $blockdev >&$EXP_SIZE_FD
213 The **import** command is used for restoring an instance from a
214 backup as done by **export**. The arguments are the similar to
215 those passed to **export**, whose output will be provided on
218 The difference in variables is that the current disk is denoted by
219 ``IMPORT_DEVICE`` and ``IMPORT_INDEX`` (instead of ``EXPORT_...``).
224 This command is used in order to perform a rename at the instance
225 OS level, after the instance has been renamed in Ganeti. The
226 command should do whatever steps are required to ensure that the
227 instance is updated to use the new name, if the operating system
230 Note that it is acceptable for the rename script to do nothing at
231 all, however be warned that in this case, there will be a
232 desynchronization between what gnt-instance list shows you and the
233 actual hostname of the instance.
235 The script will be passed one additional environment variable
236 called ``OLD_INSTANCE_NAME`` which holds the old instance name. The
237 ``INSTANCE_NAME`` variable holds the new instance name.
239 A very simple rename script should at least change the hostname and
240 IP address of the instance, leaving the administrator to update the
246 The *verify* script is used to verify consistency of the OS parameters
247 (see below). The command should take one or more arguments denoting
248 what checks should be performed, and return a proper exit code
249 depending on whether the validation failed or succeeded.
251 Currently (API version 20), only one parameter is supported:
252 ``parameters``. This should validate the ``OSP_`` variables from the
253 environment, and output diagnostic messages in case the validation
256 For the ``dhcp`` parameter given as example above, a verification
267 echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2
282 The ganeti_api_version file is a plain text file containing the
283 version(s) of the guest OS API that this OS definition complies
284 with, one per line. The version documented by this man page is 20,
285 so this file must contain the number 20 followed by a newline if
286 only this version is supported. A script compatible with more than
287 one Ganeti version should contain the most recent version first
288 (i.e. 20), followed by the old version(s) (in this case 15 and/or
294 variants.list is a plain text file containing all the declared supported
295 variants for this OS, one per line. If this file is missing or empty,
296 then the OS won't be considered to support variants.
298 Empty lines and lines starting with a hash (``#``) are ignored.
303 This file declares the parameters supported by the OS, one parameter
304 per line, with name and description (space and/or tab separated). For
307 dhcp Whether to enable (yes) or disable (no) dhcp
308 root_size The size of the root partition, in GiB
310 The parameters can then be used in instance add or modification, as
313 # gnt-instance add -O dhcp=no,root_size=8 ...
319 Backwards compatibility
320 ~~~~~~~~~~~~~~~~~~~~~~~
322 Ganeti 2.3 and up is compatible with API versions 10, 15 and 20. The OS
323 parameters and related scripts (verify) are only supported in
324 version 20. The variants functionality (variants.list, and OS_VARIANT
325 env. var) are supported/present only in version 15 and up.
330 All the scripts should display an usage message when called with a
331 wrong number of arguments or when the first argument is ``-h`` or
334 Upgrading from old versions
335 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
340 The ``parameters.list`` file and ``verify`` script have been
341 added. For no parameters, an empty parameters file and an empty verify
342 script which returns success can be used.
347 The ``variants.list`` file has been added, so OSes should support at
348 least one variant, declaring it in that file and must be prepared to
349 parse the OS_VARIANT environment variable. OSes are free to support more
350 variants than just the declared ones. Note that this file is optional;
351 without it, the variants functionality is disabled.
356 The method for passing data has changed from command line options
357 to environment variables, so scripts should be modified to use
358 these. For an example of how this can be done in a way compatible
359 with both versions, feel free to look at the debootstrap instance's
360 common.sh auxiliary script.
362 Also, instances can have now a variable number of disks, not only
363 two, and a variable number of NICs (instead of fixed one), so the
364 scripts should deal with this. The biggest change is in the
365 import/export, which are called once per disk, instead of once per
371 The rename script has been added. If you don't want to do any
372 changes on the instances after a rename, you can migrate the OS
373 definition to version 5 by creating the rename script simply as:
381 Note that the script must be executable.
383 .. vim: set textwidth=72 :