X-Git-Url: https://git.whamcloud.com/?a=blobdiff_plain;f=misc%2Fe2image.8.in;h=75002d77e7bd89a0c237de09cb0a4be69b090031;hb=bc8f1ae5237b85e1dc0ac4781da170ecc3a035fe;hp=45ee272d014f6ba855cca55e687c653fa78adf6a;hpb=11d1e61f935237dd3e851fe846ca99c723be859e;p=tools%2Fe2fsprogs.git diff --git a/misc/e2image.8.in b/misc/e2image.8.in index 45ee272..75002d7 100644 --- a/misc/e2image.8.in +++ b/misc/e2image.8.in @@ -4,57 +4,125 @@ .\" .TH E2IMAGE 8 "@E2FSPROGS_MONTH@ @E2FSPROGS_YEAR@" "E2fsprogs version @E2FSPROGS_VERSION@" .SH NAME -e2image \- Save critical ext2/ext3 filesystem data to a file +e2image \- Save critical ext2/ext3/ext4 filesystem metadata to a file .SH SYNOPSIS .B e2image [ -.B \-rI +.B \-r|Q ] +[ +.B \-fr +] +.I device +.I image-file +.br +.B e2image +.B \-I .I device .I image-file +.br +.B e2image +.B \-ra +[ +.B \-cfnp +] +[ +.B \-o +.I src_offset +] +[ +.B \-O +.I dest_offset +] +.I src_fs +[ +.I dest_fs +] .SH DESCRIPTION The .B e2image -program will save critical filesystem data on the ext2 filesystem located on -.I device -to a file specified by +program will save critical ext2, ext3, or ext4 filesystem metadata located on +.I device +to a file specified by .IR image-file . -The image file may be examined by +The image file may be examined by .B dumpe2fs and .BR debugfs , by using the .B \-i -option to those programs. This can be used by an expert in assisting -the recovery of catastrophically corrupted filesystems. In the future, +option to those programs. This can assist an expert in +recovering catastrophically corrupted filesystems. In the future, e2fsck will be enhanced to be able to use the image file to help recover a badly damaged filesystem. .PP -If +When saving an e2image for debugging purposes, using either the +.B \-r +or +.B \-Q +options, the filesystem must be unmounted or be mounted read/only, in order +for the image file to be in a consistent state. This requirement can be +overriden using the +.B \-f +option, but the resulting image file is very likely not going to be useful. +.PP +If .I image-file -is \-, then the output of +is \-, then the output of .B e2image will be sent to standard output, so that the output can be piped to -another program, such as -.BR gzip (1). -(Note that is currently only supported when -creating a raw image file using the +another program, such as +.BR gzip (1). +(Note that this is currently only supported when +creating a raw image file using the .B \-r -option, since the process of creating a normal image file currently -requires random-access access to the file, which can not be done using a +option, since the process of creating a normal image file, or QCOW2 +image currently +requires random access to the file, which cannot be done using a pipe. This restriction will hopefully be lifted in a future version of .BR e2image .) .PP -The -.B \-I +It is a very good idea to create image files for all of +filesystems on a system and save the partition +layout (which can be generated using the +.B fdisk \-l +command) at regular intervals --- at boot time, and/or every week or so. +The image file should be stored on some filesystem other than +the filesystem whose data it contains, to ensure that this data is +accessible in the case where the filesystem has been badly damaged. +.PP +To save disk space, +.B e2image +creates the image file as a sparse file, or in QCOW2 format. +Hence, if the sparse image file +needs to be copied to another location, it should +either be compressed first or copied using the +.B \-\-sparse=always +option to the GNU version of +.BR cp . +This does not apply to the QCOW2 image, which is not sparse. +.PP +The size of an ext2 image file depends primarily on the size of the +filesystems and how many inodes are in use. For a typical 10 gigabyte +filesystem, with 200,000 inodes in use out of 1.2 million inodes, the +image file will be approximately 35 megabytes; a 4 gigabyte filesystem with +15,000 inodes in use out of 550,000 inodes will result in a 3 megabyte +image file. Image files tend to be quite +compressible; an image file taking up 32 megabytes of space on +disk will generally compress down to 3 or 4 megabytes. +.PP +.SH RESTORING FILESYSTEM METADATA USING AN IMAGE FILE +.PP +The +.B \-I option will cause e2image to install the metadata stored in the image -file to the device. It can be used to restore the filesystem metadata +file back to the device. It can be used to restore the filesystem metadata back to the device in emergency situations. .PP .B WARNING!!!! The -.B \-I -option should only be used as desperation measure when other +.B \-I +option should only be used as a desperation measure when other alternatives have failed. If the filesystem has changed since the image file was created, data .B will @@ -62,56 +130,154 @@ be lost. In general, you should make a full image backup of the filesystem first, in case you wish to try other recovery strategies afterwards. .PP -The +.SH RAW IMAGE FILES +The .B \-r -option will create a raw image file instead of a normal image file. +option will create a raw image file instead of a normal image file. A raw image file differs from a normal image file in two ways. First, the filesystem metadata is placed in the proper position so that e2fsck, dumpe2fs, debugfs, -etc. can be run directly on the raw image file. In order to minimize +etc.\& can be run directly on the raw image file. In order to minimize the amount of disk space consumed by a raw image file, the file is created as a sparse file. (Beware of copying or compressing/decompressing this file with utilities that don't understand how to create sparse files; the file will become as large as the filesystem itself!) Secondly, the raw image file also includes indirect -blocks and data blocks, which the current image file does not have, +blocks and directory blocks, which the standard image file does not have, although this may change in the future. .PP -It is a very good idea to periodically (at boot time and -every week or so) to create image files for all of -filesystems on a system, as well as saving the partition -layout (which can be generated using the using -.B fdisk \-l -command). Ideally the image file should be stored on some filesystem -other that -the filesystem whose data it contains, to ensure that its data is -accessible in the case where the filesystem has been badly damaged. +Raw image files are sometimes used when sending filesystems to the maintainer +as part of bug reports to e2fsprogs. When used in this capacity, the +recommended command is as follows (replace hda1 with the appropriate device): .PP -To save disk space, +.br + \fBe2image \-r /dev/hda1 \- | bzip2 > hda1.e2i.bz2\fR +.PP +This will only send the metadata information, without any data blocks. +However, the filenames in the directory blocks can still reveal +information about the contents of the filesystem that the bug reporter +may wish to keep confidential. To address this concern, the +.B \-s +option can be specified. This will cause .B e2image -creates the image file as a sparse file. -Hence, if the image file -needs to be copied to another location, it should -either be compressed first or copied using the -.B \-\-sparse=always -option to GNU version of -.BR cp . +to scramble directory entries and zero out any unused portions +of the directory blocks before writing the image file. However, +the +.B \-s +option will prevent analysis of problems related to hash-tree indexed +directories. .PP -The size of an ext2 image file depends primarily on the size of the -filesystems and how many inodes are in use. For a typical 10 gigabyte -filesystem, with 200,000 inodes in use out of 1.2 million inodes, the -image file be approximately 35 megabytes; a 4 gigabyte filesystem with -15,000 inodes in use out of 550,000 inodes will result in a 3 megabyte -image file. Image files tend to be quite -compressible; an image file taking up 32 megabytes of space on -disk will generally compress down to 3 or 4 megabytes. +Note that this will work even if you substitute "/dev/hda1" for another raw +disk image, or QCOW2 image previously created by +.BR e2image . +.PP +.SH QCOW2 IMAGE FILES +The +.B \-Q +option will create a QCOW2 image file instead of a normal, or raw image file. +A QCOW2 image contains all the information the raw image does, however unlike +the raw image it is not sparse. The QCOW2 image minimize the amount of disk +space by storing data in special format with pack data closely together, hence +avoiding holes while still minimizing size. +.PP +In order to send filesystem to the maintainer as a part of bug report to +e2fsprogs, use following commands (replace hda1 with the appropriate device): +.PP +.br +\ \fBe2image \-Q /dev/hda1 hda1.qcow2\fR +.br +\ \fBbzip2 -z hda1.qcow2\fR .PP +This will only send the metadata information, without any data blocks. +However, the filenames in the directory blocks can still reveal +information about the contents of the filesystem that the bug reporter +may wish to keep confidential. To address this concern, the +.B \-s +option can be specified. This will cause +.B e2image +to scramble directory entries and zero out any unused portions +of the directory blocks before writing the image file. However, the +.B \-s +option will prevent analysis of problems related to hash-tree indexed +directories. +.PP +Note that QCOW2 image created by +.B e2image +is regular QCOW2 image and can be processed by tools aware of QCOW2 format +such as for example +.BR qemu-img . +.PP +You can convert a qcow2 image into a raw image with: +.PP +.br +\ \fBe2image \-r hda1.qcow2 hda1.raw\fR +.br +.PP +This can be useful to write a qcow2 image containing all data to a +sparse image file where it can be loop mounted, or to a disk partition. +Note that this may not work with qcow2 images not generated by e2image. +.PP +.SH INCLUDING DATA +Normally +.B e2image +only includes fs metadata, not regular file data. The +.B \-a +option can be specified to include all data. This will +give an image that is suitable to use to clone the entire FS or +for backup purposes. Note that this option only works with the +raw or QCOW2 formats. The +.B \-p +switch may be given to show progress. If the file system is being +cloned to a flash-based storage device (where reads are very fast and +where it is desirable to avoid unnecessary writes to reduce write wear +on the device), the +.B \-c +option which cause e2image to try reading a block from the destination +to see if it is identical to the block which +.B e2image +is about to copy. If the block is already the same, the write can be +skipped. The +.B \-n +option will cause all of the writes to be no-ops, and print the blocks +that would have been written. +.PP +.SH OFFSETS +Normally a filesystem starts at the beginning of a partition, and +.B e2image +is run on the partition. When working with image files, you don't +have the option of using the partition device, so you can specify +the offset where the filesystem starts directly with the +.B \-o +option. Similarly the +.B \-O +option specifies the offset that should be seeked to in the destination +before writing the filesystem. +.PP +For example, if you have a +.B dd +image of a whole hard drive that contains an ext2 fs in a partition +starting at 1 MiB, you can clone that fs with: +.PP +.br +\ \fBe2image \-aro 1048576 img /dev/sda1\fR +.br +.PP +Or you can clone a fs into an image file, leaving room in the first +MiB for a partition table with: +.PP +.br +\ \fBe2image -arO 1048576 /dev/sda1 img\fR +.br +.PP +If you specify at least one offset, and only one file, an in-place +move will be performed, allowing you to safely move the filesystem +from one offset to another. .SH AUTHOR -.B e2image +.B e2image was written by Theodore Ts'o (tytso@mit.edu). .SH AVAILABILITY .B e2image -is part of the e2fsprogs package and is available from +is part of the e2fsprogs package and is available from http://e2fsprogs.sourceforge.net. .SH SEE ALSO .BR dumpe2fs (8),