root / docs / advanced.rst @ b2b9a247
History | View | Annotate | Download (5.9 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 when resizing the partitions, especially when shrinking. |
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 |
* 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 |
* All devices in fstab should be specified by persistent names (UUID or LABEL) |
55 |
* LVMs are not supported |
56 |
* For Linux disks only ext{2,3,4} file systems are supported |
57 |
* For FreeBSD disks only UFS file systems are supported |
58 |
* For FreeBSD only GUID Partition Tables (GPT) are supported |
59 |
|
60 |
Progress Monitoring Interface |
61 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
62 |
|
63 |
*snf-image* has an embedded mechanism for transmitting progress messages during |
64 |
an image deployment. A user may specify an external executable by overwriting |
65 |
the *PROGRESS_MONITOR* variable under ``/etc/default/snf-image`` and |
66 |
*snf-image* will redirect the progress messages to the standard input of this |
67 |
program. In this section we will describe the format and the fields of the |
68 |
progress messages. |
69 |
|
70 |
The progress messages are json strings with standardized fields. All messages |
71 |
have a **type** field whose value is a string and a **timestamp** field whose |
72 |
value is a floating point number referring to a time encoded as the number of |
73 |
seconds elapsed since the epoch. The rest of the field depend on the specific |
74 |
type. |
75 |
|
76 |
image-info |
77 |
++++++++++ |
78 |
|
79 |
This message type is used to display arbitrary progress information. It has an |
80 |
extra *messages* field whose value is a list of strings. A valid ``image-info`` |
81 |
message looks like this: |
82 |
|
83 |
``{"messages": ["Starting image copy..."], "type": "image-info", "timestamp": 1378914866.209169}`` |
84 |
|
85 |
image-error |
86 |
+++++++++++ |
87 |
|
88 |
This message type is used to display a fatal error that occurred during image |
89 |
deployment. It may either have an extra *messages* field to display the error |
90 |
message or an *stderr* field to display the last lines of the standard error |
91 |
output stream of the OS creation script. Valid ``image-error`` messages look |
92 |
like this: |
93 |
|
94 |
``{"messages": ["Image customization failed."], "type": "image-error", "timestamp": 1379507045.924449}`` |
95 |
|
96 |
image-copy-progress |
97 |
+++++++++++++++++++ |
98 |
|
99 |
One of the tasks *snf-image* has to accomplish is to copy the image file into |
100 |
the VM's hard disk before configuring it. Messages of type |
101 |
``image-copy-progress`` are used to display the progress of this task. The extra |
102 |
fields this message type has is *position*, *total* and *progress*. The |
103 |
*position* field is used to display the number of bytes written to the hard |
104 |
disk. The *total* field indicates the overall size (in bytes) of the image, and |
105 |
finally the *progress* field indicates the percent of the accomplished work. |
106 |
Messages of this type look like this: |
107 |
|
108 |
``{"position": 335547996, "total": 474398720, "type": "image-copy-progress", "timestamp": 1378914869.312985, "progress": 70.73}`` |
109 |
|
110 |
image-helper |
111 |
++++++++++++ |
112 |
|
113 |
This is a family of messages that are created when *snf-image-helper* runs. |
114 |
Each message of this type has a *subtype* field. |
115 |
|
116 |
task-start |
117 |
---------- |
118 |
|
119 |
Messages with *subtype* ``task-start`` indicate that *snf-image-helper* |
120 |
started running a :ref:`configuration task <image-configuration-tasks>` on the |
121 |
image. Messages of this type have an extra *task* field whose value is the |
122 |
name of the task *snf-image-helper* started, and look like this: |
123 |
|
124 |
``{"subtype": "task-start", "task": "FixPartitionTable", "type": "image-helper", "timestamp": 1379507040.456931}`` |
125 |
|
126 |
task-stop |
127 |
--------- |
128 |
|
129 |
Messages with *subtype* ``task-stop`` are produced every time a configuration |
130 |
task successfully exits. As with the ``task-start`` messages, the *task* field |
131 |
is present: |
132 |
|
133 |
``{"subtype": "task-end", "task": "FixPartitionTable", "type": "image-helper", "timestamp": 1379507041.357184}`` |
134 |
|
135 |
warning |
136 |
------- |
137 |
|
138 |
This messages are produced to display a warning. The actual warning message |
139 |
itself is present in the *messages* field: |
140 |
|
141 |
``{"subtype": "warning", "type": "image-helper", "messages": [" No swap partition defined"], "timestamp": 1379075807.71704}`` |
142 |
|
143 |
error |
144 |
----- |
145 |
|
146 |
The last ``image-helper`` message that may occur is the ``error`` message. As |
147 |
with the ``image-error`` messages, either a *messages* field that hosts the |
148 |
actual error message or a *stderr* field that hosts the last 10 lines of the |
149 |
standard error output stream of *snf-image-helper*. Valid *error* messages look |
150 |
like this: |
151 |
|
152 |
``{"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}`` |