Add RST version of ganeti-os-interface man page

Signed-off-by: Iustin Pop <iustin@google.com>
Reviewed-by: René Nussbaumer <rn@google.com>

man/ganeti-os-interface.rst

+ganeti-os-interface(7) Ganeti | Version @GANETI_VERSION@
+========================================================
+
+Name
+----
+
+ganeti-os-interface - Specifications for guest OS types
+
+DESCRIPTION
+-----------
+
+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.
+
+REFERENCE
+---------
+
+There are six required files: *create*, *import*, *export*, *rename*
+(executables), *ganeti_api_version* and *variants.list* (text files).
+
+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.
+
+
+
+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
+    The number of disks the instance has. The actual disk defitions are
+    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``).
+
+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
+    ``type`` is either ``loop`` or ``blktap`` depending on how the
+    hypervisor will be configured.  Note that not all backend types
+    apply to all hypervisors.
+
+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.
+
+NIC_%N_IP
+    The IP address, if any, associated with the N-th NIC of the
+    instance.
+
+NIC_%N_MODE
+    The NIC mode, either routed or bridged
+
+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
+    If the NIC is in bridged mode, this is the same as
+    ``NIC_%N_BRIDGE``.  If it is in routed mode, the routing table
+    which will be used by the hypervisor to insert the appropriate
+    routes.
+
+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``.
+
+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.
+
+
+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
+request is reinstalling and existing instance, rather than creating
+one anew. This can be used, for example, to preserve some data in the
+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
+if not needed for backup) and ``EXPORT_PATH`` which has the same value
+as ``DISK_N_PATH`` but is duplicate here for easier usage by shell
+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.
+
+The difference in variables is that the current disk is called by
+``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.
+
+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
+with, one per line. The version documented by this man page is 15,
+so this file must contain the number 15 followed by a newline if
+only this version is supported. A script compatible with more than
+one Ganeti version should contain the most recent version first
+(i.e. 15), followed by the old version(s) (in this case 10 and/or
+5).
+
+variants.list
+~~~~~~~~~~~~~
+
+variants.list is a plain text file containing all the declared
+supported variants for this OS, one per line. At least one variant
+must be supported.
+
+NOTES
+-----
+
+Backwards compatibility
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Ganeti 2.2 is compatible with both API version 10, and 15. In API
+version 10 the variants.list file is ignored and no OS_VARIANT
+environment variable is passed.
+
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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
+parse the OS_VARIANT environment variable. OSes are free to support
+more variants than just the declared ones.
+
+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
+definition to version 5 by creating the rename script simply as::
+
+    #!/bin/sh
+
+    exit 0
+
+Note that the script must be executable.