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