Fix syntax errors
[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 with 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 use when authenticating
206    to *~okeanos*
207  * A *pithos+* filename for the uploaded *diskdump* image
208  * A name for the image to use when registering it with *~okeanos*, as well as
209    the registration type (*private* or *public*)
210
211 By choosing the *Extract* menu entry, the user can dump the image to the local
212 file system. Finally, if the user selects *Reset*, the system will ignore
213 all changes made so far and will start the image creation process again.
214
215 Host bundling operation
216 =======================
217
218 As a new feature in *v0.2*, snf-image-creator can create images out of the host
219 system that runs the program. This is done either by specifying / as input
220 media or by using the *Bundle Host* button in the media selection dialog of
221 snf-mkimage. During this operation, the files of the disk are copied into a
222 temporary image file, which means that the file system that will host the
223 temporary image needs to have a lot of free space (see `large temporary files`_
224 for more information).
225
226 Creating a new image
227 ====================
228
229 Suppose you want to create a new Ubuntu server image. Download the installation
230 disk from the Internet:
231
232 .. code-block:: console
233
234    $ wget http://ubuntureleases.tsl.gr/12.04.2/ubuntu-12.04.2-server-amd64.iso
235
236 Verify that it has been downloaded correctly:
237
238 .. code-block:: console
239
240    $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17  ubuntu-12.04.2-server-amd64.iso' > check.md5
241    $ md5sum -c check.md5
242
243 Create a 2G sparse file to host the new system:
244
245 .. code-block:: console
246
247    $ truncate -s 2G ubuntu_hd.raw
248
249 And install the Ubuntu system on this file:
250
251 .. code-block:: console
252
253    $ sudo kvm -boot d -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio \
254      -m 1G -cdrom ubuntu-12.04.2-server-amd64.iso
255
256 .. warning::
257
258    During the installation, you will be asked about the partition scheme. Don't 
259    use LVM partitions. They are not supported by snf-image-creator.
260
261 You will be able to boot your installed OS and make any changes you want
262 (e.g. install openssh-server) using the following command::
263
264    $ sudo kvm -m 1G -boot c -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio
265
266 After you're done, you may use *snf-mkimage* as root to create and upload the
267 image:
268
269 .. code-block:: console
270
271    $ sudo -s
272    $ snf-mkimage ubuntu_hd.raw
273
274 In the first screen you will be asked to choose if you want to run the program
275 in *Wizard* or *Expert* mode. Choose *Wizard*.
276
277 .. image:: /snapshots/wizard.png
278
279 Then you will be asked to provide a name, a description, a registration type
280 (*private* or *public*) and the authentication token corresponding to your
281 *~okeanos* account. Finally, you'll be asked to confirm the provided data.
282
283 .. image:: /snapshots/confirm.png
284
285 Choosing *YES* will create and upload the image to your *~okeanos* account.
286
287 Limitations
288 ===========
289
290 Supported operating systems
291 ---------------------------
292
293 *snf-image-creator* can only fully function on input media hosting *Linux*
294 systems. The program will detect the needed metadata and you may use it to
295 upload and register other *Unix* or *Windows* images, but you cannot use it to
296 shrink them or perform system preparation operations.
297
298 Logical Volumes
299 ---------------
300
301 The program cannot work on LVM partitions [#f1]_. The input media may only
302 contain primary or logical partitions.
303
304 Para-virtualized drivers
305 ------------------------
306
307 *~Okeanos* uses the *VirtIO* framework. The disk I/O controller and the
308 Ethernet cards on the VM instances are para-virtualized and need special
309 *VirtIO* drivers. Those drivers are included in the Linux Kernel mainline since
310 version 2.6.25 and are shipped with all the popular Linux distributions. The
311 problem is that if the driver for the para-virtualized disk I/O controller is
312 built as module, it needs to be preloaded using an initial ramdisk, otherwise
313 the VM won't be able to boot.
314
315 Many popular Linux distributions, like Ubuntu and Debian, will automatically
316 create a generic initial ramdisk file that contains many different modules,
317 including the VirtIO drivers. Others that target more experienced users, like
318 Slackware, won't do that [#f2]_. *snf-image-creator* cannot resolve this kind
319 of problems and it's left to the user to do so. Please refer to your
320 distribution's documentation for more information on this. You can always check
321 if a system can boot with para-virtualized disk controller by launching it with
322 kvm using the *if=virtio* option (see the kvm command in the
323 `Creating a new image`_ section).
324
325 Some caveats on image creation
326 ==============================
327
328 Image partition schemes and shrinking
329 -------------------------------------
330
331 When image shrinking is enabled, *snf-image-creator* will shrink the last
332 partition on the disk. If this is a swap partition, it will remove it, save
333 enough information to recreate it during image deployment and shrink the
334 partition that lays just before that. This will make the image smaller which
335 speeds up the deployment process.
336
337 During image deployment, the last partition is enlarged to occupy the available
338 space in the VM's hard disk and a swap partition is added at the end if a SWAP
339 image property is present.
340
341 Keep this in mind when creating images. It's always better to have your swap
342 partition placed as the last partition on the disk and have your largest
343 partition (*/* or */home*) just before that.
344
345 Large temporary files
346 ---------------------
347
348 *snf-image-creator* may create large temporary files when running:
349
350  * During image shrinking, the input media snapshot file may reach the size of
351    the original media.
352  * When bundling the host system, the temporary image file may became as large
353    as the rest of the disk files altogether.
354
355 */tmp* directory is not a good place for hosting large files. In many systems
356 the contents of */tmp* are stored in volatile memory and the size they may occupy
357 is limited. By default, *snf-image-creator* will use a heuristic approach to
358 determine where to store large temporary files. It will examine the free space
359 under */var/tmp*, the user's home directory and */mnt* and will pick the one
360 with the most available space. The user may overwrite this behaviour and
361 indicate a different directory using the *tmpdir* option. This option is
362 supported by both *snf-image-creator* and *snf-mkimage*.
363
364 .. rubric:: Footnotes
365
366 .. [#f1] http://sourceware.org/lvm2/
367 .. [#f2] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd