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 ``local://``, 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).
  52
  53   | For example, if we want to deploy the image file:
  54   | ``/var/lib/snf-image/slackware.diskdump``
  55   | We need to assign:
  56   | ``img_format=diskdump`` and ``img_id=file://slackware.diskdump``
  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
  63   | For example, if we want to deploy an image from an http location:
  64   | ``img_id=http://www.synnefo.org/path/to/image/slackware-image``
  65
  66  * **Pithos backend**:
  67    If the **img_id** is prefixed with ``pithos://`` or ``pithosmap://`` the
  68    image is considered to reside on a Pithos deployment. For ``pithosmap://``
  69    images, the user needs to have set a valid value for the
  70    ``PITHOS_DATA`` variable in snf-image's configuration file
  71    (``/etc/default/snf-image`` by default). For ``pithos://`` images, in
  72    addition to ``PITHOS_DATA``, the user needs to have set a valid value for the
  73    ``PITHOS_DB`` variable, too.
  74
  75   | For example, if we want to deploy using a full Pithos URI:
  76   | ``img_id=pithos://<user-uuid>/<container>/<slackware-image>``
  77   | or if we already know the map:
  78   | ``img_id=pithosmap://<slackware-image-map-name>``
  79
  80  * **Null backend**:
  81    To select the Null backend and skip the fetching and extraction step, we set
  82    ``img_id=null``.
  83
  84 .. _image-properties:
  85
  86 Image Properties (img_properties)
  87 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  88
  89 *snf-image* may use a number of properties to properly configure the image.
  90 Those image properties are passed to snf-image by Ganeti through the
  91 *img_poroperties* OS parameter (see Ganeti OS Interface). The name of all image
  92 properties is case-insensitive. For the diskdump format some properties are
  93 mandatory. For {ext,ntfs}dump formats all image properties are optional.
  94
  95 We can group image properties in two categories:
  96
  97 1. Generic properties (*OSFAMILY*, *ROOT_PARTITION*, *USERS*)
  98 2. Configuration tasks to run (*EXCLUDE_ALL_TASKS*, *EXCLUDE_TASK_<task_name>*)
  99    (see here for :ref:`valid configuration tasks <image-configuration-tasks>`)
 100
 101 A list of all properties follows:
 102
 103 Mandatory properties (for diskdump only)
 104 ++++++++++++++++++++++++++++++++++++++++
 105
 106  * **OSFAMILY={linux,windows}**
 107    This specifies whether the image is a Linux or a Windows Image.
 108    {ext,ntfs}dump formats are self descriptive regarding this property.
 109  * **ROOT_PARTITION=n**
 110    This specifies the partition number of the root partition. As mentioned
 111    earlier, for now, only primary partitions are supported. This property is
 112    trivial for {ext,ntfs}dump formats (they only host one partition).
 113
 114 Optional properties
 115 +++++++++++++++++++
 116
 117  * **USERS="username1 username2...."**
 118    This is a space-separated list of users, whose password will be reset by
 119    *snf-image*. The use of this property is optional, but highly recommended.
 120    For now, if this property is missing, the users are chosen according to a
 121    set of rules, but those rules may change or even be dropped in the future.
 122    The rules we currently use are listed below:
 123
 124      * For Windows images, the *Administrator*'s password is reset.
 125      * For Linux and FreeBSD images, the *root* password is reset.
 126
 127  * **EXCLUDE_ALL_TASKS=yes**
 128    If this property is defined with a value other than null, then during the
 129    deployment, the image will not be configured at all. This is really handy
 130    because it gives the ability to deploy images hosting operating systems
 131    whose configuration is not supported by snf-image.
 132
 133  * **EXCLUDE_TASK_<task_name>=yes**
 134    This family of properties gives the ability to exclude individual
 135    configuration tasks from running. Hence, if the property
 136    *EXCLUDE_TASK_DeleteSSHKeys* with a value other than null is passed to
 137    *snf-image*, the aforementioned configuration step will not be executed, and
 138    the SSH Keys found in the image will not be removed during the deployment.
 139    Task exclusion provides great flexibility, but it needs to be used with
 140    great care. Tasks depend on each other and although those dependencies are
 141    well documented, automatic task dependency resolution isn't yet supported in
 142    *snf-image*. If you exclude task A but not task B which depends on A, you
 143    will probably end up with an unsuccessful deployment because B will fail and
 144    exit in an abnormal way. You can read more about configuration tasks here.
 145
 146 img_properties OS parameter
 147 +++++++++++++++++++++++++++
 148
 149 Image properties are passed to snf_image through the img_properties OS
 150 parameter as a simple json string like the one below:
 151
 152 | {
 153 |     "PROPERTY1": "VALUE1",
 154 |     "PROPERTY2": "VALUE2",
 155 |     "PROPERTY3": "VALUE3",
 156 |     ...
 157 |     ...
 158 |     ...
 159 |     "PROPERTYn": "VALUEn"
 160 | }
 161
 162
 163 A real life example for creating a new Ganeti instance and passing image
 164 properties to snf-image looks like this:
 165
 166 .. code-block:: console
 167
 168    ``gnt-instance add -O img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"2"\,"USERS":"root guest"}',img_format=diskdump,img_id=...``
 169
 170 .. _image-personality:
 171
 172 Image Personality (img_personality)
 173 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 174
 175 This parameter is an extension of the Server Personality notation proposed by
 176 the OpenStack Compute API v1.1 and defines a list of files to be injected into
 177 the image file system.
 178
 179 Format
 180 ++++++
 181
 182 The format of this parameter is a JSON array of objects. Each object in the
 183 array supports the following keys:
 184
 185  * **path**: The absolute path of the file (string)
 186  * **contents**: The content of the file encoded as a base64 string (string)
 187  * **owner**: The user ownership of the file (string)
 188  * **group**: The group ownership of the file (string)
 189  * **mode**: The permission mode of the file (number)
 190
 191 The first two (path, contents) are mandatory. The others (owner, group, mode)
 192 are optional and their default value is root, root and 0440 respectively.
 193
 194 Example
 195 +++++++
 196
 197 The JSON string below defines two files (*/tmp/test1*, */tmp/test2*) whose
 198 content is ``test1\n`` and ``test2\n``, they are both owned by *root:root* and
 199 their permissions are ``-rw-r--r--`` [#]_
 200
 201 | [
 202 |     {
 203 |         "path": "/tmp/test1",
 204 |         "contents": "dGVzdDENCg==",
 205 |         "owner": "root",
 206 |         "group": "root",
 207 |         "mode": 0644
 208 |     },
 209 |     {
 210 |         "path": "/tmp/test2",
 211 |         "contents": "dGVzdDINCg==",
 212 |         "owner": "root",
 213 |         "group": "root",
 214 |         "mode": 420
 215 |     }
 216 | ]
 217
 218 .. [#] The first mode is in octal representation and the second in decimal.