4 snf-image-creator comes in 2 variants:
6 * snf-image-creator: A non-interactive command line program
7 * snf-mkimage: A user-friendly dialog-based program
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`_).
13 Non-interactive version
14 =======================
16 snf-image-creator receives the following options:
18 .. code-block:: console
20 $ snf-image-creator --help
21 Usage: snf-image-creator [options] <input_media>
24 --version show program's version number and exit
25 -h, --help show this help message and exit
26 -o FILE, --outfile=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
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
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
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
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.
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
71 Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a
72 debian system, we print the following output:
76 .. code-block:: console
78 $ snf-image-creator --print-sysprep debian_desktop.img
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
89 Enabled system preparation operations:
91 Remove all regular files under /var/cache
94 Empty all files under /var/log
97 Remove all passwords and lock all user accounts
100 Remove all files under /tmp and /var/tmp
103 Delete sensitive userdata
106 Replace acpid powerdown action scripts to immediately shutdown the
107 system without checking if a GUI is running.
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.
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.
120 use-persistent-block-device-names:
121 Scan fstab & grub configuration files and replace all non-persistent
122 device references with UUIDs.
124 Disabled system preparation operations:
126 Remove all files under /var/mail and /var/spool/mail
128 remove-user-accounts:
129 Remove all user accounts with id greater than 1000
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:
137 .. code-block:: console
139 $ snf-image-creator --enable-sysprep cleanup-mail --enable-sysprep remove-user-accounts ...
144 *snf-mkimage* receives the following options:
146 .. code-block:: console
149 Usage: snf-mkimage [options] [<input_media>]
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
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:
161 .. image:: /snapshots/select_media.png
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`_).
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.
173 When *snf-mkimage* runs in *wizard* mode, the user is just asked to provide the
174 following basic information:
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
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
186 For most users the functionality this mode provides should be sufficient.
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:
194 .. image:: /snapshots/main_menu.png
196 In the *Customize* sub-menu the user can control:
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
203 In the *Register* sub-menu the user can provide:
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*)
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.
214 Host bundling operation
215 =======================
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).
228 Suppose you want to create a new Ubuntu server image. Download the installation
229 disk from the Internet:
231 .. code-block:: console
233 $ wget http://ubuntureleases.tsl.gr/12.04.2/ubuntu-12.04.2-server-amd64.iso
235 Verify that it has been downloaded correctly:
237 .. code-block:: console
239 $ echo 'a8c667e871f48f3a662f3fbf1c3ddb17 ubuntu-12.04.2-server-amd64.iso' > check.md5
240 $ md5sum -c check.md5
242 Create a 2G sparse file to host the new system:
244 .. code-block:: console
246 $ truncate -s 2G ubuntu_hd.raw
248 And install the Ubuntu system on this file:
250 .. code-block:: console
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
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.
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::
263 $ sudo kvm -m 1G -boot c -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio
265 After you're done, you may use *snf-mkimage* as root to create and upload the
268 .. code-block:: console
271 $ snf-mkimage ubuntu_hd.raw
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*.
276 .. image:: /snapshots/wizard.png
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.
282 .. image:: /snapshots/confirm.png
284 Choosing *YES* will create and upload the image to your *~okeanos* account.
289 Supported operating systems
290 ---------------------------
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.
300 The program cannot work on LVM partitions [#f1]_. The input media may only
301 contain primary or logical partitions.
303 Para-virtualized drivers
304 ------------------------
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.
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).
324 Some caveats on image creation
325 ==============================
327 Image partition schemes and shrinking
328 -------------------------------------
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.
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.
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.
344 Large temporary files
345 ---------------------
347 *snf-image-creator* may create large temporary files when running:
349 * During image shrinking, the input media snapshot file may reach the size of
351 * When bundling the host system, the temporary image file may became as large
352 as the rest of the disk files altogether.
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*.
363 .. rubric:: Footnotes
365 .. [#f1] http://sourceware.org/lvm2/
366 .. [#f2] http://mirrors.slackware.com/slackware/slackware-14.0/README.initrd