Update the documentation
[snf-image-creator] / docs / usage.rst
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 token when uploading/registering images
38                          [Default: None]
39    --print-sysprep       print the available enabled and disabled system
40                          preparation operations for this input media
41    --enable-sysprep=SYSPREP
42                          run SYSPREP operation on the input media
43    --disable-sysprep=SYSPREP
44                          prevent SYSPREP operation from running on the input
45                          media
46    --no-sysprep          don't perform any system preparation operation
47    --no-shrink           don't shrink the image
48    --public              register image to cyclades as public
49    --tmpdir=DIR          create large temporary image files under DIR
50
51 Most input options are self-describing. If you want to save a local copy of
52 the image you create, provide a filename using the *-o* option. To upload the
53 image to *pithos+*, provide a valid authentication token using *-t* and a
54 filename using *-u*. If you also want to register the image with *~okeanos*, in
55 addition to *-u* provide a registration name using *-r*. All images are
56 registered as *private*. Only the user that registers the image can create
57 VM's out of it. If you want the image to be visible by other user too, use the
58 *--public* option.
59
60 By default, before extracting the image, snf-image-creator will perform a
61 number of system preparation operations on the snapshot of the media and will
62 shrink the last partition found. Both actions can be disabled by specifying
63 *--no-sysprep* and *--no-shrink* respectively.
64
65 If *--print-sysprep* is defined, the program will exit after printing a
66 list of enabled and disabled system preparation operation applicable to this
67 input media. The user can enable or disable specific *syspreps*, using
68 *-{enable,disable}-sysprep* options. The user may specify those options
69 multiple times.
70
71 Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a
72 debian system, we print the following output:
73
74 .. _sysprep:
75
76 .. code-block:: console
77
78    $ snf-image-creator --print-sysprep debian_desktop.img
79
80    snf-image-creator 0.1
81    =====================
82    Examining source media `debian_desktop.img'... looks like an image file
83    Snapshotting media source... done
84    Enabling recovery proc
85    Launching helper VM... done
86    Inspecting Operating System... found a(n) debian system
87    Mounting the media read-only... done
88
89    Enabled system preparation operations:
90        cleanup-cache:
91         Remove all regular files under /var/cache
92
93        cleanup-log:
94         Empty all files under /var/log
95
96        cleanup-passwords:
97         Remove all passwords and lock all user accounts
98
99        cleanup-tmp:
100         Remove all files under /tmp and /var/tmp
101
102        cleanup-userdata:
103         Delete sensitive userdata
104
105        fix-acpid:
106         Replace acpid powerdown action scripts to immediately shutdown the
107         system without checking if a GUI is running.
108
109        remove-persistent-net-rules:
110         Remove udev rules that will keep network interface names persistent
111         after hardware changes and reboots. Those rules will be created again
112         the next time the image runs.
113
114        remove-swap-entry:
115         Remove swap entry from /etc/fstab. If swap is the last partition
116         then the partition will be removed when shrinking is performed. If the
117         swap partition is not the last partition in the disk or if you are not
118         going to shrink the image you should probably disable this.
119
120        use-persistent-block-device-names:
121         Scan fstab & grub configuration files and replace all non-persistent
122         device references with UUIDs.
123
124    Disabled system preparation operations:
125        cleanup-mail:
126         Remove all files under /var/mail and /var/spool/mail
127
128        remove-user-accounts:
129         Remove all user accounts with id greater than 1000
130
131
132    cleaning up...
133
134 If you want the image to have all normal user accounts and all mail files
135 removed, you should use *--enable-sysprep* option like this:
136
137 .. code-block:: console
138
139    $ snf-image-creator --enable-sysprep cleanup-mail --enable-sysprep remove-user-accounts ...
140
141 Dialog-based version
142 ====================
143
144 *snf-mkimage* receives the following options:
145
146 .. code-block:: console
147
148  $ snf-mkimage --help
149  Usage: snf-mkimage [options] [<input_media>]
150
151  Options:
152    --version             show program's version number and exit
153    -h, --help            show this help message and exit
154    -l FILE, --logfile=FILE
155                          log all messages to FILE
156    --tmpdir=DIR          create large temporary image files under DIR
157
158 If the input media is not specified in the command line, in the first dialog
159 box the user will be asked to specify it:
160
161 .. image:: /snapshots/select_media.png
162
163 The user can select a file (regular or block device) or use the *Bundle Host*
164 button to create an image out of the running system (see
165 `Host bundling operation`_).
166
167 After the input media is examined and the program is initialized, the user will
168 be given the choice to run *snf-mkimage* in *wizard* or *expert* mode.
169
170 Wizard mode
171 -----------
172
173 When *snf-mkimage* runs in *wizard* mode, the user is just asked to provide the
174 following basic information:
175
176  * Name: A short name for the image (ex. "Slackware")
177  * Description: An one-line description for the image
178    (ex. "Slackware Linux 14.0 with KDE")
179  * Registration Type: Private or Public
180  * Account: The authentication token for an *~okeanos* account
181
182 After confirming, the image will be extracted, uploaded to *pithos+* and
183 registered with *~okeanos*. The user will also be given the choice to keep a
184 local copy of it.
185
186 For most users the functionality this mode provides should be sufficient.
187
188 Expert mode
189 -----------
190
191 Expert mode allows the user to have better control on the image creation
192 process. The main menu can be seen in the picture below:
193
194 .. image:: /snapshots/main_menu.png
195
196 In the *Customize* sub-menu the user can control:
197
198  * The system preparation operations that will be applied on the media
199  * Whether the image will be shrunk or not
200  * The properties associated with the image
201  * The configuration tasks that will run during image deployment
202
203 In the *Register* sub-menu the user can provide:
204
205  * The credentials (authentication token) to authenticate on *~okeanos*
206  * A *pithos+* filename for the uploaded *diskdump* image
207  * A name for the image to be registered to *~okeanos* with, as well as the
208    registration type (*private* or *public*)
209
210 By choosing the *Extract* menu entry, the user can dump the image to the local
211 file system. Finally, if the user selects *Reset*, the system will ignore
212 all changes made so far and will start the image creation process again.
213
214 Host bundling operation
215 =======================
216
217 As a new feature in *v0.2*, snf-image-creator can create images out of the host
218 system that runs the program. This is done either by specifying / as input
219 media or by using the *Bundle Host* button in the media selection dialog of
220 snf-mkimage. During this operation, the files of the disk are copied into a
221 temporary image file, which means that the file system that will host the
222 temporary image needs to have a lot of free space (see `large temporary files`_
223 for more information).
224
225 Creating a new image
226 ====================
227
228 Suppose you want to create a new Ubuntu server image. Download the installation
229 disk from the Internet:
230
231 .. code-block:: console
232
233    $ wget http://ubuntureleases.tsl.gr/12.04.2/ubuntu-12.04.2-server-amd64.iso
234
235 Verify that it has been downloaded correctly:
236
237 .. code-block:: console
238
239    $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17  ubuntu-12.04.2-server-amd64.iso' > check.md5
240    $ md5sum -c check.md5
241
242 Create a 2G sparse file to host the new system:
243
244 .. code-block:: console
245
246    $ truncate -s 2G ubuntu_hd.raw
247
248 And install the Ubuntu system on this file:
249
250 .. code-block:: console
251
252    $ sudo kvm -boot d -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio \
253      -m 1G -cdrom ubuntu-12.04.2-server-amd64.iso
254
255 .. warning::
256
257    During the installation, you will be asked about the partition scheme. Don't 
258    use LVM partitions. They are not supported by snf-image-creator.
259
260 You will be able to boot your installed OS and make any changes you want
261 (e.g. install openssh-server) using the following command::
262
263    $ sudo kvm -m 1G -boot c -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio
264
265 After you're done, you may use *snf-mkimage* as root to create and upload the
266 image:
267
268 .. code-block:: console
269
270    $ sudo -s
271    $ snf-mkimage ubuntu_hd.raw
272
273 In the first screen you will be asked to choose if you want to run the program
274 in *Wizard* or *Expert* mode. Choose *Wizard*.
275
276 .. image:: /snapshots/wizard.png
277
278 Then you will be asked to provide a name, a description, a registration type
279 (*private* or *public*) and the authentication token corresponding to your
280 *~okeanos* account. Finally, you'll be asked to confirm the provided data.
281
282 .. image:: /snapshots/confirm.png
283
284 Choosing *YES* will create and upload the image to your *~okeanos* account.
285
286 Limitations
287 ===========
288
289 Supported operating systems
290 ---------------------------
291
292 *snf-image-creator* can only fully function on input media hosting *Linux*
293 systems. The program will detect the needed metadata and you may use it to
294 upload and register other *Unix* or *Windows* images, but you cannot use it to
295 shrink them or perform system preparation operations.
296
297 Logical Volumes
298 ---------------
299
300 The program cannot work on LVM partitions [#f1]_. The input media may only
301 contain primary or logical partitions.
302
303 Para-virtualized drivers
304 ------------------------
305
306 *~Okeanos* uses the *VirtIO* framework. The disk I/O controller and the
307 Ethernet cards on the VM instances are para-virtualized and need special
308 *VirtIO* drivers. Those drivers are included in the Linux Kernel mainline since
309 version 2.6.25 and are shipped with all the popular Linux distributions. The
310 problem is that if the driver for the para-virtualized disk I/O controller is
311 built as module, it needs to be preloaded using an initial ramdisk, otherwise
312 the VM won't be able to boot.
313
314 Many popular Linux distributions, like Ubuntu and Debian, will automatically
315 create a generic initial ramdisk file that contains many different modules,
316 including the VirtIO drivers. Others that target more experienced users, like
317 Slackware, won't do that [#f2]_. *snf-image-creator* cannot resolve this kind
318 of problems and it's left to the user to do so. Please refer to your
319 distribution's documentation for more information on this. You can always check
320 if a system can boot with para-virtualized disk controller by launching it with
321 kvm using the *if=virtio* option (see the kvm command in the
322 `Creating a new image`_ section).
323
324 Some caveats on image creation
325 ==============================
326
327 Image partition schemes and shrinking
328 -------------------------------------
329
330 When image shrinking is enabled, *snf-image-creator* will shrink the last
331 partition on the disk. If this is a swap partition, it will remove it, save
332 enough information to recreate it during image deployment and shrink the
333 partition that lays just before that. This will make the image smaller which
334 speeds up the deployment process.
335
336 During image deployment, the last partition is enlarged to occupy the available
337 space in the VM's hard disk and a swap partition is added at the end if a SWAP
338 image property is present.
339
340 Keep this in mind when creating images. It's always better to have your swap
341 partition placed as the last partition on the disk and have your largest
342 partition (*/* or */home*) just before that.
343
344 Large temporary files
345 ---------------------
346
347 *snf-image-creator* may create large temporary files when running:
348
349  * During image shrinking, the input media snapshot file may reach the size of
350    the original media.
351  * When bundling the host system, the temporary image file may became as large
352    as the rest of the disk files altogether.
353
354 */tmp* directory is not a good place for hosting large files. In many systems
355 the contents of */tmp* are stored in volatile memory and the size they may occupy
356 is limited. By default, *snf-image-creator* will use a heuristic approach to
357 determine where to store large temporary files. It will examine the free space
358 under */var/tmp*, the user's home directory and */mnt* and will pick the one
359 with the most available space. The user may overwrite this behaviour and
360 indicate a different directory using the *tmpdir* option. This option is
361 supported by both *snf-image-creator* and *snf-mkimage*.
362
363 .. rubric:: Footnotes
364
365 .. [#f1] http://sourceware.org/lvm2/
366 .. [#f2] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd