root / docs / usage.rst @ 00302138
History | View | Annotate | Download (7 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 create, you specify *-o* option. To upload the image to |
51 |
*pithos+*, you specify valid credentials with *-a* and *-t* options and a |
52 |
filename using *-u*. If you want to register the image with *~okeanos*, |
53 |
in addition to *-u* specify a registration name using *-r*. |
54 |
|
55 |
By default snf-image-creator will perform a number of system preparation |
56 |
operations 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, the program will exit after outputing a |
61 |
list of enabled and disabled system preparation operation appliable to this |
62 |
media source. The user can enable or disable specific *syspreps* when creating |
63 |
an image, using *-{enable,disable}-sysprep* options. You can specify those |
64 |
options multiple times to enable or disable multiple *syspreps*. |
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 the media read-only... 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 we want the image to have all normal user accounts and all mail files |
128 |
removed, we can create it specifying *--enable-sysprep* option like this: |
129 |
|
130 |
.. code-block:: console |
131 |
|
132 |
$ snf-image-creator --enable-sysprep cleanup-mail --enable-sysprep 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, in the first dialog |
150 |
box the user will be asked to specify it. After the input media is examined and |
151 |
the program is initialized, the user will be 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 email |
163 |
* Token: A token corresponding to the account defined previously |
164 |
|
165 |
After confirming, the image will be extracted, uploaded to *pithos+* and |
166 |
registered to *~okeanos*. The user will also be given the choice to keep a local |
167 |
copy of it. For most users the functionality this mode provides should be |
168 |
sufficient. |
169 |
|
170 |
Expert mode |
171 |
----------- |
172 |
|
173 |
Expert mode allows the user to have better control on the image creation |
174 |
process. In the picture below the main menu can be seen: |
175 |
|
176 |
.. image:: /snapshots/main_menu.png |
177 |
|
178 |
In the *Customize* sub-menu the user can control: |
179 |
|
180 |
* The system preparation operations that will be applied on the media |
181 |
* Whether the image will be shrunk or not |
182 |
* The properties associated with the image |
183 |
* The configuration tasks that will run during image deployment |
184 |
|
185 |
In the *Register* sub-menu the user can provide: |
186 |
|
187 |
* The credentials to login to *~okeanos* |
188 |
* A pithos filename for the uploaded *diskdump* image |
189 |
* A name for the image to be registered to *~okeanos* with |
190 |
|
191 |
By choosing the *Extract* menu entry the user can dump the image to the local |
192 |
file system and finally, if the user selects *Reset*, the system will ignore |
193 |
all changes made so far and will start the image creation process again. |