root / docs / advanced.rst @ 5e2e29b9
History | View | Annotate | Download (6 kB)
1 |
Advanced Topics |
---|---|
2 |
=============== |
3 |
|
4 |
.. _image-format-advanced: |
5 |
|
6 |
Image Format |
7 |
^^^^^^^^^^^^ |
8 |
|
9 |
snf-image supports 3 types of image formats: |
10 |
|
11 |
* **extdump**: a raw dump of an ext{2,3,4} file system |
12 |
* **ntfsdump**: a raw dump of an NTFS file system |
13 |
* **diskdump** (recommended): a raw dump of a disk |
14 |
|
15 |
extdump and ntfsdump image formats |
16 |
++++++++++++++++++++++++++++++++++ |
17 |
|
18 |
Those two formats are dumps (raw copies using dd) of partitions hosting Linux |
19 |
systems on ext{2,3,4} and Windows systems on ntfs file systems respectively. |
20 |
Partitions hosting a Windows or Linux system that are suitable for dumping |
21 |
should have the following properties: |
22 |
|
23 |
* Be the first partition in the file system |
24 |
* The OS they host should not depend on any other partitions |
25 |
* Start at sector 2048 |
26 |
* Have a boot loader installed in the boot sector of the partition (not MBR) |
27 |
* Have the root device in */etc/fstab* specified in a persistent way, using |
28 |
UUID or LABEL (for extdump only) |
29 |
|
30 |
Known Issues |
31 |
------------ |
32 |
|
33 |
* For Linux systems, having grub installed in the partition is fragile and |
34 |
things can go wrong if you shrink the partition. |
35 |
* More complicated partition schemes are not supported. |
36 |
|
37 |
diskdump image format (recommended) |
38 |
+++++++++++++++++++++++++++++++++++ |
39 |
|
40 |
Diskdump is a newer format that overcomes most of the aforementioned issues. |
41 |
This format is a dump (raw copy using dd) of a whole disk. |
42 |
|
43 |
This design decision has the following benefits: |
44 |
|
45 |
* Swap partitions are supported |
46 |
* The system may use multiple partitions: |
47 |
* Dedicated partitions for /boot, /home etc. in Linux |
48 |
* Separate system and boot partition in Windows |
49 |
* There are no restrictions on starting sectors of partitions |
50 |
|
51 |
Although diskdump is a lot more flexible than the older formats, there are |
52 |
still some rules to follow: |
53 |
|
54 |
* For Linux: |
55 |
* All block devices in */etc/fstab* should be specified using persistent |
56 |
names (UUID or LABEL) |
57 |
* LVM partitions are not supported |
58 |
* Only ext{2,3,4} file systems are supported |
59 |
* For FreeBSD: |
60 |
* GUID Partition Tables (GPT) should be used |
61 |
* Only UFS2 file systems are supported |
62 |
* Labels should be omitted in */etc/fstab* entries |
63 |
* For {Open,Net}BSD: |
64 |
* Only FFS file systems should be used |
65 |
|
66 |
Progress Monitoring Interface |
67 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
68 |
|
69 |
*snf-image* has an embedded mechanism for transmitting progress messages during |
70 |
an image deployment. A user may specify an external executable by overwriting |
71 |
the *PROGRESS_MONITOR* variable under ``/etc/default/snf-image`` and |
72 |
*snf-image* will redirect the progress messages to the standard input of this |
73 |
program. In this section we will describe the format and the fields of the |
74 |
progress messages. |
75 |
|
76 |
The progress messages are JSON strings with standardized fields. All messages |
77 |
have a **type** field whose value is a string and a **timestamp** field whose |
78 |
value is a floating point number referring to a time encoded as the number of |
79 |
seconds elapsed since the epoch. The rest of the field depend on the specific |
80 |
type. |
81 |
|
82 |
image-info |
83 |
++++++++++ |
84 |
|
85 |
This message type is used to display arbitrary progress information. It has an |
86 |
extra *messages* field whose value is a list of strings. A valid ``image-info`` |
87 |
message looks like this: |
88 |
|
89 |
``{"messages": ["Starting image copy..."], "type": "image-info", "timestamp": 1378914866.209169}`` |
90 |
|
91 |
image-error |
92 |
+++++++++++ |
93 |
|
94 |
This message type is used to display a fatal error that occurred during image |
95 |
deployment. It may either have an extra *messages* field to display the error |
96 |
message or an *stderr* field to display the last lines of the standard error |
97 |
output stream of the OS creation script. Valid ``image-error`` messages look |
98 |
like this: |
99 |
|
100 |
``{"messages": ["Image customization failed."], "type": "image-error", "timestamp": 1379507045.924449}`` |
101 |
|
102 |
image-copy-progress |
103 |
+++++++++++++++++++ |
104 |
|
105 |
One of the tasks *snf-image* has to accomplish is to copy the image file into |
106 |
the VM's hard disk before configuring it. Messages of type |
107 |
``image-copy-progress`` are used to display the progress of this task. The extra |
108 |
fields this message type has is *position*, *total* and *progress*. The |
109 |
*position* field is used to display the number of bytes written to the hard |
110 |
disk. The *total* field indicates the overall size (in bytes) of the image, and |
111 |
finally the *progress* field indicates the percent of the accomplished work. |
112 |
Messages of this type look like this: |
113 |
|
114 |
``{"position": 335547996, "total": 474398720, "type": "image-copy-progress", "timestamp": 1378914869.312985, "progress": 70.73}`` |
115 |
|
116 |
image-helper |
117 |
++++++++++++ |
118 |
|
119 |
This is a family of messages that are created when *snf-image-helper* runs. |
120 |
Each message of this type has a *subtype* field. |
121 |
|
122 |
task-start |
123 |
---------- |
124 |
|
125 |
Messages with *subtype* ``task-start`` indicate that *snf-image-helper* |
126 |
started running a :ref:`configuration task <image-configuration-tasks>` on the |
127 |
image. Messages of this type have an extra *task* field whose value is the |
128 |
name of the task *snf-image-helper* started, and look like this: |
129 |
|
130 |
``{"subtype": "task-start", "task": "FixPartitionTable", "type": "image-helper", "timestamp": 1379507040.456931}`` |
131 |
|
132 |
task-stop |
133 |
--------- |
134 |
|
135 |
Messages with *subtype* ``task-stop`` are produced every time a configuration |
136 |
task successfully exits. As with the ``task-start`` messages, the *task* field |
137 |
is present: |
138 |
|
139 |
``{"subtype": "task-end", "task": "FixPartitionTable", "type": "image-helper", "timestamp": 1379507041.357184}`` |
140 |
|
141 |
warning |
142 |
------- |
143 |
|
144 |
This messages are produced to display a warning. The actual warning message |
145 |
itself is present in the *messages* field: |
146 |
|
147 |
``{"subtype": "warning", "type": "image-helper", "messages": ["No swap partition defined"], "timestamp": 1379075807.71704}`` |
148 |
|
149 |
error |
150 |
----- |
151 |
|
152 |
The last ``image-helper`` message that may occur is the ``error`` message. As |
153 |
with the ``image-error`` messages, either a *messages* field that hosts the |
154 |
actual error message or a *stderr* field that hosts the last 10 lines of the |
155 |
standard error output stream of *snf-image-helper*. Valid *error* messages look |
156 |
like this: |
157 |
|
158 |
``{"subtype": "error", "type": "image-helper", "messages": ["The image contains a(n) msdos partition table. For FreeBSD images only GUID Partition Tables are supported."], "timestamp": 1379507910.799365}`` |