Statistics
| Branch: | Tag: | Revision:

root / docs / usage.rst @ ebe0f1e0

History | View | Annotate | Download (14.9 kB)

1
Usage
2
^^^^^
3

    
4
snf-image-creator comes in 2 variants:
5

    
6
 * snf-mkimage: A non-interactive command line program
7
 * snf-image-creator: A user-friendly dialog-based program
8

    
9
Both expect the input media as first argument. The input media may be a local
10
file, a block device or *"/"* if you want to create an image out of the running
11
system (see `host bundling operation`_).
12

    
13
Non-interactive version
14
=======================
15

    
16
snf-mkimage receives the following options:
17

    
18
.. code-block:: console
19

    
20
  $ snf-mkimage --help
21
  Usage: snf-mkimage [options] <input_media>
22

    
23
  Options:
24
    --version             show program's version number and exit
25
    -h, --help            show this help message and exit
26
    -o FILE, --outfile=FILE
27
                          dump image to FILE
28
    -f, --force           overwrite output files if they exist
29
    -s, --silent          output only errors
30
    -u FILENAME, --upload=FILENAME
31
                          upload the image to the cloud with name FILENAME
32
    -r IMAGENAME, --register=IMAGENAME
33
                          register the image with a cloud as IMAGENAME
34
    -m KEY=VALUE, --metadata=KEY=VALUE
35
                          add custom KEY=VALUE metadata to the image
36
    -t TOKEN, --token=TOKEN
37
                          use this authentication token when
38
                          uploading/registering images
39
    -a URL, --authentication-url=URL
40
                          use this authentication URL when uploading/registering
41
                          images
42
    -c CLOUD, --cloud=CLOUD
43
                          use this saved cloud account to authenticate against a
44
                          cloud when uploading/registering images
45
    --print-syspreps      print the enabled and disabled system preparation
46
                          operations for this input media
47
    --enable-sysprep=SYSPREP
48
                          run SYSPREP operation on the input media
49
    --disable-sysprep=SYSPREP
50
                          prevent SYSPREP operation from running on the input
51
                          media
52
    --print-sysprep-params
53
                          print the needed sysprep parameters for this input
54
                          media
55
    --sysprep-param=SYSPREP_PARAMS
56
                          Add KEY=VALUE system preparation parameter
57
    --no-sysprep          don't perform any system preparation operation
58
    --no-shrink           don't shrink any partition
59
    --public              register image with the cloud as public
60
    --tmpdir=DIR          create large temporary image files under DIR
61

    
62
Most input options are self-describing. If you want to save a local copy of
63
the image you create, provide a filename using the *-o* option. To upload the
64
image to the storage service of a cloud, provide valid cloud API access info
65
(by either using a token and a URL with *-t* and *-a* respectively, or a cloud
66
name with *-c*) and a remote filename using *-u*. If you also want to register
67
the image with the compute service of the cloud, in addition to *-u* provide a
68
registration name using *-r*. All images are
69
registered as *private*. Only the user that registers the image can create
70
VM's out of it. If you want the image to be visible by other user too, use the
71
*--public* option.
72

    
73
By default, before extracting the image, snf-mkimage will perform a
74
number of system preparation operations on the snapshot of the media and will
75
shrink the last partition found. Both actions can be disabled by specifying
76
*--no-sysprep* and *--no-shrink* respectively.
77

    
78
If *--print-sysprep* is defined, the program will exit after printing a
79
list of enabled and disabled system preparation operation applicable to this
80
input media. The user can enable or disable specific *syspreps*, using
81
*-{enable,disable}-sysprep* options. The user may specify those options
82
multiple times.
83

    
84
Running *snf-mkimage* with *--print-sysprep* on a raw file that hosts a
85
debian system, we print the following output:
86

    
87
.. _sysprep:
88

    
89
.. code-block:: console
90

    
91
   $ snf-mkimage --print-syspreps ubuntu.raw
92
   snf-image-creator 0.6
93
   =====================
94
   Examining source media `ubuntu_hd.raw' ... looks like an image file
95
   Snapshotting media source ... done
96
   Enabling recovery proc
97
   Launching helper VM (may take a while) ... done
98
   Inspecting Operating System ... ubuntu
99
   Mounting the media read-only ... done
100
   Collecting image metadata ... done
101
   Umounting the media ... done
102
   
103
   Enabled system preparation operations:
104
       cleanup-cache:
105
           Remove all regular files under /var/cache
106
   
107
       cleanup-log:
108
           Empty all files under /var/log
109
   
110
       cleanup-passwords:
111
           Remove all passwords and lock all user accounts
112
   
113
       cleanup-tmp:
114
           Remove all files under /tmp and /var/tmp
115
   
116
       cleanup-userdata:
117
           Delete sensitive userdata
118
   
119
       fix-acpid:
120
           Replace acpid powerdown action scripts to immediately shutdown the
121
           system without checking if a GUI is running.
122
   
123
       remove-persistent-net-rules:
124
           Remove udev rules that will keep network interface names persistent
125
           after hardware changes and reboots. Those rules will be created again
126
           the next time the image runs.
127
   
128
       remove-swap-entry:
129
           Remove swap entry from /etc/fstab. If swap is the last partition
130
           then the partition will be removed when shrinking is performed. If the
131
           swap partition is not the last partition in the disk or if you are not
132
           going to shrink the image you should probably disable this.
133
   
134
       use-persistent-block-device-names:
135
           Scan fstab & grub configuration files and replace all non-persistent
136
           device references with UUIDs.
137
   
138
   Disabled system preparation operations:
139
       cleanup-mail:
140
           Remove all files under /var/mail and /var/spool/mail
141
   
142
       remove-user-accounts:
143
           Remove all user accounts with id greater than 1000
144
   
145
   
146
   cleaning up ...
147

    
148
If you want the image to have all normal user accounts and all mail files
149
removed, you should use *--enable-sysprep* option like this:
150

    
151
.. code-block:: console
152

    
153
   $ snf-mkimage --enable-sysprep cleanup-mail --enable-sysprep remove-user-accounts ...
154

    
155
Dialog-based version
156
====================
157

    
158
*snf-image-creator* receives the following options:
159

    
160
.. code-block:: console
161

    
162
 $ snf-image-creator --help
163
 Usage: snf-image-creator [options] [<input_media>]
164

    
165
 Options:
166
   --version             show program's version number and exit
167
   -h, --help            show this help message and exit
168
   -l FILE, --logfile=FILE
169
                         log all messages to FILE
170
   --tmpdir=DIR          create large temporary image files under DIR
171

    
172
If the input media is not specified in the command line, in the first dialog
173
box the user will be asked to specify it:
174

    
175
.. image:: /snapshots/select_media.png
176

    
177
The user can select a file (regular or block device) or use the *Bundle Host*
178
button to create an image out of the running system (see
179
`Host bundling operation`_).
180

    
181
After the input media is examined and the program is initialized, the user will
182
be given the choice to run *snf-image-creator* in *wizard* or *expert* mode.
183

    
184
Wizard mode
185
-----------
186

    
187
When *snf-image-creator* runs in *wizard* mode, the user is just asked to provide the
188
following basic information:
189

    
190
 * Cloud: The cloud account to use to upload and register the resulting image
191
 * Name: A short name for the image (ex. "Slackware")
192
 * Description: An one-line description for the image
193
   (ex. "Slackware Linux 14.0 with KDE")
194
 * Registration Type: Private or Public
195

    
196
After confirming, the image will be extracted, uploaded to the storage service
197
and registered with the compute service of the selected cloud. The user will
198
also be given the choice to keep a local copy of it.
199

    
200
For most users the functionality this mode provides should be sufficient.
201

    
202
Expert mode
203
-----------
204

    
205
Expert mode allows the user to have better control on the image creation
206
process. The main menu can be seen in the picture below:
207

    
208
.. image:: /snapshots/main_menu.png
209

    
210
In the *Customize* sub-menu the user can control:
211

    
212
 * The system preparation operations that will be applied on the media
213
 * Whether the image will be shrunk or not
214
 * The properties associated with the image
215
 * The configuration tasks that will run during image deployment
216

    
217
In the *Register* sub-menu the user can provide:
218

    
219
 * Which cloud account to use
220
 * A filename for the uploaded *diskdump* image
221
 * A name for the image to use when registering it with the storage service of
222
   the cloud, as well as the registration type (*private* or *public*)
223

    
224
By choosing the *Extract* menu entry, the user can dump the image to the local
225
file system. Finally, if the user selects *Reset*, the system will ignore
226
all changes made so far and will start the image creation process again.
227

    
228
Host bundling operation
229
=======================
230

    
231
As a new feature in *v0.2*, snf-image-creator can create images out of the host
232
system that runs the program. This is done either by specifying / as input
233
media or by using the *Bundle Host* button in the media selection dialog of
234
snf-mkimage. During this operation, the files of the disk are copied into a
235
temporary image file, which means that the file system that will host the
236
temporary image needs to have a lot of free space (see `large temporary files`_
237
for more information).
238

    
239
Creating a new image
240
====================
241

    
242
Suppose your host system is a Debian Wheezy and you want to create a new Ubuntu
243
server image. Download the installation disk from the Internet:
244

    
245
.. code-block:: console
246

    
247
   $ wget http://ubuntureleases.tsl.gr/12.04.2/ubuntu-12.04.2-server-amd64.iso
248

    
249
Verify that it has been downloaded correctly:
250

    
251
.. code-block:: console
252

    
253
   $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17  ubuntu-12.04.2-server-amd64.iso' > check.md5
254
   $ md5sum -c check.md5
255

    
256
Create a 2G sparse file to host the new system:
257

    
258
.. code-block:: console
259

    
260
   $ truncate -s 2G ubuntu.raw
261

    
262
And install the Ubuntu system on this file:
263

    
264
.. code-block:: console
265

    
266
   $ sudo kvm -boot d -drive file=ubuntu.raw,format=raw,cache=none,if=virtio \
267
     -m 1G -cdrom ubuntu-12.04.2-server-amd64.iso
268

    
269
.. warning::
270

    
271
   During the installation, you will be asked about the partition scheme. Don't 
272
   use LVM partitions. They are not supported by snf-image-creator.
273

    
274
You will be able to boot your installed OS and make any changes you want
275
(e.g. install openssh-server) using the following command:
276

    
277
.. code-block:: console
278

    
279
   $ sudo kvm -m 1G -boot c -drive file=ubuntu.raw,format=raw,cache=none,if=virtio
280

    
281
After you're done, you may use *snf-image-creator* as root to create and upload the
282
image:
283

    
284
.. code-block:: console
285

    
286
   $ sudo -s
287
   $ snf-image-creator ubuntu.raw
288

    
289
In the first screen you will be asked to choose if you want to run the program
290
in *Wizard* or *Expert* mode. Choose *Wizard*.
291

    
292
.. image:: /snapshots/wizard.png
293

    
294
Then you will be asked to select a cloud and provide a name, a description and
295
a registration type (*private* or *public*). Finally, you'll be asked to
296
confirm the provided data.
297

    
298
.. image:: /snapshots/confirm.png
299

    
300
Choosing *YES* will create and upload the image to your cloud account.
301

    
302
Limitations
303
===========
304

    
305
Supported operating systems
306
---------------------------
307

    
308
*snf-image-creator* can only fully function on input media hosting *Linux*,
309
*FreeBSD* (tested on version 9.1) and *Windows* (Server 2008 R2 and Server
310
2012) systems. The program will detect the needed metadata and you may use it
311
to upload and register other *Unix* images, but you cannot use it to shrink
312
them or perform system preparation operations.
313

    
314
Logical Volumes
315
---------------
316

    
317
The program cannot work on LVM partitions [#f1]_. The input media may only
318
contain primary or logical partitions.
319

    
320
Para-virtualized drivers
321
------------------------
322

    
323
Most synnefo deployments uses the *VirtIO* framework. The disk I/O controller
324
and the Ethernet cards on the VM instances are para-virtualized and need
325
special *VirtIO* drivers. Those drivers are included in the Linux Kernel
326
mainline since version 2.6.25 and are shipped with all the popular Linux
327
distributions. The problem is that if the driver for the para-virtualized disk
328
I/O controller is built as module, it needs to be preloaded using an initial
329
ramdisk, otherwise the VM won't be able to boot.
330

    
331
Many popular Linux distributions, like Ubuntu and Debian, will automatically
332
create a generic initial ramdisk file that contains many different modules,
333
including the VirtIO drivers. Others that target more experienced users, like
334
Slackware, won't do that [#f2]_. *snf-image-creator* cannot resolve this kind
335
of problems and it's left to the user to do so. Please refer to your
336
distribution's documentation for more information on this. You can always check
337
if a system can boot with para-virtualized disk controller by launching it with
338
kvm using the *if=virtio* option (see the kvm command in the
339
`Creating a new image`_ section).
340

    
341
For Windows and FreeBSD systems, the needed drivers need to be manually
342
downloaded and installed on the media before the image creation process takes
343
place. For *FreeBSD* the virtio drivers can be found
344
`here <http://people.freebsd.org/~kuriyama/virtio/>`_. For Windows the drivers
345
are hosted by the
346
`Fedora Project <http://alt.fedoraproject.org/pub/alt/virtio-win/latest/images/>`_.
347

    
348
Some caveats on image creation
349
==============================
350

    
351
Image partition schemes and shrinking
352
-------------------------------------
353

    
354
When image shrinking is enabled, *snf-image-creator* will shrink the last
355
partition on the disk. If this is a swap partition, it will remove it, save
356
enough information to recreate it during image deployment and shrink the
357
partition that lays just before that. This will make the image smaller which
358
speeds up the deployment process.
359

    
360
During image deployment, the last partition is enlarged to occupy the available
361
space in the VM's hard disk and a swap partition is added at the end if a SWAP
362
image property is present.
363

    
364
Keep this in mind when creating images. It's always better to have your swap
365
partition placed as the last partition on the disk and have your largest
366
partition (*/* or */home*) just before that.
367

    
368
Large temporary files
369
---------------------
370

    
371
*snf-image-creator* may create large temporary files when running:
372

    
373
 * During image shrinking, the input media snapshot file may reach the size of
374
   the original media.
375
 * When bundling the host system, the temporary image file may became as large
376
   as the rest of the disk files altogether.
377

    
378
*/tmp* directory is not a good place for hosting large files. In many systems
379
the contents of */tmp* are stored in volatile memory and the size they may occupy
380
is limited. By default, *snf-image-creator* will use a heuristic approach to
381
determine where to store large temporary files. It will examine the free space
382
under */var/tmp*, the user's home directory and */mnt* and will pick the one
383
with the most available space. The user may overwrite this behaviour and
384
indicate a different directory using the *tmpdir* option. This option is
385
supported by both *snf-image-creator* and *snf-mkimage*.
386

    
387
.. rubric:: Footnotes
388

    
389
.. [#f1] http://sourceware.org/lvm2/
390
.. [#f2] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd