misc/e2image.8.in

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