Statistics
| Branch: | Tag: | Revision:

root / docs / usage.rst @ b0ddf192

History | View | Annotate | Download (14.2 kB)

1
Usage
2
^^^^^
3

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

    
6
 * snf-image-creator: A non-interactive command line program
7
 * snf-mkimage: 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-image-creator receives the following options:
17

    
18
.. code-block:: console
19

    
20
   $ snf-image-creator --help
21
   Usage: snf-image-creator [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 pithos with name FILENAME
32
     -r IMAGENAME, --register=IMAGENAME
33
                           register the image with ~okeanos 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-sysprep       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
     --no-sysprep          don't perform any system preparation operation
53
     --no-shrink           don't shrink any partition
54
     --public              register image with cyclades as public
55
     --tmpdir=DIR          create large temporary image files under DIR
56

    
57
Most input options are self-describing. If you want to save a local copy of
58
the image you create, provide a filename using the *-o* option. To upload the
59
image to *pithos+*, provide valid cloud API access info (by either using a
60
token with *-t* and a URL with *-a* pair or a cloud name with *-c*) and a
61
filename using *-u*. If you also want to register the image with *~okeanos*, in
62
addition to *-u* provide a registration name using *-r*. All images are
63
registered as *private*. Only the user that registers the image can create
64
VM's out of it. If you want the image to be visible by other user too, use the
65
*--public* option.
66

    
67
By default, before extracting the image, snf-image-creator will perform a
68
number of system preparation operations on the snapshot of the media and will
69
shrink the last partition found. Both actions can be disabled by specifying
70
*--no-sysprep* and *--no-shrink* respectively.
71

    
72
If *--print-sysprep* is defined, the program will exit after printing a
73
list of enabled and disabled system preparation operation applicable to this
74
input media. The user can enable or disable specific *syspreps*, using
75
*-{enable,disable}-sysprep* options. The user may specify those options
76
multiple times.
77

    
78
Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a
79
debian system, we print the following output:
80

    
81
.. _sysprep:
82

    
83
.. code-block:: console
84

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

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

    
145
.. code-block:: console
146

    
147
   $ snf-image-creator --enable-sysprep cleanup-mail --enable-sysprep remove-user-accounts ...
148

    
149
Dialog-based version
150
====================
151

    
152
*snf-mkimage* receives the following options:
153

    
154
.. code-block:: console
155

    
156
 $ snf-mkimage --help
157
 Usage: snf-mkimage [options] [<input_media>]
158

    
159
 Options:
160
   --version             show program's version number and exit
161
   -h, --help            show this help message and exit
162
   -l FILE, --logfile=FILE
163
                         log all messages to FILE
164
   --tmpdir=DIR          create large temporary image files under DIR
165

    
166
If the input media is not specified in the command line, in the first dialog
167
box the user will be asked to specify it:
168

    
169
.. image:: /snapshots/select_media.png
170

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

    
175
After the input media is examined and the program is initialized, the user will
176
be given the choice to run *snf-mkimage* in *wizard* or *expert* mode.
177

    
178
Wizard mode
179
-----------
180

    
181
When *snf-mkimage* runs in *wizard* mode, the user is just asked to provide the
182
following basic information:
183

    
184
 * Cloud: The cloud account to use to upload and register the resulting image
185
 * Name: A short name for the image (ex. "Slackware")
186
 * Description: An one-line description for the image
187
   (ex. "Slackware Linux 14.0 with KDE")
188
 * Registration Type: Private or Public
189

    
190
After confirming, the image will be extracted, uploaded to *pithos+* and
191
registered with *~okeanos*. The user will also be given the choice to keep a
192
local copy of it.
193

    
194
For most users the functionality this mode provides should be sufficient.
195

    
196
Expert mode
197
-----------
198

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

    
202
.. image:: /snapshots/main_menu.png
203

    
204
In the *Customize* sub-menu the user can control:
205

    
206
 * The system preparation operations that will be applied on the media
207
 * Whether the image will be shrunk or not
208
 * The properties associated with the image
209
 * The configuration tasks that will run during image deployment
210

    
211
In the *Register* sub-menu the user can provide:
212

    
213
 * Which cloud account to use
214
 * A *pithos+* filename for the uploaded *diskdump* image
215
 * A name for the image to use when registering it with *~cyclades*, as well as
216
   the registration type (*private* or *public*)
217

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

    
222
Host bundling operation
223
=======================
224

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

    
233
Creating a new image
234
====================
235

    
236
Suppose you want to create a new Ubuntu server image. Download the installation
237
disk from the Internet:
238

    
239
.. code-block:: console
240

    
241
   $ wget http://ubuntureleases.tsl.gr/12.04.2/ubuntu-12.04.2-server-amd64.iso
242

    
243
Verify that it has been downloaded correctly:
244

    
245
.. code-block:: console
246

    
247
   $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17  ubuntu-12.04.2-server-amd64.iso' > check.md5
248
   $ md5sum -c check.md5
249

    
250
Create a 2G sparse file to host the new system:
251

    
252
.. code-block:: console
253

    
254
   $ truncate -s 2G ubuntu.raw
255

    
256
And install the Ubuntu system on this file:
257

    
258
.. code-block:: console
259

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

    
263
.. warning::
264

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

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

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

    
273
After you're done, you may use *snf-mkimage* as root to create and upload the
274
image:
275

    
276
.. code-block:: console
277

    
278
   $ sudo -s
279
   $ snf-mkimage ubuntu.raw
280

    
281
In the first screen you will be asked to choose if you want to run the program
282
in *Wizard* or *Expert* mode. Choose *Wizard*.
283

    
284
.. image:: /snapshots/wizard.png
285

    
286
Then you will be asked to provide a name, a description, a registration type
287
(*private* or *public*) and the authentication token corresponding to your
288
*~okeanos* account. Finally, you'll be asked to confirm the provided data.
289

    
290
.. image:: /snapshots/confirm.png
291

    
292
Choosing *YES* will create and upload the image to your *~okeanos* account.
293

    
294
Limitations
295
===========
296

    
297
Supported operating systems
298
---------------------------
299

    
300
*snf-image-creator* can only fully function on input media hosting *Linux*
301
systems. The program will detect the needed metadata and you may use it to
302
upload and register other *Unix* or *Windows* images, but you cannot use it to
303
shrink them or perform system preparation operations.
304

    
305
Logical Volumes
306
---------------
307

    
308
The program cannot work on LVM partitions [#f1]_. The input media may only
309
contain primary or logical partitions.
310

    
311
Para-virtualized drivers
312
------------------------
313

    
314
*~Okeanos* uses the *VirtIO* framework. The disk I/O controller and the
315
Ethernet cards on the VM instances are para-virtualized and need special
316
*VirtIO* drivers. Those drivers are included in the Linux Kernel mainline since
317
version 2.6.25 and are shipped with all the popular Linux distributions. The
318
problem is that if the driver for the para-virtualized disk I/O controller is
319
built as module, it needs to be preloaded using an initial ramdisk, otherwise
320
the VM won't be able to boot.
321

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

    
332
Some caveats on image creation
333
==============================
334

    
335
Image partition schemes and shrinking
336
-------------------------------------
337

    
338
When image shrinking is enabled, *snf-image-creator* will shrink the last
339
partition on the disk. If this is a swap partition, it will remove it, save
340
enough information to recreate it during image deployment and shrink the
341
partition that lays just before that. This will make the image smaller which
342
speeds up the deployment process.
343

    
344
During image deployment, the last partition is enlarged to occupy the available
345
space in the VM's hard disk and a swap partition is added at the end if a SWAP
346
image property is present.
347

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

    
352
Large temporary files
353
---------------------
354

    
355
*snf-image-creator* may create large temporary files when running:
356

    
357
 * During image shrinking, the input media snapshot file may reach the size of
358
   the original media.
359
 * When bundling the host system, the temporary image file may became as large
360
   as the rest of the disk files altogether.
361

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

    
371
.. rubric:: Footnotes
372

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