X-Git-Url: https://code.grnet.gr/git/ganeti-local/blobdiff_plain/386b57af7a09e4cdb2a40832f823397ee791d8d2..e557bae9fb6e3d23172c3a638f8973477a9283d9:/man/ganeti-os-interface.sgml?ds=sidebyside
diff --git a/man/ganeti-os-interface.sgml b/man/ganeti-os-interface.sgml
index 6d3a56f..c61ea5a 100644
--- a/man/ganeti-os-interface.sgml
+++ b/man/ganeti-os-interface.sgml
@@ -2,7 +2,7 @@
- June 20, 2007">
+ February 02, 2009">
7">
@@ -20,6 +20,8 @@
20062007
+ 2008
+ 2009Google Inc.
&dhdate;
@@ -28,10 +30,10 @@
&dhucpackage;
&dhsection;
- ganeti 1.2
+ ganeti 2.0
- ganeti guest OS interface
+ ganeti-os-interfacespecifications for guest OS types
@@ -60,86 +62,211 @@
+ 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
+
+ The name os 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.
+
+
+
+ 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
+ loopblktap
+ 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_BRIDGE
+
+ The bridge to which this NIC will be attached
+ to.
+
+
+
+ NIC_%N_FRONTEND_TYPE
+
+ (Optional) If applicable, the type of the exported
+ NIC to the instance, this can be one of of: rtl8139
+ ne2k_pcine2k_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
-
- create
- -i instance_name
- -b blockdev_sda
- -s blockdev_sdb
- The create command is used for creating
- a new instance from scratch.
+ a new instance from scratch. It has no additional environment
+ variables bside the common ones.
- The argument to the option is the FQDN
+ 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 and options
- denote the block devices which will be visible in the instance
- as sda and sdb. The
- sda block device should be used for the
- root disk (and will be passed as the root device for Linux
- kernels). The sdb device should be setup
- for swap usage.
+ 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.
- import
-
- import
- -i instance_name
- -b blockdev_sda
- -s blockdev_sdb
-
+ export
- The import command is used for restoring an
- instance from a backup as done by
- export. The arguments are the same as for
- create and the output of the
- export will be provided on
- stdin.
+ 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).
- export
-
- export
- -i instance_name
- -b blockdev_sda
-
+ import
- This command is used in order to make a backup of the
- instance. The command should write to stdout a dump of the
- given block device. The output of this program will be passed
- to the import command.
+ 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 options have the same meaning as for
- create and import, with
- the exception that the argument to denotes
- an existing instance.
+ The difference in variables is that the current disk is called
+ by IMPORT_DEVICE and IMPORT_IDX
+ (instead of EXPORT_).
rename
-
- rename
- -o old_name
- -n new_name
- -b blockdev_sda
- -s blockdev_sdb
-
This command is used in order to perform a rename at the
@@ -157,11 +284,15 @@
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.
-
@@ -169,10 +300,13 @@
ganeti_api_version
The ganeti_api_version file is a plain
- text file containing the version of the guest OS api that this
- OS definition complies with. The version documented by this
- man page is 5, so this file must contain the number 5 followed
- by a newline.
+ 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 10, so this file must contain
+ the number 10 followed by a newline if only this version is
+ supported. A script compatible with both Ganeti 1.2 and Ganeti
+ 2.0 should contain the most recent version first (i.e. 10),
+ followed by the old version(s) (in this case, 5).
@@ -184,13 +318,38 @@
Common behaviour
- All the scripts should display an usage message when called with a wrong number of arguments or when the first argument is or .
+ All the scripts should display an usage message when
+ called with a wrong number of arguments or when the first
+ argument is or
+ .Upgrading from old versions
+ Version 5 to 10
+
+
+ The method os 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