1E2IMAGE(8)                  System Manager's Manual                 E2IMAGE(8)
2
3
4

NAME

6       e2image - Save critical ext2/ext3/ext4 filesystem metadata to a file
7

SYNOPSIS

9       e2image  [  -r|-Q  ]  [  -f ] [ -b superblock ] [ -B blocksize ] device
10       image-file
11       e2image -I device image-file
12       e2image -ra [ -cfnp ] [ -o src_offset ] [ -O  dest_offset  ]  src_fs  [
13       dest_fs ]
14

DESCRIPTION

16       The  e2image  program will save critical ext2, ext3, or ext4 filesystem
17       metadata located on device to a  file  specified  by  image-file.   The
18       image  file  may  be  examined by dumpe2fs and debugfs, by using the -i
19       option to those programs.  This can assist an expert in recovering cat‐
20       astrophically  corrupted  filesystems.   In  the future, e2fsck will be
21       enhanced to be able to use the image file to help recover a badly  dam‐
22       aged filesystem.
23
24       When  saving  an e2image for debugging purposes, using either the -r or
25       -Q options, the filesystem must be unmounted or be  mounted  read/only,
26       in order for the image file to be in a consistent state.  This require‐
27       ment can be overridden using the -f option,  but  the  resulting  image
28       file is very likely not going to be useful.
29
30       If image-file is -, then the output of e2image will be sent to standard
31       output, so that the output can be piped to  another  program,  such  as
32       gzip(1).   (Note  that this is currently only supported when creating a
33       raw image file using the -r option, since the  process  of  creating  a
34       normal  image  file, or QCOW2 image currently requires random access to
35       the file, which cannot be done using a  pipe.   This  restriction  will
36       hopefully be lifted in a future version of e2image.)
37
38       It  is a very good idea to create image files for all of filesystems on
39       a system and save the partition layout (which can  be  generated  using
40       the  fdisk  -l  command)  at regular intervals --- at boot time, and/or
41       every week or so.  The image file should be stored on  some  filesystem
42       other  than  the filesystem whose data it contains, to ensure that this
43       data is accessible in the case where the filesystem has been badly dam‐
44       aged.
45
46       To save disk space, e2image creates the image file as a sparse file, or
47       in QCOW2 format.  Hence, if the sparse image file needs to be copied to
48       another  location, it should either be compressed first or copied using
49       the --sparse=always option to the GNU version of  cp.   This  does  not
50       apply to the QCOW2 image, which is not sparse.
51
52       The  size  of  an  ext2 image file depends primarily on the size of the
53       filesystems and how many inodes are in use.  For a typical 10  gigabyte
54       filesystem,  with  200,000 inodes in use out of 1.2 million inodes, the
55       image file will be approximately 35 megabytes; a 4 gigabyte  filesystem
56       with  15,000  inodes  in  use  out of 550,000 inodes will result in a 3
57       megabyte image file.  Image files tend to  be  quite  compressible;  an
58       image  file taking up 32 megabytes of space on disk will generally com‐
59       press down to 3 or 4 megabytes.
60

RESTORING FILESYSTEM METADATA USING AN IMAGE FILE

62       The -I option will cause e2image to install the metadata stored in  the
63       image  file back to the device.  It can be used to restore the filesys‐
64       tem metadata back to the device in emergency situations.
65
66       WARNING!!!!  The -I option should only be used as a desperation measure
67       when  other  alternatives  have  failed.  If the filesystem has changed
68       since the image file was created, data will be lost.  In  general,  you
69       should  make  a  full image backup of the filesystem first, in case you
70       wish to try other recovery strategies afterwards.
71

RAW IMAGE FILES

73       The -r option will create a raw image file instead of  a  normal  image
74       file.   A  raw image file differs from a normal image file in two ways.
75       First, the filesystem metadata is placed in the proper position so that
76       e2fsck,  dumpe2fs,  debugfs,  etc. can be run directly on the raw image
77       file.  In order to minimize the amount of disk space consumed by a  raw
78       image  file,  the file is created as a sparse file.  (Beware of copying
79       or compressing/decompressing this file with utilities that don't under‐
80       stand  how to create sparse files; the file will become as large as the
81       filesystem itself!)  Secondly, the raw image file also  includes  indi‐
82       rect  blocks  and  directory blocks, which the standard image file does
83       not have, although this may change in the future.
84
85       Raw image files are sometimes used  when  sending  filesystems  to  the
86       maintainer  as  part  of  bug  reports to e2fsprogs.  When used in this
87       capacity, the recommended command is as follows (replace hda1 with  the
88       appropriate device):
89
90            e2image -r /dev/hda1 - | bzip2 > hda1.e2i.bz2
91
92       This  will only send the metadata information, without any data blocks.
93       However, the filenames in the directory blocks can still reveal  infor‐
94       mation  about  the contents of the filesystem that the bug reporter may
95       wish to keep confidential.  To address this concern, the -s option  can
96       be  specified.   This  will cause e2image to scramble directory entries
97       and zero out any unused portions of the directory blocks before writing
98       the  image file.  However, the -s option will prevent analysis of prob‐
99       lems related to hash-tree indexed directories.
100
101       Option -b superblock can be used to get image from partition with  bro‐
102       ken primary superblock.  The partition is copied as-is including broken
103       primary superblock.
104
105       Option -B blocksize can be used to set superblock block size. Normally,
106       e2fsck  will search for the superblock at various different block sizes
107       in an attempt to find the appropriate blocksize.  This  search  can  be
108       fooled  in  some cases.  This option forces e2fsck to only try locating
109       the superblock at a particular blocksize.  If  the  superblock  is  not
110       found, e2fsck will terminate with a fatal error.
111
112       Note that this will work even if you substitute "/dev/hda1" for another
113       raw disk image, or QCOW2 image previously created by e2image.
114

QCOW2 IMAGE FILES

116       The -Q option will create a QCOW2 image file instead of  a  normal,  or
117       raw  image  file.   A  QCOW2 image contains all the information the raw
118       image does, however unlike the raw image it is not  sparse.  The  QCOW2
119       image minimize the amount of disk space by storing data in special for‐
120       mat with pack data closely together, hence avoiding holes  while  still
121       minimizing size.
122
123       In  order  to send filesystem to the maintainer as a part of bug report
124       to e2fsprogs, use following commands (replace hda1 with the appropriate
125       device):
126
127            e2image -Q /dev/hda1 hda1.qcow2
128            bzip2 -z hda1.qcow2
129
130       This  will only send the metadata information, without any data blocks.
131       However, the filenames in the directory blocks can still reveal  infor‐
132       mation  about  the contents of the filesystem that the bug reporter may
133       wish to keep confidential.  To address this concern, the -s option  can
134       be  specified.   This  will cause e2image to scramble directory entries
135       and zero out any unused portions of the directory blocks before writing
136       the  image file.  However, the -s option will prevent analysis of prob‐
137       lems related to hash-tree indexed directories.
138
139       Note that QCOW2 image created by e2image is regular QCOW2 image and can
140       be  processed  by tools aware of QCOW2 format such as for example qemu-
141       img.
142
143       You can convert a qcow2 image into a raw image with:
144
145            e2image -r hda1.qcow2 hda1.raw
146
147       This can be useful to write a qcow2 image  containing  all  data  to  a
148       sparse image file where it can be loop mounted, or to a disk partition.
149       Note that this may not work with qcow2 images not generated by e2image.
150
151       Options -b superblock and -B blocksize can be used same way as for  raw
152       images.
153

INCLUDING DATA

155       Normally e2image only includes fs metadata, not regular file data.  The
156       -a option can be specified to include all  data.   This  will  give  an
157       image that is suitable to use to clone the entire FS or for backup pur‐
158       poses.  Note that this option only works with the raw or QCOW2 formats.
159       The  -p  switch  may  be given to show progress.  If the file system is
160       being cloned to a flash-based storage device (where reads are very fast
161       and  where  it is desirable to avoid unnecessary writes to reduce write
162       wear on the device), the -c option which cause e2image to try reading a
163       block from the destination to see if it is identical to the block which
164       e2image is about to copy.  If the block is already the same, the  write
165       can  be  skipped.  The -n option will cause all of the writes to be no-
166       ops, and print the blocks that would have been written.
167

OFFSETS

169       Normally a filesystem starts at  the  beginning  of  a  partition,  and
170       e2image  is  run  on the partition.  When working with image files, you
171       don't have the option of using the partition device, so you can specify
172       the  offset  where  the  filesystem starts directly with the -o option.
173       Similarly the -O option specifies the offset that should be  seeked  to
174       in the destination before writing the filesystem.
175
176       For example, if you have a dd image of a whole hard drive that contains
177       an ext2 fs in a partition starting at 1 MiB,  you  can  clone  that  fs
178       with:
179
180            e2image -aro 1048576 img /dev/sda1
181
182       Or you can clone a fs into an image file, leaving room in the first MiB
183       for a partition table with:
184
185            e2image -arO 1048576 /dev/sda1 img
186
187       If you specify at least one offset, and only one file, an in-place move
188       will  be performed, allowing you to safely move the filesystem from one
189       offset to another.
190

AUTHOR

192       e2image was written by Theodore Ts'o (tytso@mit.edu).
193

AVAILABILITY

195       e2image is  part  of  the  e2fsprogs  package  and  is  available  from
196       http://e2fsprogs.sourceforge.net.
197

SEE ALSO

199       dumpe2fs(8), debugfs(8)
200
201
202
203
204E2fsprogs version 1.45.6          March 2020                        E2IMAGE(8)
Impressum