ganeti-os-interface.rst 12.6 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11
ganeti-os-interface(7) Ganeti | Version @GANETI_VERSION@
========================================================

Name
----

ganeti-os-interface - Specifications for guest OS types

DESCRIPTION
-----------

12 13 14 15 16
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.

17 18 19 20

REFERENCE
---------

21
There are eight required files: *create*, *import*, *export*, *rename*,
22 23
*verify* (executables), *ganeti_api_version*, *variants.list* and
*parameters.list* (text files).
24 25 26 27 28 29 30 31 32

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.

Iustin Pop's avatar
Iustin Pop committed
33 34 35 36 37 38
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.

39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63
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
64
    The number of disks the instance has. The actual disk definitions are
65 66 67 68 69 70 71 72 73 74 75 76 77 78
    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``).

79 80 81 82 83 84
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.

85 86 87 88 89 90 91 92 93
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
94 95 96
    ``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.
97 98 99 100 101 102 103 104

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.

105 106 107 108 109 110
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.

111 112 113 114 115
NIC_%N_IP
    The IP address, if any, associated with the N-th NIC of the
    instance.

NIC_%N_MODE
116
    The NIC mode, routed, bridged or openvswitch
117 118 119 120 121 122

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
123 124 125 126
    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.
127 128 129 130 131 132

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

133
NIC_%d_NETWORK_NAME
134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
    (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.

163 164
OSP_*name*
    Each OS parameter (see below) will be exported in its own
165
    variable, prefixed with ``OSP_``, and upper-cased. For example, a
166 167
    ``dhcp`` parameter will be exported as ``OSP_DHCP``.

168 169 170 171 172 173
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.


174 175 176 177
EXECUTABLE SCRIPTS
------------------


178 179 180 181 182 183 184 185 186 187 188 189 190 191
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
192
request is reinstalling an existing instance, rather than creating
193
a new one. This can be used, for example, to preserve some data in the
194 195 196 197 198 199 200 201 202 203 204 205 206
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
207 208
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
209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229
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.

230
The difference in variables is that the current disk is denoted by
231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254
``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.

255 256 257 258 259 260 261 262 263 264
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
265
environment, and output diagnostic messages in case the validation
266 267 268
fails.

For the ``dhcp`` parameter given as example above, a verification
269 270
script could be:

271
.. code-block:: bash
272 273 274 275

    #!/bin/sh

    case $OSP_DHCP in
276 277 278 279 280 281
      ""|yes|no)
          ;;
      *)
        echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2
        exit 1;
        ;;
282 283 284 285 286 287 288 289 290
    esac

    exit 0


TEXT FILES
----------


291 292 293 294 295
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
296 297
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
298 299
only this version is supported. A script compatible with more than
one Ganeti version should contain the most recent version first
300 301
(i.e. 20), followed by the old version(s) (in this case 15 and/or
10).
302 303 304 305

variants.list
~~~~~~~~~~~~~

306 307 308
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.
309

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

312 313 314 315 316 317 318 319 320 321 322 323 324
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::

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


328 329 330 331 332 333
NOTES
-----

Backwards compatibility
~~~~~~~~~~~~~~~~~~~~~~~

334
Ganeti 2.3 and up is compatible with API versions 10, 15 and 20. The OS
335 336 337
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.
338 339 340 341 342 343 344 345 346 347 348

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

349 350 351 352 353 354 355
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.

356 357 358 359 360
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
361 362 363
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.
364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384

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
385 386
definition to version 5 by creating the rename script simply as:

387
.. code-block:: bash
388 389 390 391 392 393

    #!/bin/sh

    exit 0

Note that the script must be executable.
394 395 396 397 398 399

.. vim: set textwidth=72 :
.. Local Variables:
.. mode: rst
.. fill-column: 72
.. End: