Update the documentation to reflect v0.2
[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    -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 resulting filename using the *-o* option. To
55 upload the image to *pithos+*, provide valid credentials  using *-a* and *-t*
56 and a filename using *-u*. If you also want to register the image with
57 *~okeanos*, in addition to *-u* provide a registration name using *-r*.
58
59 By default snf-image-creator will perform a number of system preparation
60 operations on the snapshot of the media and will shrink the last partition
61 found, before extracting the image. Both 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 media source. The user can enable or disable specific *syspreps* when creating
67 an image, using *-{enable,disable}-sysprep* options. You may specify those
68 options multiple times to enable or disable multiple *syspreps*.
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 email
179  * Token: A token corresponding to the account defined previously
180
181 After confirming, the image will be extracted, uploaded to *pithos+* and
182 registered to *~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. In the picture below the main menu can be seen:
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 `the tmpdir option`_
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 to it
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. After that you will 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 Some caveats on image creation
285 ==============================
286
287 Para-virtualized drivers
288 ------------------------
289
290 *~Okeanos* uses the *VirtIO* framework. The disk I/O controller and the
291 Ethernet cards on the VM instances are para-virtualized and need special
292 *VirtIO* drivers. Those drivers are included in the Linux Kernel mainline since
293 version 2.6.25 and are shipped with all the popular Linux distributions. The
294 problem is that if the driver for the para-virtualized disk I/O controller is
295 built as module, it needs to be preloaded using an initial ramdisk, otherwise
296 the VM will not be able to boot.
297
298 Many popular linux distributions, like Ubuntu and Debian, will automatically
299 create a generic initial ramdisk file that contains many different modules,
300 including the VirtIO drivers. Others that target more experienced users, like
301 Slackware, won't do that [#f1]_. *snf-image-creator* cannot resolve this kind
302 of problems and it's left to the user to do so. Please refer to your
303 distribution's documentation for more information on this. You can always check
304 if a system can boot with para-virtualized disk controller by launching it with
305 kvm using the *if=virtio* option (take a look at the kvm command in the
306 `Creating a new image`_ section).
307
308 Image partition schemes and shrinking
309 -------------------------------------
310
311 When image shrinking is enabled, *snf-image-creator* will shrink the last
312 partition on the disk. If this is a swap partition, it will remove it, save
313 enough information to recreate it during image deployment and shrink the
314 partition that lays just before that. This will make the image smaller which
315 speeds up the deployment process.
316
317 During image deployment, the last partition is enlarged to occupy the available
318 space in the VM's hard disk and a swap partition is added at the end if a SWAP
319 image property is present.
320
321 Keep this in mind when creating images. It's always better to have your swap
322 partition placed as the last partition on the disk and have your largest
323 partition (*/* or */home*) just before that.
324
325 The tmpdir option
326 -----------------
327
328 *snf-image-creator* may create large temporary files when running:
329
330  * During image shrinking, the input media snapshot file may reach the size of
331    the original media.
332  * When bundling the host system, the size of temporary image file may reach
333    the size of all disk files.
334
335 The */tmp* directory is not a good place for hosting large files. In many systems
336 the contents of */tmp* are stored in volatile memory and the size they may occupy
337 is limited. By default, *snf-image-creator* will use a heuristic approach to
338 determine where to store large temporary files. It will examine the free space
339 under */var/tmp*, the user's home directory and */mnt* and will pick the one
340 with the most free space. The user may overwrite this behaviour and indicate a
341 directory using the *tmpdir* option. This option is present in both
342 *snf-image-creator* and *snf-mkimage*.
343
344 .. rubric:: Footnotes
345
346 .. [#f1] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd