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
  25 ^^^^^^^^^^^^
  26
  27 Right now 3 different types of image formats are supported:
  28
  29  * **extdump**: a raw dump of an ext{2,3,4} file system
  30  * **ntfsdump**: a raw dump of an NTFS file system
  31  * **diskdump**: a raw dump of a disk
  32
  33 extdump and ntfsdump image formats
  34 ++++++++++++++++++++++++++++++++++
  35
  36 Those two formats are dumps (raw copies using dd) of partitions hosting Linux
  37 systems on ext{2,3,4} and Windows systems on ntfs file systems respectively.
  38 Partitions hosting a Windows or Linux system that are suitable for dumping
  39 should have the following properties:
  40
  41  * Be the first partition in the file system
  42  * The OS they host should not depend on any other partitions
  43  * Start at sector 2048
  44  * Have a boot loader installed in the boot sector of the partition (not MBR)
  45  * Have the root device in */etc/fstab* specified in a persistent way, using
  46    UUID or LABEL (for extdump only)
  47
  48 Known Issues
  49 ------------
  50
  51  * For Linux systems, having grub installed in the partition is fragile and
  52    things can go wrong when resizing the partitions, especially when shrinking.
  53  * More complicated partition schemes are not supported.
  54
  55 diskdump image format
  56 +++++++++++++++++++++
  57
  58 Diskdump is a newer format that overcomes most of the aforementioned issues.
  59 This format is a dump (raw copy using dd) of a whole disk.
  60
  61 This design decision has the following benefits:
  62
  63  * Swap partitions are supported
  64  * The system may use multiple partitions:
  65     * dedicated partitions for /boot, /home etc in Linux
  66     * system and boot partition in Windows
  67  * There are no restrictions on starting sectors of partitions
  68
  69 Although diskdump is a lot more flexible than the older formats, there are
  70 still some rules to follow:
  71
  72  * All devices in fstab should be specified by persistent names (UUID or LABEL)
  73  * LVMs are not supported
  74  * For Linux disks only ext{2,3,4} file systems are supported
  75  * For FreeBSD disks only UFS file systems are supported
  76  * For FreeBSD only GUID Partition Tables (GPT) are supported
  77
  78 .. _image-id:
  79
  80 Image IDs & Storage back-ends
  81 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  82
  83 *snf-image* can use images that are stored in a variety of different back-ends.
  84 The back-end to be used is determined by the value passed by the *img_id* OS
  85 parameter. The following back-ends are supported:
  86
  87  * **Local back-end**:
  88    The local back-end is used to retrieve images that are stored in the ganeti
  89    node that the image deployment takes place. The local back-end is used if
  90    the value of the *img_id* ganeti OS parameter is either prefixed with
  91    *file://* or is not prefixed at all. All local images are expected to be
  92    found under a predifined image directory. By default */var/lib/snf-image* is
  93    used, but the user can change thi directory by overwriting the value of the
  94    *IMAGE_DIR* variable under */etc/default/snf-image*. The name of the image
  95    file is created by adding the image type extension in the end of the
  96    *img_id*. If the *img_id* for example is *file://slackware* and the image
  97    type is *diskdump*, snf-image will expect to find an image file under the
  98    following path: ``/usr/lib/snf-image/slackware.diskdump``
  99
 100  * **Network back-end**:
 101    The network back-end is used to retrieve images that are accessible from the
 102    network. If the *imd_id* starts with *http:*, *https:*, *ftp:* or *ftps:*,
 103    snf-image will treat the *img_id* as a remote URL and will try to fetch the
 104    image using `cURL <http://curl.haxx.se/>`_.
 105
 106  * **Pithos back-end**:
 107    If an *img_id* is prefixed with *pithos:* or *pithosmap:*, the image is
 108    considered to be pithos back-ended. *snf-image* contains a special
 109    command-line tool (*pithcat*) for retrieving this kind of images. For
 110    *pithosmap:* images, the user needs to have set a valid value for the
 111    *PITHOS_DATA* variable. For *pithos:* images, in addition to PITHOS_DATA,
 112    the PITHOS_DB variable needs to contain a valid value.
 113    */etc/default/snf-image* may be used to set both values.
 114
 115  * **Null back-end**:
 116    The null back-end is used if the *img_id* value is *null*. In this case no
 117    image copying is performed. This is handy if the hard disk already contains
 118    the image data before *snf-image* is executed (for example if the hard disk
 119    is a snapshot of an existing VM's hard disk).
 120
 121 .. _image-properties:
 122
 123 Image Properties
 124 ^^^^^^^^^^^^^^^^
 125
 126 In order for snf-image to be able to properly configure an image, it may make
 127 use of a set of image properties. Those image properties are passed to
 128 snf-image by Ganeti through the img_poroperties OS parameter (see Ganeti OS
 129 Interface). The name of all image properties is case-insensitive. For the
 130 diskdump format some properties are mandatory. For {ext,ntfs}dump formats all
 131 image properties are optional.
 132
 133 A list of mandatory and optional properties follows:
 134
 135 Mandatory properties (diskdump only)
 136 ++++++++++++++++++++++++++++++++++++
 137
 138  * **OSFAMILY={linux,windows}**
 139    This specifies whether the image is a Linux or a Windows Image.
 140    {ext,ntfs}dump formats are self descriptive regarding this property.
 141  * **ROOT_PARTITION=n**
 142    This specifies the partition number of the root partition. As mentioned
 143    earlier, for now, only primary partitions are supported. This property is
 144    trivial for {ext,ntfs}dump formats (they only host one partition).
 145
 146 Optional properties
 147 +++++++++++++++++++
 148
 149  * **USERS="username1 username2...."**
 150    This is a space-seperated list of users, whose password will be reset by
 151    *snf-image*. The use of this property is optional, but highly recommended.
 152    For now, if this property is missing, the users are chosen according to a
 153    set of rules, but those rules may change or even be dropped in the future.
 154    The rules we currently use are listed below:
 155
 156      * For Windows images, the *Administrator*'s password is reset.
 157      * For Linux and FreeBSD images, the *root* password is reset.
 158
 159  * **EXCLUDE_ALL_TASKS=yes**
 160    If this property is defined with a value other than null, then during the
 161    deployment, the image will not be configured at all. This is really handy
 162    because it gives the ability to deploy images hosting operating systems
 163    whose configuration is not supported by snf-image.
 164
 165  * **EXCLUDE_TASK_<task_name>=yes**
 166    This family of properties gives the ability to exclude individual
 167    configuration tasks from running. Hence, if the property
 168    *EXCLUDE_TASK_DeleteSSHKeys* with a value other than null is passed to
 169    *snf-image*, the aforementioned configuration step will not be executed, and
 170    the SSH Keys found in the image will not be removed during the deployment.
 171    Task exclusion provides great flexibility, but it needs to be used with
 172    great care. Tasks depend on each other and although those dependencies are
 173    well documented, automatic task dependency resolution isn't yet supported in
 174    *snf-image*. If you exclude task A but not task B which depends on A, you
 175    will probably end up with an unsuccessful deployment because B will fail and
 176    exit in an abnormal way. You can read more about configuration tasks here.
 177
 178
 179 img_properties OS parameter
 180 +++++++++++++++++++++++++++++++
 181
 182 Image properties are passed to snf_image through the img_properties OS
 183 parameter as a simple json string like the one below:
 184
 185 | {
 186 |     "PROPERTY1": "VALUE1",
 187 |     "PROPERTY2": "VALUE2",
 188 |     "PROPERTY3": "VALUE3",
 189 |     ...
 190 |     ...
 191 |     ...
 192 |     "PROPERTYn": "VALUEn"
 193 | }
 194
 195
 196 A real life example for creating a new ganeti instance and passing image
 197 properties to snf-image would probably look more like this:
 198
 199 ``gnt-instance add -O img_properties='{"OSFAMILY":"linux"\,"ROOT_PARTITION":"2"\,"USERS":"root guest"}',img_format=diskdump...``
 200
 201 .. _image-personality:
 202
 203 Personality OS Parameter
 204 ^^^^^^^^^^^^^^^^^^^^^^^^
 205
 206 This parameter is an extension of the Server Personality notation proposed by
 207 the OpenStack Compute API v1.1 and defines a list of files to be injected into
 208 the image file system.
 209
 210 Format
 211 ++++++
 212
 213 The format of this parameter is a JSON array of objects. Each object in the
 214 array supports the following keys:
 215
 216  * **path**: The absolute path of the file (string)
 217  * **contents**: The content of the file encoded as a base64 string (string)
 218  * **owner**: The user ownership of the file (string)
 219  * **group**: The group ownership of the file (string)
 220  * **mode**: The permission mode of the file (number)
 221
 222 The first two (path, contents) are mandatory. The others (owner, group, mode)
 223 are optional and their default value is root, root and 0440 respectively.
 224
 225 Example
 226 +++++++
 227
 228 The JSON string below defines two files (*/tmp/test1*, */tmp/test2*) whose
 229 content is ``test1\n`` and ``test2\n``, they are both owned by *root:root* and
 230 their permissions are ``-rw-r--r--`` [#]_
 231
 232 | [
 233 |     {
 234 |         "path": "/tmp/test1",
 235 |         "contents": "dGVzdDENCg==",
 236 |         "owner": "root",
 237 |         "group": "root",
 238 |         "mode": 0644
 239 |     },
 240 |     {
 241 |         "path": "/tmp/test2",
 242 |         "contents": "dGVzdDINCg==",
 243 |         "owner": "root",
 244 |         "group": "root",
 245 |         "mode": 420
 246 |     }
 247 | ]
 248
 249 .. [#] The first mode is in octal representation and the second in decimal.
 250
 251
 252 .. _sample-images:
 253
 254 Sample Images
 255 ^^^^^^^^^^^^^
 256
 257 While developing *snf-image*, we created and tested a number of images. The
 258 following images are basic installations of some popular Linux distributions,
 259 that have been tested with snf-image and provided here for testing purposes:
 260
 261
 262  * Debian Squeeze Base System
 263    [`diskdump <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump>`_]
 264    [`md5sum <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump.md5sum>`_]
 265    [`metadata <http://cdn.synnefo.org/debian_base-6.0-x86_64.diskdump.meta>`_]
 266  * Debian Wheezy Base System
 267    [`diskdump <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump>`_]
 268    [`md5sum <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump.md5sum>`_]
 269    [`metadata <http://cdn.synnefo.org/debian_base-7.0-x86_64.diskdump.meta>`_]
 270  * Debian Desktop
 271    [`diskdump <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump>`_]
 272    [`md5sum <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump.md5sum>`_]
 273    [`metadata <http://cdn.synnefo.org/debian_desktop-7.0-x86_64.diskdump.meta>`_]
 274  * CentOS 6.0
 275    [`diskdump <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump>`_]
 276    [`md5sum <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump.md5sum>`_]
 277    [`metadata <http://cdn.synnefo.org/centos-6.0-x86_64.diskdump.meta>`_]
 278  * Fedora Desktop 18
 279    [`diskdump <http://cdn.synnefo.org/fedora-18-x86_64.diskdump>`_]
 280    [`md5sum <http://cdn.synnefo.org/fedora-18-x86_64.diskdump.md5sum>`_]
 281    [`metadata <http://cdn.synnefo.org/fedora-18-x86_64.diskdump.meta>`_]
 282  * Ubuntu Desktop LTS 12.04
 283    [`diskdump <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump>`_]
 284    [`md5sum <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump.md5sum>`_]
 285    [`metadata <http://cdn.synnefo.org/ubuntu_desktop-12.04-x86_64.diskdump.meta>`_]
 286  * Kubuntu LTS 12.04
 287    [`diskdump <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump>`_]
 288    [`md5sum <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump.md5sum>`_]
 289    [`metadata <http://cdn.synnefo.org/kubuntu_desktop-12.04-x86_64.diskdump.meta>`_]
 290  * Ubuntu Desktop 13.04
 291    [`diskdump <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump>`_]
 292    [`md5sum <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump.md5sum>`_]
 293    [`metadata <http://cdn.synnefo.org/ubuntu_desktop-13.04-x86_64.diskdump.meta>`_]
 294  * Kubuntu 13.04
 295    [`diskdump <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump>`_]
 296    [`md5sum <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump.md5sum>`_]
 297    [`metadata <http://cdn.synnefo.org/kubuntu_desktop-13.04-x86_64.diskdump.meta>`_]
 298  * Ubuntu Server 12.04
 299    [`diskdump <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump>`_]
 300    [`md5sum <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump.md5sum>`_]
 301    [`metadata <http://cdn.synnefo.org/ubuntu_server-12.04-x86_64.diskdump.meta>`_]
 302  * OpenSUSE Desktop 12.3
 303    [`diskdump <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump>`_]
 304    [`md5sum <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump.md5sum>`_]
 305    [`metadata <http://cdn.synnefo.org/opensuse_desktop-12.3-x86_64.diskdump.meta>`_]
 306  * FreeBSD 9.1
 307    [`diskdump <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump>`_]
 308    [`md5sum <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.md5sum>`_]
 309    [`metadata <http://cdn.synnefo.org/freebsd-9.1-x86_64.diskdump.meta>`_]
 310
 311 Sample Usage
 312 ^^^^^^^^^^^^
 313
 314 Download an Image
 315 +++++++++++++++++
 316
 317 Download a :ref:`Sample Image <sample-images>` and store it under IMAGE_DIR.
 318 Make sure you also have its corresponding metadata file.
 319
 320 Spawn a diskdump image
 321 ++++++++++++++++++++++
 322
 323 If you want to deploy an image of type diskdump, you need to provide the
 324 corresponding *img_properties* as described in the
 325 :ref:`Image Format<image-format>` section. If using a diskdump found in the
 326 :ref:`sample-images` list, use the *img_properties* described in the image's
 327 metadata file. For example:
 328
 329 ``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``
 330