Revision fa77d79a docs/usage.rst
b/docs/usage.rst | ||
---|---|---|
1 | 1 |
Usage |
2 |
=====
|
|
2 |
^^^^^
|
|
3 | 3 |
|
4 | 4 |
snf-image-creator comes in 2 variants: |
5 | 5 |
* snf-image-creator: A non-interactive command line program |
6 | 6 |
* snf-mkimage: A user-friendly dialog-based program |
7 | 7 |
|
8 | 8 |
Non-interactive version |
9 |
-----------------------
|
|
9 |
=======================
|
|
10 | 10 |
|
11 | 11 |
snf-image-creator receives the following options: |
12 | 12 |
|
... | ... | |
52 | 52 |
filename using *-u* option. To also register the image with ~okeanos, specify a |
53 | 53 |
name using the *-r* option. |
54 | 54 |
|
55 |
By default snf-image-creator will run a number of system preparation tasks on
|
|
56 |
the snapshot of the media and will shrink the last partition found, before
|
|
57 |
extracting the image. Both can be disabled by specifying *--no-sysprep* and
|
|
58 |
*--no-shrink* respectively. |
|
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 | 59 |
|
60 |
If *--print-sysprep* is defined, then snf-image-creator will not create an |
|
61 |
image at all. It will only run the OS detection part and will output the system |
|
62 |
preparation tasks that would and would not run on the image. This behavior is, |
|
63 |
convenient because it allows you to see the available system preparation tasks |
|
64 |
that you can enable or disable with *-{enable,disable}-sysprep* options when |
|
65 |
you create a new image. |
|
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. |
|
66 | 65 |
|
67 | 66 |
Running *snf-image-creator* with *--print-sysprep* on a raw file that hosts a |
68 |
debian system, I get the following output:
|
|
67 |
debian system, we get the following output:
|
|
69 | 68 |
|
70 | 69 |
.. code-block:: console |
71 | 70 |
|
... | ... | |
133 | 132 |
$ snf-image-creator --enable-sysprep cleanup-mail,remove-user-accounts ... |
134 | 133 |
|
135 | 134 |
Dialog-based version |
136 |
--------------------
|
|
135 |
====================
|
|
137 | 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. |
|
138 | 191 |
|
139 | 192 |
Creating a new image |
140 |
--------------------
|
|
193 |
====================
|
|
141 | 194 |
|
142 |
Suppose you want to create a new ubuntu server image. Download the installation
|
|
143 |
disk from the internet:
|
|
195 |
Suppose you want to create a new Ubuntu server image. Download the installation
|
|
196 |
disk from the Internet:
|
|
144 | 197 |
|
145 | 198 |
.. code-block:: console |
146 | 199 |
|
... | ... | |
152 | 205 |
|
153 | 206 |
$ truncate -s 2G ubuntu_hd.raw |
154 | 207 |
|
155 |
And install the ubuntu system on this file:
|
|
208 |
And install the Ubuntu system on this file:
|
|
156 | 209 |
|
157 | 210 |
.. code-block:: console |
158 | 211 |
|
159 | 212 |
$ sudo kvm -boot d -drive file=ubuntu_hd.raw,format=raw,cache=none,if=virtio \ |
160 | 213 |
-cdrom ubuntu-12.04.1-server-amd64.iso |
161 | 214 |
|
162 |
After this, become root, activate the virtual environment you have installed |
|
163 |
snf-image-creator in, and use *snf-mkimage* to create and upload the image: |
|
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: |
|
164 | 218 |
|
165 | 219 |
.. code-block:: console |
166 | 220 |
|
... | ... | |
169 | 223 |
$ snf-mkimage ubuntu_hd.raw |
170 | 224 |
|
171 | 225 |
In the first screen you will be asked to choose if you want to run the program |
172 |
in *Wizand* or *Expert* mode. Choose *Wizard*.
|
|
226 |
in *Wizard* or *Expert* mode. Choose *Wizard*.
|
|
173 | 227 |
|
174 | 228 |
.. image:: /snapshots/01_wizard.png |
175 | 229 |
|
... | ... | |
181 | 235 |
|
182 | 236 |
Choosing *YES* will create the image and upload it to your ~okeanos account. |
183 | 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 |
Also available in: Unified diff