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

   1 Usage
   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
  85 ^^^^^^^^^^^^^^^^
  86
  87 In order for *snf-image* to be able to properly configure an image, it may make
  88 use of a set of image properties. Those image properties are passed to
  89 *snf-image* by Ganeti through the *img_poroperties* OS parameter (see Ganeti OS
  90 Interface). The name of all image properties is case-insensitive. For the
  91 diskdump format some properties are mandatory. For {ext,ntfs}dump formats all
  92 image properties are optional.
  93
  94 A list of mandatory and optional properties follows:
  95
  96 Mandatory properties (diskdump only)
  97 ++++++++++++++++++++++++++++++++++++
  98
  99  * **OSFAMILY={linux,windows}**
 100    This specifies whether the image is a Linux or a Windows Image.
 101    {ext,ntfs}dump formats are self descriptive regarding this property.
 102  * **ROOT_PARTITION=n**
 103    This specifies the partition number of the root partition. As mentioned
 104    earlier, for now, only primary partitions are supported. This property is
 105    trivial for {ext,ntfs}dump formats (they only host one partition).
 106
 107 Optional properties
 108 +++++++++++++++++++
 109
 110  * **USERS="username1 username2...."**
 111    This is a space-seperated list of users, whose password will be reset by
 112    *snf-image*. The use of this property is optional, but highly recommended.
 113    For now, if this property is missing, the users are chosen according to a
 114    set of rules, but those rules may change or even be dropped in the future.
 115    The rules we currently use are listed below:
 116
 117      * For Windows images, the *Administrator*'s password is reset.
 118      * For Linux and FreeBSD images, the *root* password is reset.
 119
 120  * **EXCLUDE_ALL_TASKS=yes**
 121    If this property is defined with a value other than null, then during the
 122    deployment, the image will not be configured at all. This is really handy
 123    because it gives the ability to deploy images hosting operating systems
 124    whose configuration is not supported by snf-image.
 125
 126  * **EXCLUDE_TASK_<task_name>=yes**
 127    This family of properties gives the ability to exclude individual
 128    configuration tasks from running. Hence, if the property
 129    *EXCLUDE_TASK_DeleteSSHKeys* with a value other than null is passed to
 130    *snf-image*, the aforementioned configuration step will not be executed, and
 131    the SSH Keys found in the image will not be removed during the deployment.
 132    Task exclusion provides great flexibility, but it needs to be used with
 133    great care. Tasks depend on each other and although those dependencies are
 134    well documented, automatic task dependency resolution isn't yet supported in
 135    *snf-image*. If you exclude task A but not task B which depends on A, you
 136    will probably end up with an unsuccessful deployment because B will fail and
 137    exit in an abnormal way. You can read more about configuration tasks here.
 138
 139
 140 img_properties OS parameter
 141 +++++++++++++++++++++++++++++++
 142
 143 Image properties are passed to snf_image through the img_properties OS
 144 parameter as a simple json string like the one below:
 145
 146 | {
 147 |     "PROPERTY1": "VALUE1",
 148 |     "PROPERTY2": "VALUE2",
 149 |     "PROPERTY3": "VALUE3",
 150 |     ...
 151 |     ...
 152 |     ...
 153 |     "PROPERTYn": "VALUEn"
 154 | }
 155
 156
 157 A real life example for creating a new ganeti instance and passing image
 158 properties to snf-image would probably look more like this:
 159
 160 ``gnt-instance add -O img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"2"\,"USERS":"root guest"}',img_format=diskdump...``
 161
 162 .. _image-personality:
 163
 164 Personality OS Parameter
 165 ^^^^^^^^^^^^^^^^^^^^^^^^
 166
 167 This parameter is an extension of the Server Personality notation proposed by
 168 the OpenStack Compute API v1.1 and defines a list of files to be injected into
 169 the image file system.
 170
 171 Format
 172 ++++++
 173
 174 The format of this parameter is a JSON array of objects. Each object in the
 175 array supports the following keys:
 176
 177  * **path**: The absolute path of the file (string)
 178  * **contents**: The content of the file encoded as a base64 string (string)
 179  * **owner**: The user ownership of the file (string)
 180  * **group**: The group ownership of the file (string)
 181  * **mode**: The permission mode of the file (number)
 182
 183 The first two (path, contents) are mandatory. The others (owner, group, mode)
 184 are optional and their default value is root, root and 0440 respectively.
 185
 186 Example
 187 +++++++
 188
 189 The JSON string below defines two files (*/tmp/test1*, */tmp/test2*) whose
 190 content is ``test1\n`` and ``test2\n``, they are both owned by *root:root* and
 191 their permissions are ``-rw-r--r--`` [#]_
 192
 193 | [
 194 |     {
 195 |         "path": "/tmp/test1",
 196 |         "contents": "dGVzdDENCg==",
 197 |         "owner": "root",
 198 |         "group": "root",
 199 |         "mode": 0644
 200 |     },
 201 |     {
 202 |         "path": "/tmp/test2",
 203 |         "contents": "dGVzdDINCg==",
 204 |         "owner": "root",
 205 |         "group": "root",
 206 |         "mode": 420
 207 |     }
 208 | ]
 209
 210 .. [#] The first mode is in octal representation and the second in decimal.
 211
 212
 213 .. _sample-images:
 214
 215 Sample Images
 216 ^^^^^^^^^^^^^
 217
 218 While developing *snf-image*, we created and tested a number of images. The
 219 following images are basic installations of some popular Linux distributions,
 220 that have been tested with snf-image and provided here for testing purposes:
 221
 222
 223  * Debian Squeeze Base System
 224    [`diskdump <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump>`_]
 225    [`md5sum <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump.md5sum>`_]
 226    [`metadata <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump.meta>`_]
 227  * Debian Wheezy Base System
 228    [`diskdump <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump>`_]
 229    [`md5sum <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump.md5sum>`_]
 230    [`metadata <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump.meta>`_]
 231  * Debian Desktop
 232    [`diskdump <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump>`_]
 233    [`md5sum <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump.md5sum>`_]
 234    [`metadata <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump.meta>`_]
 235  * CentOS 6.0
 236    [`diskdump <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump>`_]
 237    [`md5sum <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump.md5sum>`_]
 238    [`metadata <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump.meta>`_]
 239  * Fedora Desktop 18
 240    [`diskdump <http://cdn.synnefo.org/fedora-18-x86_64.diskdump>`_]
 241    [`md5sum <http://cdn.synnefo.org/fedora-18-x86_64.diskdump.md5sum>`_]
 242    [`metadata <http://cdn.synnefo.org/fedora-18-x86_64.diskdump.meta>`_]
 243  * Ubuntu Desktop LTS 12.04
 244    [`diskdump <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump>`_]
 245    [`md5sum <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump.md5sum>`_]
 246    [`metadata <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump.meta>`_]
 247  * Kubuntu LTS 12.04
 248    [`diskdump <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump>`_]
 249    [`md5sum <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump.md5sum>`_]
 250    [`metadata <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump.meta>`_]
 251  * Ubuntu Desktop 13.04
 252    [`diskdump <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump>`_]
 253    [`md5sum <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump.md5sum>`_]
 254    [`metadata <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump.meta>`_]
 255  * Kubuntu 13.04
 256    [`diskdump <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump>`_]
 257    [`md5sum <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump.md5sum>`_]
 258    [`metadata <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump.meta>`_]
 259  * Ubuntu Server 12.04
 260    [`diskdump <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump>`_]
 261    [`md5sum <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump.md5sum>`_]
 262    [`metadata <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump.meta>`_]
 263  * OpenSUSE Desktop 12.3
 264    [`diskdump <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump>`_]
 265    [`md5sum <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump.md5sum>`_]
 266    [`metadata <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump.meta>`_]
 267  * FreeBSD 9.1
 268    [`diskdump <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump>`_]
 269    [`md5sum <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.md5sum>`_]
 270    [`metadata <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.meta>`_]
 271
 272 Sample Usage
 273 ^^^^^^^^^^^^
 274
 275 Download an Image
 276 +++++++++++++++++
 277
 278 Download a :ref:`Sample Image <sample-images>` and store it under IMAGE_DIR.
 279 Make sure you also have its corresponding metadata file.
 280
 281 Spawn a diskdump image
 282 ++++++++++++++++++++++
 283
 284 If you want to deploy an image of type diskdump, you need to provide the
 285 corresponding *img_properties* as described in the
 286 :ref:`Image Format<image-format>` section. If using a diskdump found in the
 287 :ref:`sample-images` list, use the *img_properties* described in the image's
 288 metadata file. For example:
 289
 290 ``gnt-instance add -o snf-image+default --os-parameters img_passwd=SamplePassw0rd,img_format=diskdump,img_id=debian_base-6.0-7-x86_64,img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"1"}' -t plain --disk=0:size=10G --no-name-check --no-ip-check --no-nics test1``
 291