Theodore Ts'o | 348e43d | 2001-05-03 14:43:43 +0000 | [diff] [blame] | 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 |
Theodore Ts'o | 4f85854 | 2009-05-30 12:34:28 -0400 | [diff] [blame] | 7 | e2image \- Save critical ext2/ext3/ext4 filesystem metadata to a file |
Theodore Ts'o | 348e43d | 2001-05-03 14:43:43 +0000 | [diff] [blame] | 8 | .SH SYNOPSIS |
| 9 | .B e2image |
Theodore Ts'o | 6304baf | 2001-08-09 05:41:29 -0400 | [diff] [blame] | 10 | [ |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 11 | .B \-rsI |
Theodore Ts'o | 6304baf | 2001-08-09 05:41:29 -0400 | [diff] [blame] | 12 | ] |
Theodore Ts'o | 348e43d | 2001-05-03 14:43:43 +0000 | [diff] [blame] | 13 | .I device |
| 14 | .I image-file |
| 15 | .SH DESCRIPTION |
Theodore Ts'o | 0edb4d8 | 2001-05-03 16:30:48 +0000 | [diff] [blame] | 16 | The |
Theodore Ts'o | 348e43d | 2001-05-03 14:43:43 +0000 | [diff] [blame] | 17 | .B e2image |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 18 | program will save critical ext2, ext3, or ext4 filesystem metadata located on |
| 19 | .I device |
| 20 | to a file specified by |
Theodore Ts'o | 0edb4d8 | 2001-05-03 16:30:48 +0000 | [diff] [blame] | 21 | .IR image-file . |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 22 | The image file may be examined by |
Theodore Ts'o | 0edb4d8 | 2001-05-03 16:30:48 +0000 | [diff] [blame] | 23 | .B dumpe2fs |
| 24 | and |
| 25 | .BR debugfs , |
| 26 | by using the |
| 27 | .B \-i |
Theodore Ts'o | b7c1d20 | 2005-06-20 08:26:50 -0400 | [diff] [blame] | 28 | option to those programs. This can assist an expert in |
| 29 | recovering catastrophically corrupted filesystems. In the future, |
Theodore Ts'o | 0edb4d8 | 2001-05-03 16:30:48 +0000 | [diff] [blame] | 30 | e2fsck will be enhanced to be able to use the image file to help |
| 31 | recover a badly damaged filesystem. |
| 32 | .PP |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 33 | If |
Theodore Ts'o | 1c1e004 | 2001-08-09 06:04:32 -0400 | [diff] [blame] | 34 | .I image-file |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 35 | is \-, then the output of |
Theodore Ts'o | 1c1e004 | 2001-08-09 06:04:32 -0400 | [diff] [blame] | 36 | .B e2image |
Theodore Ts'o | 8ac5929 | 2004-03-08 14:18:56 -0500 | [diff] [blame] | 37 | will be sent to standard output, so that the output can be piped to |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 38 | another program, such as |
| 39 | .BR gzip (1). |
Theodore Ts'o | b7c1d20 | 2005-06-20 08:26:50 -0400 | [diff] [blame] | 40 | (Note that this is currently only supported when |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 41 | creating a raw image file using the |
Theodore Ts'o | 8ac5929 | 2004-03-08 14:18:56 -0500 | [diff] [blame] | 42 | .B \-r |
Lukas Czerner | bf0449b | 2011-05-18 13:36:53 +0200 | [diff] [blame] | 43 | option, since the process of creating a normal image file, or QCOW2 |
| 44 | image currently |
Theodore Ts'o | b7c1d20 | 2005-06-20 08:26:50 -0400 | [diff] [blame] | 45 | requires random access to the file, which cannot be done using a |
Theodore Ts'o | 8ac5929 | 2004-03-08 14:18:56 -0500 | [diff] [blame] | 46 | pipe. This restriction will hopefully be lifted in a future version of |
| 47 | .BR e2image .) |
Theodore Ts'o | 1c1e004 | 2001-08-09 06:04:32 -0400 | [diff] [blame] | 48 | .PP |
Theodore Ts'o | b7c1d20 | 2005-06-20 08:26:50 -0400 | [diff] [blame] | 49 | It is a very good idea to create image files for all of |
| 50 | filesystems on a system and save the partition |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 51 | layout (which can be generated using the |
Theodore Ts'o | 11d1e61 | 2004-12-01 12:42:33 -0500 | [diff] [blame] | 52 | .B fdisk \-l |
Theodore Ts'o | b7c1d20 | 2005-06-20 08:26:50 -0400 | [diff] [blame] | 53 | command) at regular intervals --- at boot time, and/or every week or so. |
Theodore Ts'o | d9781ce | 2005-06-26 22:16:21 -0400 | [diff] [blame] | 54 | The image file should be stored on some filesystem other than |
| 55 | the filesystem whose data it contains, to ensure that this data is |
Theodore Ts'o | 0edb4d8 | 2001-05-03 16:30:48 +0000 | [diff] [blame] | 56 | accessible in the case where the filesystem has been badly damaged. |
| 57 | .PP |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 58 | To save disk space, |
Theodore Ts'o | 0edb4d8 | 2001-05-03 16:30:48 +0000 | [diff] [blame] | 59 | .B e2image |
Lukas Czerner | bf0449b | 2011-05-18 13:36:53 +0200 | [diff] [blame] | 60 | creates the image file as a sparse file, or in QCOW2 format. |
| 61 | Hence, if the sparse image file |
Theodore Ts'o | 0edb4d8 | 2001-05-03 16:30:48 +0000 | [diff] [blame] | 62 | needs to be copied to another location, it should |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 63 | either be compressed first or copied using the |
Theodore Ts'o | 11d1e61 | 2004-12-01 12:42:33 -0500 | [diff] [blame] | 64 | .B \-\-sparse=always |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 65 | option to the GNU version of |
Lukas Czerner | bf0449b | 2011-05-18 13:36:53 +0200 | [diff] [blame] | 66 | .BR cp . |
| 67 | This does not apply to the QCOW2 image, which is not sparse. |
Theodore Ts'o | 0edb4d8 | 2001-05-03 16:30:48 +0000 | [diff] [blame] | 68 | .PP |
| 69 | The size of an ext2 image file depends primarily on the size of the |
| 70 | filesystems and how many inodes are in use. For a typical 10 gigabyte |
| 71 | filesystem, with 200,000 inodes in use out of 1.2 million inodes, the |
Theodore Ts'o | b7c1d20 | 2005-06-20 08:26:50 -0400 | [diff] [blame] | 72 | image file will be approximately 35 megabytes; a 4 gigabyte filesystem with |
Theodore Ts'o | 0edb4d8 | 2001-05-03 16:30:48 +0000 | [diff] [blame] | 73 | 15,000 inodes in use out of 550,000 inodes will result in a 3 megabyte |
| 74 | image file. Image files tend to be quite |
Theodore Ts'o | 6304baf | 2001-08-09 05:41:29 -0400 | [diff] [blame] | 75 | compressible; an image file taking up 32 megabytes of space on |
Theodore Ts'o | 0edb4d8 | 2001-05-03 16:30:48 +0000 | [diff] [blame] | 76 | disk will generally compress down to 3 or 4 megabytes. |
Theodore Ts'o | 348e43d | 2001-05-03 14:43:43 +0000 | [diff] [blame] | 77 | .PP |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 78 | .SH RESTORING FILESYSTEM METADATA USING AN IMAGE FILE |
| 79 | .PP |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 80 | The |
| 81 | .B \-I |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 82 | option will cause e2image to install the metadata stored in the image |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 83 | file back to the device. It can be used to restore the filesystem metadata |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 84 | back to the device in emergency situations. |
| 85 | .PP |
| 86 | .B WARNING!!!! |
| 87 | The |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 88 | .B \-I |
Theodore Ts'o | b7c1d20 | 2005-06-20 08:26:50 -0400 | [diff] [blame] | 89 | option should only be used as a desperation measure when other |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 90 | alternatives have failed. If the filesystem has changed since the image |
| 91 | file was created, data |
| 92 | .B will |
| 93 | be lost. In general, you should make a full image |
| 94 | backup of the filesystem first, in case you wish to try other recovery |
| 95 | strategies afterwards. |
| 96 | .PP |
| 97 | .SH RAW IMAGE FILES |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 98 | The |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 99 | .B \-r |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 100 | option will create a raw image file instead of a normal image file. |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 101 | A raw image file differs |
| 102 | from a normal image file in two ways. First, the filesystem metadata is |
| 103 | placed in the proper position so that e2fsck, dumpe2fs, debugfs, |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 104 | etc.\& can be run directly on the raw image file. In order to minimize |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 105 | the amount of disk space consumed by a raw image file, the file is |
| 106 | created as a sparse file. (Beware of copying or |
| 107 | compressing/decompressing this file with utilities that don't understand |
| 108 | how to create sparse files; the file will become as large as the |
| 109 | filesystem itself!) Secondly, the raw image file also includes indirect |
| 110 | blocks and directory blocks, which the standard image file does not have, |
| 111 | although this may change in the future. |
| 112 | .PP |
Theodore Ts'o | b7c1d20 | 2005-06-20 08:26:50 -0400 | [diff] [blame] | 113 | Raw image files are sometimes used when sending filesystems to the maintainer |
| 114 | as part of bug reports to e2fsprogs. When used in this capacity, the |
| 115 | recommended command is as follows (replace hda1 with the appropriate device): |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 116 | .PP |
| 117 | .br |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 118 | \fBe2image \-r /dev/hda1 \- | bzip2 > hda1.e2i.bz2\fR |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 119 | .PP |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 120 | This will only send the metadata information, without any data blocks. |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 121 | However, the filenames in the directory blocks can still reveal |
| 122 | information about the contents of the filesystem that the bug reporter |
| 123 | may wish to keep confidential. To address this concern, the |
| 124 | .B \-s |
| 125 | option can be specified. This will cause |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 126 | .B e2image |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 127 | to scramble directory entries and zero out any unused portions |
Theodore Ts'o | b7c1d20 | 2005-06-20 08:26:50 -0400 | [diff] [blame] | 128 | of the directory blocks before writing the image file. However, |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 129 | the |
Theodore Ts'o | b7c1d20 | 2005-06-20 08:26:50 -0400 | [diff] [blame] | 130 | .B \-s |
| 131 | option will prevent analysis of problems related to hash-tree indexed |
| 132 | directories. |
Theodore Ts'o | d851ed3 | 2005-01-19 00:26:43 -0500 | [diff] [blame] | 133 | .PP |
Lukas Czerner | 92dcfb7 | 2011-05-18 14:20:47 +0200 | [diff] [blame] | 134 | Note that this will work even if you substitute "/dev/hda1" for another raw |
| 135 | disk image, or QCOW2 image previously created by |
| 136 | .BR e2image . |
| 137 | .PP |
Lukas Czerner | bf0449b | 2011-05-18 13:36:53 +0200 | [diff] [blame] | 138 | .SH QCOW2 IMAGE FILES |
| 139 | The |
| 140 | .B \-Q |
| 141 | option will create a QCOW2 image file instead of a normal, or raw image file. |
| 142 | A QCOW2 image contains all the information the raw image does, however unlike |
| 143 | the raw image it is not sparse. The QCOW2 image minimize the amount of disk |
| 144 | space by storing data in special format with pack data closely together, hence |
| 145 | avoiding holes while still minimizing size. |
| 146 | .PP |
| 147 | In order to send filesystem to the maintainer as a part of bug report to |
| 148 | e2fsprogs, use following commands (replace hda1 with the appropriate device): |
| 149 | .PP |
| 150 | .br |
| 151 | \ \fBe2image \-Q /dev/hda1 hda1.qcow2\fR |
| 152 | .br |
| 153 | \ \fBbzip2 -z hda1.qcow2\fR |
| 154 | .PP |
| 155 | This will only send the metadata information, without any data blocks. |
| 156 | However, the filenames in the directory blocks can still reveal |
| 157 | information about the contents of the filesystem that the bug reporter |
| 158 | may wish to keep confidential. To address this concern, the |
| 159 | .B \-s |
| 160 | option can be specified. This will cause |
| 161 | .B e2image |
| 162 | to scramble directory entries and zero out any unused portions |
| 163 | of the directory blocks before writing the image file. However, the |
| 164 | .B \-s |
| 165 | option will prevent analysis of problems related to hash-tree indexed |
| 166 | directories. |
| 167 | .PP |
| 168 | Note that QCOW2 image created by |
| 169 | .B e2image |
| 170 | is regular QCOW2 image and can be processed by tools aware of QCOW2 format |
| 171 | such as for example |
| 172 | .BR qemu-img . |
| 173 | .PP |
Theodore Ts'o | 348e43d | 2001-05-03 14:43:43 +0000 | [diff] [blame] | 174 | .SH AUTHOR |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 175 | .B e2image |
Theodore Ts'o | 348e43d | 2001-05-03 14:43:43 +0000 | [diff] [blame] | 176 | was written by Theodore Ts'o (tytso@mit.edu). |
| 177 | .SH AVAILABILITY |
| 178 | .B e2image |
Theodore Ts'o | 4780e87 | 2012-05-27 22:03:39 -0400 | [diff] [blame] | 179 | is part of the e2fsprogs package and is available from |
Theodore Ts'o | 348e43d | 2001-05-03 14:43:43 +0000 | [diff] [blame] | 180 | http://e2fsprogs.sourceforge.net. |
| 181 | .SH SEE ALSO |
| 182 | .BR dumpe2fs (8), |
| 183 | .BR debugfs (8) |
| 184 | |