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