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