Statistics
| Branch: | Tag: | Revision:

root / docs / usage.rst @ 6f9e1534

History | View | Annotate | Download (13.3 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
   -a ACCOUNT, --account=ACCOUNT
35
                         use this ACCOUNT when uploading/registering images
36
                         [Default: None]
37
   -m KEY=VALUE, --metadata=KEY=VALUE
38
                         add custom KEY=VALUE metadata to the image
39
   -t TOKEN, --token=TOKEN
40
                         use this token when uploading/registering images
41
                         [Default: None]
42
   --print-sysprep       print the available enabled and disabled system
43
                         preparation operations for this input media
44
   --enable-sysprep=SYSPREP
45
                         run SYSPREP operation on the input media
46
   --disable-sysprep=SYSPREP
47
                         prevent SYSPREP operation from running on the input
48
                         media
49
   --no-sysprep          don't perform any system preparation operation
50
   --no-shrink           don't shrink the image
51
   --tmpdir=DIR          create large temporary image files under DIR
52

    
53
Most input options are self-describing. If you want to save a local copy of
54
the image you create, provide a filename using the *-o* option. To upload the
55
image to *pithos+*, provide valid credentials using *-a* and *-t* and a
56
filename using *-u*. If you also want to register the image with *~okeanos*, in
57
addition to *-u* provide a registration name using *-r*.
58

    
59
By default, before extracting the image, snf-image-creator will perform a
60
number of system preparation operations on the snapshot of the media and will
61
shrink the last partition found. Both actions can be disabled by specifying
62
*--no-sysprep* and *--no-shrink* respectively.
63

    
64
If *--print-sysprep* is defined, the program will exit after printing a
65
list of enabled and disabled system preparation operation applicable to this
66
input media. The user can enable or disable specific *syspreps*, using
67
*-{enable,disable}-sysprep* options. The user may specify those options
68
multiple times.
69

    
70
Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a
71
debian system, we print the following output:
72

    
73
.. _sysprep:
74

    
75
.. code-block:: console
76

    
77
   $ snf-image-creator --print-sysprep debian_desktop.img
78

    
79
   snf-image-creator 0.1
80
   =====================
81
   Examining source media `debian_desktop.img'... looks like an image file
82
   Snapshotting media source... done
83
   Enabling recovery proc
84
   Launching helper VM... done
85
   Inspecting Operating System... found a(n) debian system
86
   Mounting the media read-only... done
87

    
88
   Enabled system preparation operations:
89
       cleanup-cache:
90
   	Remove all regular files under /var/cache
91

    
92
       cleanup-log:
93
   	Empty all files under /var/log
94

    
95
       cleanup-passwords:
96
   	Remove all passwords and lock all user accounts
97

    
98
       cleanup-tmp:
99
   	Remove all files under /tmp and /var/tmp
100

    
101
       cleanup-userdata:
102
   	Delete sensitive userdata
103

    
104
       fix-acpid:
105
   	Replace acpid powerdown action scripts to immediately shutdown the
106
   	system without checking if a GUI is running.
107

    
108
       remove-persistent-net-rules:
109
   	Remove udev rules that will keep network interface names persistent
110
   	after hardware changes and reboots. Those rules will be created again
111
   	the next time the image runs.
112

    
113
       remove-swap-entry:
114
   	Remove swap entry from /etc/fstab. If swap is the last partition
115
   	then the partition will be removed when shrinking is performed. If the
116
   	swap partition is not the last partition in the disk or if you are not
117
   	going to shrink the image you should probably disable this.
118

    
119
       use-persistent-block-device-names:
120
   	Scan fstab & grub configuration files and replace all non-persistent
121
   	device references with UUIDs.
122

    
123
   Disabled system preparation operations:
124
       cleanup-mail:
125
   	Remove all files under /var/mail and /var/spool/mail
126

    
127
       remove-user-accounts:
128
   	Remove all user accounts with id greater than 1000
129

    
130

    
131
   cleaning up...
132

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

    
136
.. code-block:: console
137

    
138
   $ snf-image-creator --enable-sysprep cleanup-mail --enable-sysprep remove-user-accounts ...
139

    
140
Dialog-based version
141
====================
142

    
143
*snf-mkimage* receives the following options:
144

    
145
.. code-block:: console
146

    
147
 $ snf-mkimage --help
148
 Usage: snf-mkimage [options] [<input_media>]
149

    
150
 Options:
151
   --version             show program's version number and exit
152
   -h, --help            show this help message and exit
153
   -l FILE, --logfile=FILE
154
                         log all messages to FILE
155
   --tmpdir=DIR          create large temporary image files under DIR
156

    
157
If the input media is not specified in the command line, in the first dialog
158
box the user will be asked to specify it:
159

    
160
.. image:: /snapshots/select_media.png
161

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

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

    
169
Wizard mode
170
-----------
171

    
172
When *snf-mkimage* runs in *wizard* mode, the user is just asked to provide the
173
following basic information:
174

    
175
 * Name: A short name for the image (ex. "Slackware")
176
 * Description: An one-line description for the image
177
   (ex. "Slackware Linux 14.0 with KDE")
178
 * Account: An *~okeanos* account user id
179
 * Token: A token corresponding to the account given above
180

    
181
After confirming, the image will be extracted, uploaded to *pithos+* and
182
registered with *~okeanos*. The user will also be given the choice to keep a
183
local copy of it.
184

    
185
For most users the functionality this mode provides should be sufficient.
186

    
187
Expert mode
188
-----------
189

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

    
193
.. image:: /snapshots/main_menu.png
194

    
195
In the *Customize* sub-menu the user can control:
196

    
197
 * The system preparation operations that will be applied on the media
198
 * Whether the image will be shrunk or not
199
 * The properties associated with the image
200
 * The configuration tasks that will run during image deployment
201

    
202
In the *Register* sub-menu the user can provide:
203

    
204
 * The credentials to login to *~okeanos*
205
 * A *pithos+* filename for the uploaded *diskdump* image
206
 * A name for the image to be registered to *~okeanos* with
207

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

    
212
Host bundling operation
213
=======================
214

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

    
223
Creating a new image
224
====================
225

    
226
Suppose you want to create a new Ubuntu server image. Download the installation
227
disk from the Internet:
228

    
229
.. code-block:: console
230

    
231
   $ wget http://ubuntureleases.tsl.gr/12.04.1/ubuntu-12.04.1-server-amd64.iso
232

    
233
Verify that it has been downloaded correctly:
234

    
235
.. code-block:: console
236

    
237
   $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17  ubuntu-12.04.1-server-amd64.iso' > check.md5
238
   $ md5sum -c check.md5
239

    
240
Create a 2G sparse file to host the new system:
241

    
242
.. code-block:: console
243

    
244
   $ truncate -s 2G ubuntu_hd.raw
245

    
246
And install the Ubuntu system on this file:
247

    
248
.. code-block:: console
249

    
250
   $ sudo kvm -boot d -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio \
251
     -m 1G -cdrom ubuntu-12.04.1-server-amd64.iso
252

    
253
.. warning::
254

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

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

    
261
   $ sudo kvm -m 1G -boot c -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio
262

    
263
After you're done, you may use *snf-mkimage* as root to create and upload the
264
image:
265

    
266
.. code-block:: console
267

    
268
   $ sudo -s
269
   $ snf-mkimage ubuntu_hd.raw
270

    
271
In the first screen you will be asked to choose if you want to run the program
272
in *Wizard* or *Expert* mode. Choose *Wizard*.
273

    
274
.. image:: /snapshots/01_wizard.png
275

    
276
Then you will be asked to provide a name, a description, an *~okeanos* account
277
and the token corresponding to this account. Finally, you'll be asked to
278
confirm the provided data.
279

    
280
.. image:: /snapshots/06_confirm.png
281

    
282
Choosing *YES* will create and upload the image to your *~okeanos* account.
283

    
284
Limitations
285
===========
286

    
287
Supported operating systems
288
---------------------------
289

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

    
295
Logical Volumes
296
---------------
297

    
298
The program cannot work on LVM partitions [#f1]_. The input media may only
299
contain primary or logical partitions.
300

    
301
Para-virtualized drivers
302
------------------------
303

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

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

    
322
Some caveats on image creation
323
==============================
324

    
325
Image partition schemes and shrinking
326
-------------------------------------
327

    
328
When image shrinking is enabled, *snf-image-creator* will shrink the last
329
partition on the disk. If this is a swap partition, it will remove it, save
330
enough information to recreate it during image deployment and shrink the
331
partition that lays just before that. This will make the image smaller which
332
speeds up the deployment process.
333

    
334
During image deployment, the last partition is enlarged to occupy the available
335
space in the VM's hard disk and a swap partition is added at the end if a SWAP
336
image property is present.
337

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

    
342
Large temporary files
343
---------------------
344

    
345
*snf-image-creator* may create large temporary files when running:
346

    
347
 * During image shrinking, the input media snapshot file may reach the size of
348
   the original media.
349
 * When bundling the host system, the temporary image file may became as large
350
   as the rest of the disk files altogether.
351

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

    
361
.. rubric:: Footnotes
362

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