code.grnet.gr Git - snf-image/blob - docs/interface.rst

   1 Interface
   2 =========
   3
   4 Ganeti OS Interface
   5 ^^^^^^^^^^^^^^^^^^^
   6
   7 *snf-image* requires ganeti-os-interface v20 to operate and it introduces the
   8 following OS Parameters:
   9
  10  * **img_format** (required if *config_url* is missing): the image format type
  11    (:ref:`details <image-format>`)
  12  * **img_id** (required if *config_url* is missing): the URI used to identify
  13    the image (:ref:`details <image-id>`)
  14  * **img_passwd** (required if *config_url* is missing): the password to be
  15    injected to the image
  16  * **img_properties** (optional): additional image properties used to customize
  17    the image (:ref:`details <image-properties>`)
  18  * **img_personality** (optional): files to be injected into the image
  19    filesystem (:ref:`details <image-personality>`)
  20  * **config_url** (optional): the url to download configuration data from
  21
  22 .. _image-format:
  23
  24 Image Format (img_format)
  25 ^^^^^^^^^^^^^^^^^^^^^^^^^
  26
  27 snf-image supports 3 different types of image formats:
  28
  29  * **diskdump** (recommended): a raw dump of a disk
  30  * **extdump**: a raw dump of an ext{2,3,4} file system
  31  * **ntfsdump**: a raw dump of an NTFS file system
  32
  33 These are also the only valid values for the **img_format** OS parameter.
  34 The **diskdump** type is the newest and recommended type. Thus, all sample
  35 images we provide are of this type. For more details about the internals of
  36 image formats please see the :ref:`corresponding advanced section
  37 <image-format-advanced>`.
  38
  39 .. _image-id:
  40
  41 Image ID (img_id)
  42 ^^^^^^^^^^^^^^^^^
  43
  44 The **img_id** OS parameter points to the actual Image that we want to deploy.
  45 It is a URI and its prefix denotes the type of :ref:`backend <storage-backends>`
  46 to be used. If no prefix is used, it defaults to the local backend:
  47
  48  * **Local backend**:
  49    To select it, the prefix should be ``file://``, followed by the name of the
  50    image. All local images are expected to be found under a predefined image
  51    directory (``/var/lib/snf-image`` by default). The name of the actual file
  52    should be ``<img_id>.<img_format>``.
  53    | For example, if we want to deploy the image file:
  54    | ``/var/lib/snf-image/slackware.diskdump``
  55    | Then:
  56    | ``img_format=diskdump`` and ``img_id=file://slackware``
  57
  58  * **Network backend**:
  59    If the **imd_id** starts with ``http:``, ``https:``, ``ftp:`` or ``ftps:``,
  60    snf-image will treat the **img_id** as a remote URL and will try to fetch the
  61    image using `cURL <http://curl.haxx.se/>`_.
  62    | For example, if we want to deploy an image from an http location:
  63    | ``img_id=http://www.synnefo.org/path/to/image/slackware-image``
  64
  65  * **Pithos backend**:
  66    If the **img_id** is prefixed with ``pithos://`` or ``pithosmap://`` the
  67    image is considered to reside on a Pithos deployment. For ``pithosmap://``
  68    images, the user needs to have set a valid value for the
  69    ``PITHOS_DATA`` variable in snf-image's configuration file
  70    (``/etc/default/snf-image`` by default). For ``pithos://`` images, in
  71    addition to ``PITHOS_DATA``, the user needs to have set a valid value for the
  72    ``PITHOS_DB`` variable, too.
  73    | For example, if we want to deploy using a full Pithos URI:
  74    | ``img_id=pithos://<user-uuid>/<container>/<slackware-image>``
  75    | or if we already know the map:
  76    | ``img_id=pithosmap://<slackware-image-map-name>``
  77
  78  * **Null backend**:
  79    To select the Null backend and skip the fetching and extraction step, we set
  80    ``img_id=null``.
  81
  82 .. _image-properties:
  83
  84 Image Properties (img_properties)
  85 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  86
  87 *snf-image* may use a number of properties to properly configure the image.
  88 Those image properties are passed to snf-image by Ganeti through the
  89 *img_poroperties* OS parameter (see Ganeti OS Interface). The name of all image
  90 properties is case-insensitive. For the diskdump format some properties are
  91 mandatory. For {ext,ntfs}dump formats all image properties are optional.
  92
  93 We can group image properties in two categories:
  94
  95 1. Generic properties (*OSFAMILY*, *ROOT_PARTITION*, *USERS*)
  96 2. Configuration tasks to run (*EXCLUDE_ALL_TASKS*, *EXCLUDE_TASK_<task_name>*)
  97    (see here for :ref:`valid configuration tasks <image-configuration-tasks>`)
  98
  99 A list of all properties follows:
 100
 101 Mandatory properties (for diskdump only)
 102 ++++++++++++++++++++++++++++++++++++++++
 103
 104  * **OSFAMILY={linux,windows}**
 105    This specifies whether the image is a Linux or a Windows Image.
 106    {ext,ntfs}dump formats are self descriptive regarding this property.
 107  * **ROOT_PARTITION=n**
 108    This specifies the partition number of the root partition. As mentioned
 109    earlier, for now, only primary partitions are supported. This property is
 110    trivial for {ext,ntfs}dump formats (they only host one partition).
 111
 112 Optional properties
 113 +++++++++++++++++++
 114
 115  * **USERS="username1 username2...."**
 116    This is a space-seperated list of users, whose password will be reset by
 117    *snf-image*. The use of this property is optional, but highly recommended.
 118    For now, if this property is missing, the users are chosen according to a
 119    set of rules, but those rules may change or even be dropped in the future.
 120    The rules we currently use are listed below:
 121
 122      * For Windows images, the *Administrator*'s password is reset.
 123      * For Linux and FreeBSD images, the *root* password is reset.
 124
 125  * **EXCLUDE_ALL_TASKS=yes**
 126    If this property is defined with a value other than null, then during the
 127    deployment, the image will not be configured at all. This is really handy
 128    because it gives the ability to deploy images hosting operating systems
 129    whose configuration is not supported by snf-image.
 130
 131  * **EXCLUDE_TASK_<task_name>=yes**
 132    This family of properties gives the ability to exclude individual
 133    configuration tasks from running. Hence, if the property
 134    *EXCLUDE_TASK_DeleteSSHKeys* with a value other than null is passed to
 135    *snf-image*, the aforementioned configuration step will not be executed, and
 136    the SSH Keys found in the image will not be removed during the deployment.
 137    Task exclusion provides great flexibility, but it needs to be used with
 138    great care. Tasks depend on each other and although those dependencies are
 139    well documented, automatic task dependency resolution isn't yet supported in
 140    *snf-image*. If you exclude task A but not task B which depends on A, you
 141    will probably end up with an unsuccessful deployment because B will fail and
 142    exit in an abnormal way. You can read more about configuration tasks here.
 143
 144 img_properties OS parameter
 145 +++++++++++++++++++++++++++
 146
 147 Image properties are passed to snf_image through the img_properties OS
 148 parameter as a simple json string like the one below:
 149
 150 | {
 151 |     "PROPERTY1": "VALUE1",
 152 |     "PROPERTY2": "VALUE2",
 153 |     "PROPERTY3": "VALUE3",
 154 |     ...
 155 |     ...
 156 |     ...
 157 |     "PROPERTYn": "VALUEn"
 158 | }
 159
 160
 161 A real life example for creating a new Ganeti instance and passing image
 162 properties to snf-image looks like this:
 163
 164 .. code-block:: console
 165
 166    ``gnt-instance add -O img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"2"\,"USERS":"root guest"}',img_format=diskdump,img_id=...``
 167
 168 .. _image-personality:
 169
 170 Image Personality (img_personality)
 171 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 172
 173 This parameter is an extension of the Server Personality notation proposed by
 174 the OpenStack Compute API v1.1 and defines a list of files to be injected into
 175 the image file system.
 176
 177 Format
 178 ++++++
 179
 180 The format of this parameter is a JSON array of objects. Each object in the
 181 array supports the following keys:
 182
 183  * **path**: The absolute path of the file (string)
 184  * **contents**: The content of the file encoded as a base64 string (string)
 185  * **owner**: The user ownership of the file (string)
 186  * **group**: The group ownership of the file (string)
 187  * **mode**: The permission mode of the file (number)
 188
 189 The first two (path, contents) are mandatory. The others (owner, group, mode)
 190 are optional and their default value is root, root and 0440 respectively.
 191
 192 Example
 193 +++++++
 194
 195 The JSON string below defines two files (*/tmp/test1*, */tmp/test2*) whose
 196 content is ``test1\n`` and ``test2\n``, they are both owned by *root:root* and
 197 their permissions are ``-rw-r--r--`` [#]_
 198
 199 | [
 200 |     {
 201 |         "path": "/tmp/test1",
 202 |         "contents": "dGVzdDENCg==",
 203 |         "owner": "root",
 204 |         "group": "root",
 205 |         "mode": 0644
 206 |     },
 207 |     {
 208 |         "path": "/tmp/test2",
 209 |         "contents": "dGVzdDINCg==",
 210 |         "owner": "root",
 211 |         "group": "root",
 212 |         "mode": 420
 213 |     }
 214 | ]
 215
 216 .. [#] The first mode is in octal representation and the second in decimal.