root / docs / usage.rst @ fa77d79a
History | View | Annotate | Download (9.8 kB)
1 |
Usage |
---|---|
2 |
^^^^^ |
3 |
|
4 |
snf-image-creator comes in 2 variants: |
5 |
* snf-image-creator: A non-interactive command line program |
6 |
* snf-mkimage: A user-friendly dialog-based program |
7 |
|
8 |
Non-interactive version |
9 |
======================= |
10 |
|
11 |
snf-image-creator receives the following options: |
12 |
|
13 |
.. code-block:: console |
14 |
|
15 |
$ snf-image-creator --help |
16 |
|
17 |
Usage: snf-image-creator [options] <input_media> |
18 |
|
19 |
Options: |
20 |
--version show program's version number and exit |
21 |
-h, --help show this help message and exit |
22 |
-o FILE, --outfile=FILE |
23 |
dump image to FILE |
24 |
-f, --force overwrite output files if they exist |
25 |
-s, --silent silent mode, only output errors |
26 |
-u FILENAME, --upload=FILENAME |
27 |
upload the image to pithos with name FILENAME |
28 |
-r IMAGENAME, --register=IMAGENAME |
29 |
register the image with ~okeanos as IMAGENAME |
30 |
-a ACCOUNT, --account=ACCOUNT |
31 |
Use this ACCOUNT when uploading/registering images |
32 |
[Default: None] |
33 |
-m KEY=VALUE, --metadata=KEY=VALUE |
34 |
Add custom KEY=VALUE metadata to the image |
35 |
-t TOKEN, --token=TOKEN |
36 |
Use this token when uploading/registering images |
37 |
[Default: None] |
38 |
--print-sysprep print the enabled and disabled system preparation |
39 |
operations for this input media |
40 |
--enable-sysprep=SYSPREP |
41 |
run SYSPREP operation on the input media |
42 |
--disable-sysprep=SYSPREP |
43 |
prevent SYSPREP operation from running on the input |
44 |
media |
45 |
--no-sysprep don't perform system preparation |
46 |
--no-shrink don't shrink any partition |
47 |
|
48 |
|
49 |
Most input options are self-describing. If you want to save a local copy for |
50 |
the image, you need to specify *-o* option. In order to upload the image to |
51 |
pithos, you need to specify valid credentials with *-a* and *-t* options and a |
52 |
filename using *-u* option. To also register the image with ~okeanos, specify a |
53 |
name using the *-r* option. |
54 |
|
55 |
By default snf-image-creator will run a number of system preparation |
56 |
preparations on the snapshot of the media and will shrink the last partition |
57 |
found, before extracting the image. Both can be disabled by specifying |
58 |
*--no-sysprep* and *--no-shrink* respectively. |
59 |
|
60 |
If *--print-sysprep* is defined, then snf-image-creator will only run the OS |
61 |
detection part and will output the system preparation operation that would and |
62 |
would not run during image creation. This behavior is, convenient because it |
63 |
allows you to see the available system preparation tasks that you can enable or |
64 |
disable with *-{enable,disable}-sysprep* options when you create a new image. |
65 |
|
66 |
Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a |
67 |
debian system, we get the following output: |
68 |
|
69 |
.. code-block:: console |
70 |
|
71 |
$ snf-image-creator --print-sysprep debian_desktop.img |
72 |
|
73 |
snf-image-creator 0.1 |
74 |
===================== |
75 |
Examining source media `debian_desktop.img'... looks like an image file |
76 |
Snapshotting media source... done |
77 |
Enabling recovery proc |
78 |
Launching helper VM... done |
79 |
Inspecting Operating System... found a(n) debian system |
80 |
Mounting image... done |
81 |
|
82 |
Enabled system preparation operations: |
83 |
cleanup-cache: |
84 |
Remove all regular files under /var/cache |
85 |
|
86 |
cleanup-log: |
87 |
Empty all files under /var/log |
88 |
|
89 |
cleanup-passwords: |
90 |
Remove all passwords and lock all user accounts |
91 |
|
92 |
cleanup-tmp: |
93 |
Remove all files under /tmp and /var/tmp |
94 |
|
95 |
cleanup-userdata: |
96 |
Delete sensitive userdata |
97 |
|
98 |
fix-acpid: |
99 |
Replace acpid powerdown action scripts to immediately shutdown the |
100 |
system without checking if a GUI is running. |
101 |
|
102 |
remove-persistent-net-rules: |
103 |
Remove udev rules that will keep network interface names persistent |
104 |
after hardware changes and reboots. Those rules will be created again |
105 |
the next time the image runs. |
106 |
|
107 |
remove-swap-entry: |
108 |
Remove swap entry from /etc/fstab. If swap is the last partition |
109 |
then the partition will be removed when shrinking is performed. If the |
110 |
swap partition is not the last partition in the disk or if you are not |
111 |
going to shrink the image you should probably disable this. |
112 |
|
113 |
use-persistent-block-device-names: |
114 |
Scan fstab & grub configuration files and replace all non-persistent |
115 |
device references with UUIDs. |
116 |
|
117 |
Disabled system preparation operations: |
118 |
cleanup-mail: |
119 |
Remove all files under /var/mail and /var/spool/mail |
120 |
|
121 |
remove-user-accounts: |
122 |
Remove all user accounts with id greater than 1000 |
123 |
|
124 |
|
125 |
cleaning up... |
126 |
|
127 |
If I want your images to also have all normal user accounts and all mail files |
128 |
removed, you can create it specifying the *--enable-sysprep* option like this: |
129 |
|
130 |
.. code-block:: console |
131 |
|
132 |
$ snf-image-creator --enable-sysprep cleanup-mail,remove-user-accounts ... |
133 |
|
134 |
Dialog-based version |
135 |
==================== |
136 |
|
137 |
*snf-mkimage* receives the following options: |
138 |
|
139 |
.. code-block:: console |
140 |
|
141 |
$ Usage: snf-mkimage [options] [<input_media>] |
142 |
|
143 |
Options: |
144 |
--version show program's version number and exit |
145 |
-h, --help show this help message and exit |
146 |
-l FILE, --logfile=FILE |
147 |
log all messages to FILE |
148 |
|
149 |
If the input media is not specified in the command line, then the user will be |
150 |
asked to specify it in the first dialog box. After the input media is examined |
151 |
and the program is initialized, the user is given the choice to run |
152 |
*snf-mkimage* in *wizard* or *expert* mode. |
153 |
|
154 |
Wizard mode |
155 |
----------- |
156 |
|
157 |
When *snf-mkimage* runs in *wizard* mode, the user is just asked to provide the |
158 |
following basic information: |
159 |
|
160 |
* Name: A short name for image (ex. "Slackware") |
161 |
* Description: An one line description for the image (ex. "Slackware Linux 14.0 with KDE") |
162 |
* Account: An ~okeanos account e-mail |
163 |
* Token: A token corresponding to the account defined previously |
164 |
|
165 |
For most users the functionality this mode provides should be sufficient. |
166 |
|
167 |
Expert mode |
168 |
----------- |
169 |
|
170 |
Expert mode allows the user to have better control on the image creation |
171 |
process. In the picture below the main menu can be seen: |
172 |
|
173 |
.. image:: /snapshots/main_menu.png |
174 |
|
175 |
In the *Customize* submenu the user can control: |
176 |
|
177 |
* The system preparation operations that will run during the image creation process |
178 |
* Whether the image will be shrunk or not |
179 |
* The properties associated with the image |
180 |
* Which configuration tasks will run during image deployment |
181 |
|
182 |
In the *Register* submenu the user can provide: |
183 |
|
184 |
* The credentials to login to ~okeanos |
185 |
* A pithos filename for the uploaded diskdump image |
186 |
* A name for the image to be registered to ~okeanos with |
187 |
|
188 |
By choosing the *Extract* menu entry the user can dump the image to the local |
189 |
file system and finally, if the user selects *Reset*, the system will ignore |
190 |
all changes made so far and will start the image creation process again. |
191 |
|
192 |
Creating a new image |
193 |
==================== |
194 |
|
195 |
Suppose you want to create a new Ubuntu server image. Download the installation |
196 |
disk from the Internet: |
197 |
|
198 |
.. code-block:: console |
199 |
|
200 |
$ wget http://ubuntureleases.tsl.gr/12.04.1/ubuntu-12.04.1-server-amd64.iso |
201 |
|
202 |
Create a 2G sparce file to host the new system: |
203 |
|
204 |
.. code-block:: console |
205 |
|
206 |
$ truncate -s 2G ubuntu_hd.raw |
207 |
|
208 |
And install the Ubuntu system on this file: |
209 |
|
210 |
.. code-block:: console |
211 |
|
212 |
$ sudo kvm -boot d -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio \ |
213 |
-cdrom ubuntu-12.04.1-server-amd64.iso |
214 |
|
215 |
After the installation finishes, become root, activate the virtual environment |
216 |
you have installed snf-image-creator in, and use *snf-mkimage* to create and |
217 |
upload the image: |
218 |
|
219 |
.. code-block:: console |
220 |
|
221 |
$ sudo -s |
222 |
$ source /path/to/snf-image-env/bin/activate |
223 |
$ snf-mkimage ubuntu_hd.raw |
224 |
|
225 |
In the first screen you will be asked to choose if you want to run the program |
226 |
in *Wizard* or *Expert* mode. Choose *Wizard*. |
227 |
|
228 |
.. image:: /snapshots/01_wizard.png |
229 |
|
230 |
Then you will be asked to provide a name, a description, an ~okeanos account |
231 |
and the token corresponding to this account. After that you will be asked to |
232 |
confirm the provided data. |
233 |
|
234 |
.. image:: /snapshots/06_confirm.png |
235 |
|
236 |
Choosing *YES* will create the image and upload it to your ~okeanos account. |
237 |
|
238 |
Things you need to pay attention on when creating images |
239 |
======================================================== |
240 |
|
241 |
Para-virtualized drivers |
242 |
------------------------ |
243 |
|
244 |
~Okeanos uses the VirtIO framework. The disk I/O controller and the Ethernet |
245 |
cards on the VM instances are para-virtualized and need special VirtIO drivers. |
246 |
Those drivers are included in the Linux Kernel mainline since version 2.6.25 |
247 |
and are shipped with all the popular Linux distributions. The problem is that |
248 |
if those drivers are built as modules, they need to be preloaded using an |
249 |
initial ramdisk, otherwise the VM will not be able to boot. |
250 |
|
251 |
In the image creation demonstration above, we initially installed the Ubuntu |
252 |
system on a a hard disk (ubuntu_hd.raw) that was para-virtualized (pay |
253 |
attention on the *if=virtio* option of the kvm line). The Ubuntu installer |
254 |
detected that the disk was paravirtualized and made sure the appropriate |
255 |
drivers will be preloaded each time the system boots. In many distros this is |
256 |
not the case. In Arch Linux for example, the user needs to manually add |
257 |
*virtio_blk* and *virtio_pci* drivers in */etc/mkinitcpio.conf* and then |
258 |
rebuild the initial ramdisk [#f1]_ to make the virtio drivers get preloaded |
259 |
during boot. |
260 |
|
261 |
Swap partitions |
262 |
--------------- |
263 |
|
264 |
If you want your image to have a swap partitions, make sure this is the last |
265 |
partition on the disk. If snf-image-creator detects a swap partition in the end |
266 |
of the input media, it will remove the partition during shrinking and will save |
267 |
enough information to be able to recreate it during image deployment. This will |
268 |
make your image smaller and will speed up the deployment process. |
269 |
|
270 |
.. rubric:: Footnotes |
271 |
|
272 |
.. [#f1] https://wiki.archlinux.org/index.php/KVM#Paravirtualized_guests_.28virtio.29 |