]>
Commit | Line | Data |
---|---|---|
348e43dc TT |
1 | .\" -*- nroff -*- |
2 | .\" Copyright 2001 by Theodore Ts'o. All Rights Reserved. | |
3 | .\" This file may be copied under the terms of the GNU Public License. | |
b5bdc043 | 4 | .\" |
348e43dc TT |
5 | .TH E2IMAGE 8 "@E2FSPROGS_MONTH@ @E2FSPROGS_YEAR@" "E2fsprogs version @E2FSPROGS_VERSION@" |
6 | .SH NAME | |
e87bb84b | 7 | e2image \- Save critical ext2/ext3/ext4 file system metadata to a file |
b5bdc043 | 8 | |
348e43dc TT |
9 | .SH SYNOPSIS |
10 | .B e2image | |
b5bdc043 | 11 | .RB [ \-r | \-Q " [" \-af ]] |
6607eaad | 12 | [ |
3f3e455f AB |
13 | .B \-b |
14 | .I superblock | |
15 | ] | |
16 | [ | |
17 | .B \-B | |
18 | .I blocksize | |
19 | ] | |
c003f48b | 20 | [ |
b5bdc043 | 21 | .B \-cnps |
6304baf2 | 22 | ] |
6b5535f4 PS |
23 | [ |
24 | .B \-o | |
c003f48b | 25 | .I src_offset |
6b5535f4 PS |
26 | ] |
27 | [ | |
28 | .B \-O | |
29 | .I dest_offset | |
30 | ] | |
b5bdc043 AD |
31 | .I device |
32 | .I image-file | |
33 | .br | |
34 | .B e2image | |
35 | .B \-I | |
36 | .I device | |
37 | .I image-file | |
38 | ||
348e43dc | 39 | .SH DESCRIPTION |
0edb4d85 | 40 | The |
348e43dc | 41 | .B e2image |
e87bb84b | 42 | program will save critical ext2, ext3, or ext4 file system metadata located on |
4780e870 TT |
43 | .I device |
44 | to a file specified by | |
0edb4d85 | 45 | .IR image-file . |
4780e870 | 46 | The image file may be examined by |
0edb4d85 TT |
47 | .B dumpe2fs |
48 | and | |
49 | .BR debugfs , | |
50 | by using the | |
51 | .B \-i | |
b5bdc043 | 52 | option to those programs. This can assist an expert in recovering |
e87bb84b | 53 | catastrophically corrupted file systems. |
0edb4d85 | 54 | .PP |
e87bb84b | 55 | It is a very good idea to create image files for all file systems on a |
b5bdc043 | 56 | system and save the partition layout (which can be generated using the |
d851ed39 | 57 | .B fdisk \-l |
b7c1d202 | 58 | command) at regular intervals --- at boot time, and/or every week or so. |
e87bb84b TT |
59 | The image file should be stored on some file system other than |
60 | the file system whose data it contains, to ensure that this data is | |
61 | accessible in the case where the file system has been badly damaged. | |
d851ed39 | 62 | .PP |
4780e870 | 63 | To save disk space, |
d851ed39 | 64 | .B e2image |
b5bdc043 AD |
65 | creates the image file as a sparse file, or in QCOW2 format. Hence, if |
66 | the sparse image file needs to be copied to another location, it should | |
4780e870 | 67 | either be compressed first or copied using the |
d851ed39 | 68 | .B \-\-sparse=always |
4780e870 | 69 | option to the GNU version of |
b5bdc043 | 70 | .BR cp (1). |
bf0449b1 | 71 | This does not apply to the QCOW2 image, which is not sparse. |
d851ed39 TT |
72 | .PP |
73 | The size of an ext2 image file depends primarily on the size of the | |
e87bb84b TT |
74 | file systems and how many inodes are in use. For a typical 10 Gigabyte |
75 | file system, with 200,000 inodes in use out of 1.2 million inodes, the image | |
76 | file will be approximately 35 Megabytes; a 4 Gigabyte file system with 15,000 | |
b5bdc043 AD |
77 | inodes in use out of 550,000 inodes will result in a 3 Megabyte image file. |
78 | Image files tend to be quite compressible; an image file taking up 32 Megabytes | |
79 | of space on disk will generally compress down to 3 or 4 Megabytes. | |
d851ed39 | 80 | .PP |
b5bdc043 AD |
81 | If |
82 | .I image-file | |
83 | is | |
84 | .BR \- , | |
85 | then the output of | |
86 | .B e2image | |
87 | will be sent to standard output, so that the output can be piped to | |
88 | another program, such as | |
89 | .BR gzip (1). | |
90 | (Note that this is currently only supported when | |
91 | creating a raw image file using the | |
92 | .B \-r | |
93 | option, since the process of creating a normal image file, or QCOW2 | |
94 | image currently | |
95 | requires random access to the file, which cannot be done using a | |
96 | pipe. | |
97 | ||
98 | .SH OPTIONS | |
99 | .TP | |
100 | .B \-a | |
101 | Include file data in the image file. Normally | |
102 | .B e2image | |
103 | only includes fs metadata, not regular file data. This option will | |
104 | produce an image that is suitable to use to clone the entire FS or | |
105 | for backup purposes. Note that this option only works with the | |
106 | raw | |
107 | .RI ( \-r ) | |
108 | or QCOW2 | |
109 | .RI ( \-Q ) | |
110 | formats. In conjunction with the | |
111 | .B \-r | |
112 | option it is possible to clone all and only the used blocks of one | |
e87bb84b | 113 | file system to another device/image file. |
b5bdc043 AD |
114 | .TP |
115 | .BI \-b " superblock" | |
116 | Get image from partition with broken primary superblock by using | |
e87bb84b | 117 | the superblock located at file system block number |
b5bdc043 AD |
118 | .IR superblock . |
119 | The partition is copied as-is including broken primary superblock. | |
120 | .TP | |
121 | .BI \-B " blocksize" | |
e87bb84b | 122 | Set the file system blocksize in bytes. Normally, |
b5bdc043 AD |
123 | .B e2image |
124 | will search for the superblock at various different block sizes in an | |
125 | attempt to find the appropriate blocksize. This search can be fooled in | |
126 | some cases. This option forces e2fsck to only try locating the superblock | |
127 | with a particular blocksize. If the superblock is not found, e2image will | |
128 | terminate with a fatal error. | |
129 | .TP | |
130 | .BI \-c | |
131 | Compare each block to be copied from the source | |
132 | .I device | |
133 | to the corresponding block in the target | |
134 | .IR image-file . | |
135 | If both are already the same, the write will be skipped. This is | |
136 | useful if the file system is being cloned to a flash-based storage device | |
137 | (where reads are very fast and where it is desirable to avoid unnecessary | |
138 | writes to reduce write wear on the device). | |
139 | .TP | |
140 | .B \-f | |
e87bb84b | 141 | Override the read-only requirement for the source file system when saving |
b5bdc043 AD |
142 | the image file using the |
143 | .B \-r | |
144 | and | |
145 | .B \-Q | |
e87bb84b | 146 | options. Normally, if the source file system is in use, the resulting image |
b5bdc043 | 147 | file is very likely not going to be useful. In some cases where the source |
e87bb84b | 148 | file system is in constant use this may be better than no image at all. |
b5bdc043 | 149 | .TP |
4780e870 | 150 | .B \-I |
b5bdc043 | 151 | install the metadata stored in the image file back to the device. |
e87bb84b | 152 | It can be used to restore the file system metadata back to the device |
b5bdc043 | 153 | in emergency situations. |
8c6b6483 TT |
154 | .PP |
155 | .B WARNING!!!! | |
156 | The | |
4780e870 | 157 | .B \-I |
b7c1d202 | 158 | option should only be used as a desperation measure when other |
e87bb84b | 159 | alternatives have failed. If the file system has changed since the image |
8c6b6483 TT |
160 | file was created, data |
161 | .B will | |
b5bdc043 | 162 | be lost. In general, you should make another full image backup of the |
e87bb84b | 163 | file system first, in case you wish to try other recovery strategies afterward. |
b5bdc043 AD |
164 | .TP |
165 | .B \-n | |
166 | Cause all image writes to be skipped, and instead only print the block | |
167 | numbers that would have been written. | |
168 | .TP | |
169 | .BI \-o " src_offset" | |
170 | Specify offset of the image to be read from the start of the source | |
171 | .I device | |
172 | in bytes. See | |
173 | .B OFFSETS | |
174 | for more details. | |
175 | .TP | |
176 | .BI \-O " tgt_offset" | |
177 | Specify offset of the image to be written from the start of the target | |
178 | .I image-file | |
179 | in bytes. See | |
180 | .B OFFSETS | |
181 | for more details. | |
182 | .TP | |
183 | .B \-p | |
184 | Show progress of image-file creation. | |
185 | .TP | |
186 | .B \-Q | |
187 | Create a QCOW2-format image file instead of a normal image file, suitable | |
188 | for use by virtual machine images, and other tools that can use the | |
189 | .B .qcow | |
190 | image format. See | |
191 | .B QCOW2 IMAGE FILES | |
192 | below for details. | |
193 | .TP | |
194 | .B \-r | |
195 | Create a raw image file instead of a normal image file. See | |
196 | .B RAW IMAGE FILES | |
197 | below for details. | |
198 | .TP | |
199 | .B \-s | |
200 | Scramble directory entries and zero out unused portions of the directory | |
201 | blocks in the written image file to avoid revealing information about | |
e87bb84b | 202 | the contents of the file system. However, this will prevent analysis of |
b5bdc043 AD |
203 | problems related to hash-tree indexed directories. |
204 | ||
d851ed39 | 205 | .SH RAW IMAGE FILES |
4780e870 | 206 | The |
6304baf2 | 207 | .B \-r |
b5bdc043 | 208 | option will create a raw image file, which differs |
e87bb84b | 209 | from a normal image file in two ways. First, the file system metadata is |
b5bdc043 AD |
210 | placed in the same relative offset within |
211 | .I image-file | |
212 | as it is in the | |
213 | .I device | |
214 | so that | |
215 | .BR debugfs (8), | |
216 | .BR dumpe2fs (8), | |
217 | .BR e2fsck (8), | |
218 | .BR losetup (8), | |
219 | etc. and can be run directly on the raw image file. In order to minimize | |
220 | the amount of disk space consumed by the raw image file, it is | |
6304baf2 TT |
221 | created as a sparse file. (Beware of copying or |
222 | compressing/decompressing this file with utilities that don't understand | |
223 | how to create sparse files; the file will become as large as the | |
e87bb84b | 224 | file system itself!) Secondly, the raw image file also includes indirect |
b5bdc043 | 225 | blocks and directory blocks, which the standard image file does not have. |
6304baf2 | 226 | .PP |
e87bb84b | 227 | Raw image files are sometimes used when sending file systems to the maintainer |
b7c1d202 | 228 | as part of bug reports to e2fsprogs. When used in this capacity, the |
b5bdc043 AD |
229 | recommended command is as follows (replace |
230 | .B hda1 | |
231 | with the appropriate device for your system): | |
0edb4d85 | 232 | .PP |
d851ed39 | 233 | .br |
4780e870 | 234 | \fBe2image \-r /dev/hda1 \- | bzip2 > hda1.e2i.bz2\fR |
0edb4d85 | 235 | .PP |
4780e870 | 236 | This will only send the metadata information, without any data blocks. |
d851ed39 | 237 | However, the filenames in the directory blocks can still reveal |
e87bb84b | 238 | information about the contents of the file system that the bug reporter |
d851ed39 TT |
239 | may wish to keep confidential. To address this concern, the |
240 | .B \-s | |
b5bdc043 | 241 | option can be specified to scramble the filenames in the image. |
348e43dc | 242 | .PP |
b5bdc043 AD |
243 | Note that this will work even if you substitute |
244 | .B /dev/hda1 | |
245 | for another raw | |
92dcfb76 LC |
246 | disk image, or QCOW2 image previously created by |
247 | .BR e2image . | |
b5bdc043 | 248 | |
bf0449b1 LC |
249 | .SH QCOW2 IMAGE FILES |
250 | The | |
251 | .B \-Q | |
252 | option will create a QCOW2 image file instead of a normal, or raw image file. | |
253 | A QCOW2 image contains all the information the raw image does, however unlike | |
b5bdc043 AD |
254 | the raw image it is not sparse. The QCOW2 image minimize the amount of space |
255 | used by the image by storing it in special format which packs data closely | |
256 | together, hence avoiding holes while still minimizing size. | |
bf0449b1 | 257 | .PP |
e87bb84b | 258 | In order to send file system to the maintainer as a part of bug report to |
b5bdc043 AD |
259 | e2fsprogs, use following commands (replace |
260 | .B hda1 | |
261 | with the appropriate device for your system): | |
bf0449b1 LC |
262 | .PP |
263 | .br | |
264 | \ \fBe2image \-Q /dev/hda1 hda1.qcow2\fR | |
265 | .br | |
266 | \ \fBbzip2 -z hda1.qcow2\fR | |
267 | .PP | |
268 | This will only send the metadata information, without any data blocks. | |
b5bdc043 AD |
269 | As described for |
270 | .B RAW IMAGE FILES | |
271 | the | |
bf0449b1 | 272 | .B \-s |
e87bb84b | 273 | option can be specified to scramble the file system names in the image. |
bf0449b1 | 274 | .PP |
b5bdc043 | 275 | Note that the QCOW2 image created by |
bf0449b1 | 276 | .B e2image |
b5bdc043 | 277 | is a regular QCOW2 image and can be processed by tools aware of QCOW2 format |
bf0449b1 LC |
278 | such as for example |
279 | .BR qemu-img . | |
280 | .PP | |
b5bdc043 | 281 | You can convert a .qcow2 image into a raw image with: |
0e51f5ae PS |
282 | .PP |
283 | .br | |
284 | \ \fBe2image \-r hda1.qcow2 hda1.raw\fR | |
285 | .br | |
286 | .PP | |
b5bdc043 | 287 | This can be useful to write a QCOW2 image containing all data to a |
0e51f5ae | 288 | sparse image file where it can be loop mounted, or to a disk partition. |
b5bdc043 AD |
289 | Note that this may not work with QCOW2 images not generated by e2image. |
290 | ||
6b5535f4 | 291 | .SH OFFSETS |
e87bb84b | 292 | Normally a file system starts at the beginning of a partition, and |
6b5535f4 PS |
293 | .B e2image |
294 | is run on the partition. When working with image files, you don't | |
295 | have the option of using the partition device, so you can specify | |
e87bb84b | 296 | the offset where the file system starts directly with the |
6b5535f4 PS |
297 | .B \-o |
298 | option. Similarly the | |
299 | .B \-O | |
300 | option specifies the offset that should be seeked to in the destination | |
e87bb84b | 301 | before writing the file system. |
6b5535f4 PS |
302 | .PP |
303 | For example, if you have a | |
304 | .B dd | |
305 | image of a whole hard drive that contains an ext2 fs in a partition | |
b5bdc043 | 306 | starting at 1 MiB, you can clone that image to a block device with: |
6b5535f4 PS |
307 | .PP |
308 | .br | |
309 | \ \fBe2image \-aro 1048576 img /dev/sda1\fR | |
310 | .br | |
311 | .PP | |
e87bb84b | 312 | Or you can clone a file system from a block device into an image file, |
b5bdc043 | 313 | leaving room in the first MiB for a partition table with: |
6b5535f4 PS |
314 | .PP |
315 | .br | |
316 | \ \fBe2image -arO 1048576 /dev/sda1 img\fR | |
317 | .br | |
318 | .PP | |
22b83f62 | 319 | If you specify at least one offset, and only one file, an in-place |
e87bb84b | 320 | move will be performed, allowing you to safely move the file system |
22b83f62 | 321 | from one offset to another. |
b5bdc043 | 322 | |
348e43dc | 323 | .SH AUTHOR |
4780e870 | 324 | .B e2image |
348e43dc | 325 | was written by Theodore Ts'o (tytso@mit.edu). |
b5bdc043 | 326 | |
348e43dc TT |
327 | .SH AVAILABILITY |
328 | .B e2image | |
4780e870 | 329 | is part of the e2fsprogs package and is available from |
348e43dc | 330 | http://e2fsprogs.sourceforge.net. |
b5bdc043 | 331 | |
348e43dc TT |
332 | .SH SEE ALSO |
333 | .BR dumpe2fs (8), | |
334 | .BR debugfs (8) | |
b5bdc043 | 335 | .BR e2fsck (8) |