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
  13 have, for each guest OS type, a directory containing a number of
  14 required files.
  15
  16 REFERENCE
  17 ---------
  18
  19 There are six required files: *create*, *import*, *export*, *rename*
  20 (executables), *ganeti_api_version* and *variants.list* (text files).
  21
  22 Common environment
  23 ~~~~~~~~~~~~~~~~~~
  24
  25 All commands will get their input via environment variables. A
  26 common set of variables will be exported for all commands, and some
  27 of them might have extra ones. Note that all counts are
  28 zero-based.
  29
  30
  31
  32 OS_API_VERSION
  33     The OS API version that the rest of the environment conforms to.
  34
  35 INSTANCE_NAME
  36     The instance name the script should operate on.
  37
  38 INSTANCE_OS, OS_NAME
  39     Both names point to the name of the instance's OS as Ganeti knows
  40     it. This can simplify the OS scripts by providing the same scripts
  41     under multiple names, and then the scripts can use this name to
  42     alter their behaviour.
  43
  44     With OS API 15 changing the script behavior based on this variable
  45     is deprecated: OS_VARIANT should be used instead (see below).
  46
  47 OS_VARIANT
  48     The variant of the OS which should be installed. Each OS must
  49     support all variants listed under its variants.list file, and may
  50     support more. Any more supported variants should be properly
  51     documented in the per-OS documentation.
  52
  53 HYPERVISOR
  54     The hypervisor of this instance.
  55
  56 DISK_COUNT
  57     The number of disks the instance has. The actual disk defitions are
  58     in a set of additional variables. The instance's disk will be
  59     numbered from 0 to this value minus one.
  60
  61 DISK_%N_PATH
  62     The path to the storage for disk N of the instance. This might be
  63     either a block device or a regular file, in which case the OS
  64     scripts should use ``losetup`` (if they need to mount it). E.g. the
  65     first disk of the instance might be exported as
  66     ``DISK_0_PATH=/dev/drbd0``.
  67
  68 DISK_%N_ACCESS
  69     This is how the hypervisor will export the instance disks: either
  70     read-write (``rw``) or read-only (``ro``).
  71
  72 DISK_%N_FRONTEND_TYPE
  73     (Optional) If applicable to the current hypervisor type: the type
  74     of the device exported by the hypervisor. For example, the Xen HVM
  75     hypervisor can export disks as either ``paravirtual`` or
  76     ``ioemu``.
  77
  78 DISK_%N_BACKEND_TYPE
  79     How files are visible on the node side. This can be either
  80     ``block`` (when using block devices) or ``file:type``, where
  81     ``type`` is either ``loop`` or ``blktap`` depending on how the
  82     hypervisor will be configured.  Note that not all backend types
  83     apply to all hypervisors.
  84
  85 NIC_COUNT
  86     Similar to the ``DISK_COUNT``, this represents the number of NICs
  87     of the instance.
  88
  89 NIC_%N_MAC
  90     The MAC address associated with this interface.
  91
  92 NIC_%N_IP
  93     The IP address, if any, associated with the N-th NIC of the
  94     instance.
  95
  96 NIC_%N_MODE
  97     The NIC mode, either routed or bridged
  98
  99 NIC_%N_BRIDGE
 100     The bridge to which this NIC will be attached. This variable is
 101     defined only when the NIC is in bridged mode.
 102
 103 NIC_%N_LINK
 104     If the NIC is in bridged mode, this is the same as
 105     ``NIC_%N_BRIDGE``.  If it is in routed mode, the routing table
 106     which will be used by the hypervisor to insert the appropriate
 107     routes.
 108
 109 NIC_%N_FRONTEND_TYPE
 110     (Optional) If applicable, the type of the exported NIC to the
 111     instance, this can be one of: ``rtl8139``, ``ne2k_pci``,
 112     ``ne2k_isa``, ``paravirtual``.
 113
 114 DEBUG_LEVEL
 115     If non-zero, this should cause the OS script to generate verbose
 116     logs of its execution, for troubleshooting purposes. Currently
 117     only ``0`` and ``1`` are valid values.
 118
 119
 120 create
 121 ~~~~~~
 122
 123 The **create** command is used for creating a new instance from
 124 scratch. It has no additional environment variables bside the
 125 common ones.
 126
 127 The ``INSTANCE_NAME`` variable denotes the name of the instance,
 128 which is guaranteed to resolve to an IP address. The create script
 129 should configure the instance according to this name. It can
 130 configure the IP statically or not, depending on the deployment
 131 environment.
 132
 133 The ``INSTANCE_REINSTALL`` variable is set to ``1`` when this create
 134 request is reinstalling and existing instance, rather than creating
 135 one anew. This can be used, for example, to preserve some data in the
 136 old instance in an OS-specific way.
 137
 138 export
 139 ~~~~~~
 140
 141 This command is used in order to make a backup of a given disk of
 142 the instance. The command should write to stdout a dump of the
 143 given block device. The output of this program will be passed
 144 during restore to the **import** command.
 145
 146 The specific disk to backup is denoted by two additional environment
 147 variables: ``EXPORT_INDEX`` which denotes the index in the instance
 148 disks structure (and could be used for example to skip the second disk
 149 if not needed for backup) and ``EXPORT_PATH`` which has the same value
 150 as ``DISK_N_PATH`` but is duplicate here for easier usage by shell
 151 scripts (rather than parse the ``DISK_...`` variables).
 152
 153 To provide the user with an estimate on how long the export will take,
 154 a predicted size can be written to the file descriptor passed in the
 155 variable ``EXP_SIZE_FD``. The value is in bytes and must be terminated
 156 by a newline character (``\n``). Older versions of Ganeti don't
 157 support this feature, hence the variable should be checked before
 158 use. Example::
 159
 160     if test -n "$EXP_SIZE_FD"; then
 161       blockdev --getsize64 $blockdev >&$EXP_SIZE_FD
 162     fi
 163
 164 import
 165 ~~~~~~
 166
 167 The **import** command is used for restoring an instance from a
 168 backup as done by **export**. The arguments are the similar to
 169 those passed to **export**, whose output will be provided on
 170 stdin.
 171
 172 The difference in variables is that the current disk is called by
 173 ``IMPORT_DEVICE`` and ``IMPORT_INDEX`` (instead of ``EXPORT_...``).
 174
 175 rename
 176 ~~~~~~
 177
 178 This command is used in order to perform a rename at the instance
 179 OS level, after the instance has been renamed in Ganeti. The
 180 command should do whatever steps are required to ensure that the
 181 instance is updated to use the new name, if the operating system
 182 supports it.
 183
 184 Note that it is acceptable for the rename script to do nothing at
 185 all, however be warned that in this case, there will be a
 186 desynchronization between what gnt-instance list shows you and the
 187 actual hostname of the instance.
 188
 189 The script will be passed one additional environment variable
 190 called ``OLD_INSTANCE_NAME`` which holds the old instance name. The
 191 ``INSTANCE_NAME`` variable holds the new instance name.
 192
 193 A very simple rename script should at least change the hostname and
 194 IP address of the instance, leaving the administrator to update the
 195 other services.
 196
 197 ganeti_api_version
 198 ~~~~~~~~~~~~~~~~~~
 199
 200 The ganeti_api_version file is a plain text file containing the
 201 version(s) of the guest OS API that this OS definition complies
 202 with, one per line. The version documented by this man page is 15,
 203 so this file must contain the number 15 followed by a newline if
 204 only this version is supported. A script compatible with more than
 205 one Ganeti version should contain the most recent version first
 206 (i.e. 15), followed by the old version(s) (in this case 10 and/or
 207 5).
 208
 209 variants.list
 210 ~~~~~~~~~~~~~
 211
 212 variants.list is a plain text file containing all the declared
 213 supported variants for this OS, one per line. At least one variant
 214 must be supported.
 215
 216 NOTES
 217 -----
 218
 219 Backwards compatibility
 220 ~~~~~~~~~~~~~~~~~~~~~~~
 221
 222 Ganeti 2.2 is compatible with both API version 10, and 15. In API
 223 version 10 the variants.list file is ignored and no OS_VARIANT
 224 environment variable is passed.
 225
 226 Common behaviour
 227 ~~~~~~~~~~~~~~~~
 228
 229 All the scripts should display an usage message when called with a
 230 wrong number of arguments or when the first argument is ``-h`` or
 231 ``--help``.
 232
 233 Upgrading from old versions
 234 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
 235
 236 Version 10 to 15
 237 ^^^^^^^^^^^^^^^^
 238
 239 The ``variants.list`` file has been added, so OSes should support at
 240 least one variant, declaring it in that file and must be prepared to
 241 parse the OS_VARIANT environment variable. OSes are free to support
 242 more variants than just the declared ones.
 243
 244 Version 5 to 10
 245 ^^^^^^^^^^^^^^^
 246
 247 The method for passing data has changed from command line options
 248 to environment variables, so scripts should be modified to use
 249 these. For an example of how this can be done in a way compatible
 250 with both versions, feel free to look at the debootstrap instance's
 251 common.sh auxiliary script.
 252
 253 Also, instances can have now a variable number of disks, not only
 254 two, and a variable number of NICs (instead of fixed one), so the
 255 scripts should deal with this. The biggest change is in the
 256 import/export, which are called once per disk, instead of once per
 257 instance.
 258
 259 Version 4 to 5
 260 ^^^^^^^^^^^^^^
 261
 262 The rename script has been added. If you don't want to do any
 263 changes on the instances after a rename, you can migrate the OS
 264 definition to version 5 by creating the rename script simply as::
 265
 266     #!/bin/sh
 267
 268     exit 0
 269
 270 Note that the script must be executable.