code.grnet.gr Git - ganeti-local/blob - man/ganeti-os-interface.rst

   1 ganeti-os-interface(7) Ganeti | Version @GANETI_VERSION@
   2 ========================================================
   3
   4 Name
   5 ----
   6
   7 ganeti-os-interface - Specifications for guest OS types
   8
   9 DESCRIPTION
  10 -----------
  11
  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.
  16
  17
  18 REFERENCE
  19 ---------
  20
  21 There are eight required files: *create*, *import*, *export*, *rename*,
  22 *verify* (executables), *ganeti_api_version*, *variants.list* and
  23 *parameters.list* (text files).
  24
  25 Common environment
  26 ~~~~~~~~~~~~~~~~~~
  27
  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
  31 zero-based.
  32
  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.
  38
  39 OS_API_VERSION
  40     The OS API version that the rest of the environment conforms to.
  41
  42 INSTANCE_NAME
  43     The instance name the script should operate on.
  44
  45 INSTANCE_OS, OS_NAME
  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.
  50
  51     With OS API 15 changing the script behavior based on this variable
  52     is deprecated: OS_VARIANT should be used instead (see below).
  53
  54 OS_VARIANT
  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.
  59
  60 HYPERVISOR
  61     The hypervisor of this instance.
  62
  63 DISK_COUNT
  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.
  67
  68 DISK_%N_PATH
  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``.
  74
  75 DISK_%N_ACCESS
  76     This is how the hypervisor will export the instance disks: either
  77     read-write (``rw``) or read-only (``ro``).
  78
  79 DISK_%N_UUID
  80     The uuid associated with the N-th disk of the instance.
  81
  82 DISK_%N_NAME
  83     (Optional) The name, if any, associated with the N-th disk of the instance.
  84
  85 DISK_%N_FRONTEND_TYPE
  86     (Optional) If applicable to the current hypervisor type: the type
  87     of the device exported by the hypervisor. For example, the Xen HVM
  88     hypervisor can export disks as either ``paravirtual`` or
  89     ``ioemu``.
  90
  91 DISK_%N_BACKEND_TYPE
  92     How files are visible on the node side. This can be either
  93     ``block`` (when using block devices) or ``file:type``, where
  94     ``type`` is either ``loop`` or ``blktap`` depending on how the
  95     hypervisor will be configured.  Note that not all backend types
  96     apply to all hypervisors.
  97
  98 NIC_COUNT
  99     Similar to the ``DISK_COUNT``, this represents the number of NICs
 100     of the instance.
 101
 102 NIC_%N_MAC
 103     The MAC address associated with this interface.
 104
 105 NIC_%N_UUID
 106     The uuid associated with the N-th NIC of the instance.
 107
 108 NIC_%N_NAME
 109     (Optional) The name, if any, associated with the N-th NIC of the instance.
 110
 111 NIC_%N_IP
 112     The IP address, if any, associated with the N-th NIC of the
 113     instance.
 114
 115 NIC_%N_MODE
 116     The NIC mode, routed, bridged or openvswitch
 117
 118 NIC_%N_BRIDGE
 119     The bridge to which this NIC will be attached. This variable is
 120     defined only when the NIC is in bridged mode.
 121
 122 NIC_%N_LINK
 123     In bridged or openvswitch mode, this is the interface to which the
 124     NIC will be attached (same as ``NIC_%N_BRIDGE`` for bridged). In
 125     routed mode it is the routing table which will be used by the
 126     hypervisor to insert the appropriate routes.
 127
 128 NIC_%N_FRONTEND_TYPE
 129     (Optional) If applicable, the type of the exported NIC to the
 130     instance, this can be one of: ``rtl8139``, ``ne2k_pci``,
 131     ``ne2k_isa``, ``paravirtual``.
 132
 133 NIC_%d_NETWORK_NAME
 134     (Optional) If a NIC network is specified, the network's name.
 135
 136 NIC_%d_NETWORK_UUID
 137     (Optional) If a NIC network is specified, the network's uuid.
 138
 139 NIC_%d_NETWORK_FAMILY
 140     (Optional) If a NIC network is specified, the network's family.
 141
 142 NIC_%d_NETWORK_SUBNET
 143     (Optional) If a NIC network is specified, the network's IPv4 subnet.
 144
 145 NIC_%d_NETWORK_GATEWAY
 146     (Optional) If a NIC network is specified, the network's IPv4
 147     gateway.
 148
 149 NIC_%d_NETWORK_SUBNET6
 150     (Optional) If a NIC network is specified, the network's IPv6 subnet.
 151
 152 NIC_%d_NETWORK_GATEWAY6
 153     (Optional) If a NIC network is specified, the network's IPv6
 154     gateway.
 155
 156 NIC_%d_NETWORK_MAC_PREFIX
 157     (Optional) If a NIC network is specified, the network's mac prefix.
 158
 159 NIC_%d_NETWORK_TAGS
 160     (Optional) If a NIC network is specified, the network's tags, space
 161     separated.
 162
 163 OSP_*name*
 164     Each OS parameter (see below) will be exported in its own
 165     variable, prefixed with ``OSP_``, and upper-cased. For example, a
 166     ``dhcp`` parameter will be exported as ``OSP_DHCP``.
 167
 168 DEBUG_LEVEL
 169     If non-zero, this should cause the OS script to generate verbose
 170     logs of its execution, for troubleshooting purposes. Currently
 171     only ``0`` and ``1`` are valid values.
 172
 173
 174 EXECUTABLE SCRIPTS
 175 ------------------
 176
 177
 178 create
 179 ~~~~~~
 180
 181 The **create** command is used for creating a new instance from
 182 scratch. It has no additional environment variables bside the
 183 common ones.
 184
 185 The ``INSTANCE_NAME`` variable denotes the name of the instance,
 186 which is guaranteed to resolve to an IP address. The create script
 187 should configure the instance according to this name. It can
 188 configure the IP statically or not, depending on the deployment
 189 environment.
 190
 191 The ``INSTANCE_REINSTALL`` variable is set to ``1`` when this create
 192 request is reinstalling an existing instance, rather than creating
 193 one anew. This can be used, for example, to preserve some data in the
 194 old instance in an OS-specific way.
 195
 196 export
 197 ~~~~~~
 198
 199 This command is used in order to make a backup of a given disk of
 200 the instance. The command should write to stdout a dump of the
 201 given block device. The output of this program will be passed
 202 during restore to the **import** command.
 203
 204 The specific disk to backup is denoted by two additional environment
 205 variables: ``EXPORT_INDEX`` which denotes the index in the instance
 206 disks structure (and could be used for example to skip the second disk
 207 if not needed for backup) and ``EXPORT_DEVICE`` which has the same value
 208 as ``DISK_N_PATH`` but is duplicated here for easier usage by shell
 209 scripts (rather than parse the ``DISK_...`` variables).
 210
 211 To provide the user with an estimate on how long the export will take,
 212 a predicted size can be written to the file descriptor passed in the
 213 variable ``EXP_SIZE_FD``. The value is in bytes and must be terminated
 214 by a newline character (``\n``). Older versions of Ganeti don't
 215 support this feature, hence the variable should be checked before
 216 use. Example::
 217
 218     if test -n "$EXP_SIZE_FD"; then
 219       blockdev --getsize64 $blockdev >&$EXP_SIZE_FD
 220     fi
 221
 222 import
 223 ~~~~~~
 224
 225 The **import** command is used for restoring an instance from a
 226 backup as done by **export**. The arguments are the similar to
 227 those passed to **export**, whose output will be provided on
 228 stdin.
 229
 230 The difference in variables is that the current disk is denoted by
 231 ``IMPORT_DEVICE`` and ``IMPORT_INDEX`` (instead of ``EXPORT_...``).
 232
 233 rename
 234 ~~~~~~
 235
 236 This command is used in order to perform a rename at the instance
 237 OS level, after the instance has been renamed in Ganeti. The
 238 command should do whatever steps are required to ensure that the
 239 instance is updated to use the new name, if the operating system
 240 supports it.
 241
 242 Note that it is acceptable for the rename script to do nothing at
 243 all, however be warned that in this case, there will be a
 244 desynchronization between what gnt-instance list shows you and the
 245 actual hostname of the instance.
 246
 247 The script will be passed one additional environment variable
 248 called ``OLD_INSTANCE_NAME`` which holds the old instance name. The
 249 ``INSTANCE_NAME`` variable holds the new instance name.
 250
 251 A very simple rename script should at least change the hostname and
 252 IP address of the instance, leaving the administrator to update the
 253 other services.
 254
 255 verify
 256 ~~~~~~
 257
 258 The *verify* script is used to verify consistency of the OS parameters
 259 (see below). The command should take one or more arguments denoting
 260 what checks should be performed, and return a proper exit code
 261 depending on whether the validation failed or succeeded.
 262
 263 Currently (API version 20), only one parameter is supported:
 264 ``parameters``. This should validate the ``OSP_`` variables from the
 265 environment, and output diagnostic messages in case the validation
 266 fails.
 267
 268 For the ``dhcp`` parameter given as example above, a verification
 269 script could be:
 270
 271 .. code-block:: bash
 272
 273     #!/bin/sh
 274
 275     case $OSP_DHCP in
 276       ""|yes|no)
 277           ;;
 278       *)
 279         echo "Invalid value '$OSP_DHCP' for the dhcp parameter" 1>&2
 280         exit 1;
 281         ;;
 282     esac
 283
 284     exit 0
 285
 286
 287 TEXT FILES
 288 ----------
 289
 290
 291 ganeti_api_version
 292 ~~~~~~~~~~~~~~~~~~
 293
 294 The ganeti_api_version file is a plain text file containing the
 295 version(s) of the guest OS API that this OS definition complies
 296 with, one per line. The version documented by this man page is 20,
 297 so this file must contain the number 20 followed by a newline if
 298 only this version is supported. A script compatible with more than
 299 one Ganeti version should contain the most recent version first
 300 (i.e. 20), followed by the old version(s) (in this case 15 and/or
 301 10).
 302
 303 variants.list
 304 ~~~~~~~~~~~~~
 305
 306 variants.list is a plain text file containing all the declared supported
 307 variants for this OS, one per line. If this file is missing or empty,
 308 then the OS won't be considered to support variants.
 309
 310 Empty lines and lines starting with a hash (``#``) are ignored.
 311
 312 parameters.list
 313 ~~~~~~~~~~~~~~~
 314
 315 This file declares the parameters supported by the OS, one parameter
 316 per line, with name and description (space and/or tab separated). For
 317 example::
 318
 319     dhcp Whether to enable (yes) or disable (no) dhcp
 320     root_size The size of the root partition, in GiB
 321
 322 The parameters can then be used in instance add or modification, as
 323 follows::
 324
 325     # gnt-instance add -O dhcp=no,root_size=8 ...
 326
 327
 328 NOTES
 329 -----
 330
 331 Backwards compatibility
 332 ~~~~~~~~~~~~~~~~~~~~~~~
 333
 334 Ganeti 2.3 and up is compatible with API versions 10, 15 and 20. The OS
 335 parameters and related scripts (verify) are only supported in
 336 version 20. The variants functionality (variants.list, and OS_VARIANT
 337 env. var) are supported/present only in version 15 and up.
 338
 339 Common behaviour
 340 ~~~~~~~~~~~~~~~~
 341
 342 All the scripts should display an usage message when called with a
 343 wrong number of arguments or when the first argument is ``-h`` or
 344 ``--help``.
 345
 346 Upgrading from old versions
 347 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 348
 349 Version 15 to 20
 350 ^^^^^^^^^^^^^^^^
 351
 352 The ``parameters.list`` file and ``verify`` script have been
 353 added. For no parameters, an empty parameters file and an empty verify
 354 script which returns success can be used.
 355
 356 Version 10 to 15
 357 ^^^^^^^^^^^^^^^^
 358
 359 The ``variants.list`` file has been added, so OSes should support at
 360 least one variant, declaring it in that file and must be prepared to
 361 parse the OS_VARIANT environment variable. OSes are free to support more
 362 variants than just the declared ones. Note that this file is optional;
 363 without it, the variants functionality is disabled.
 364
 365 Version 5 to 10
 366 ^^^^^^^^^^^^^^^
 367
 368 The method for passing data has changed from command line options
 369 to environment variables, so scripts should be modified to use
 370 these. For an example of how this can be done in a way compatible
 371 with both versions, feel free to look at the debootstrap instance's
 372 common.sh auxiliary script.
 373
 374 Also, instances can have now a variable number of disks, not only
 375 two, and a variable number of NICs (instead of fixed one), so the
 376 scripts should deal with this. The biggest change is in the
 377 import/export, which are called once per disk, instead of once per
 378 instance.
 379
 380 Version 4 to 5
 381 ^^^^^^^^^^^^^^
 382
 383 The rename script has been added. If you don't want to do any
 384 changes on the instances after a rename, you can migrate the OS
 385 definition to version 5 by creating the rename script simply as:
 386
 387 .. code-block:: bash
 388
 389     #!/bin/sh
 390
 391     exit 0
 392
 393 Note that the script must be executable.
 394
 395 .. vim: set textwidth=72 :
 396 .. Local Variables:
 397 .. mode: rst
 398 .. fill-column: 72
 399 .. End: