root / docs / usage.rst @ 56884b64
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 |