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