.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "MAGICRESCUE 1" .TH MAGICRESCUE 1 "2018-10-16" "1.1.10" "Magic Rescue" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" magicrescue \- Scans a block device and extracts known file types by looking at magic bytes. .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBmagicrescue\fR [ \fIoptions\fR ] \fIdevices\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" Magic Rescue opens \fIdevices\fR for reading, scans them for file types it knows how to recover and calls an external program to extract them. It looks at \&\*(L"magic bytes\*(R" in file contents, so it can be used both as an undelete utility and for recovering a corrupted drive or partition. It works on any file system, but on very fragmented file systems it can only recover the first chunk of each file. These chunks are sometimes as big as 50MB, however. .PP To invoke \fBmagicrescue\fR, you must specify at least one device and the \fB\-d\fR and \fB\-r\fR options. See the \*(L"\s-1USAGE\*(R"\s0 section in this manual for getting started. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-b\fR \fIblocksize\fR" 7 .IX Item "-b blocksize" Default: 1. This will direct \fBmagicrescue\fR to only consider files that start at a multiple of the \fIblocksize\fR argument. The option applies only to the recipes following it, so by specifying it multiple times it can be used to get different behavior for different recipes. .Sp Using this option you can usually get better performance, but fewer files will be found. In particular, files with leading garbage (e.g. many mp3 files) and files contained inside other files are likely to be skipped. Also, some file systems don't align small files to block boundaries, so those won't be found this way either. .Sp If you don't know your file system's block size, just use the value 512, which is almost always the hardware sector size. .IP "\fB\-d\fR \fIdirectory\fR" 7 .IX Item "-d directory" Mandatory. Output directory for found files. Make sure you have plenty of free space in this directory, especially when extracting very common file types such as jpeg or gzip files. Also make sure the file system is able to handle thousands of files in a single directory, i.e. don't use \s-1FAT\s0 if you are extracting many files. .Sp You should not place the output directory on the same block device you are trying to rescue files from. This might add the same file to the block device ahead of the current reading position, causing \fBmagicrescue\fR to find the same file again later. In the worst theoretical case, this could cause a loop where the same file is extracted thousands of times until disk space is exhausted. You are also likely to overwrite the deleted files you were looking for in the first place. .IP "\fB\-r\fR \fIrecipe\fR" 7 .IX Item "-r recipe" Mandatory. Recipe name, file, or directory. Specify this as either a plain name (e.g. \f(CW\*(C`jpeg\-jfif\*(C'\fR) or a path (e.g. \fIrecipes/jpeg\-jfif\fR). If it doesn't find such a file in the current directory, it will look in \fI./recipes\fR and \&\fI/usr/share/magicrescue/recipes\fR. .Sp If \fIrecipe\fR is a directory, all files in that directory will be treated as recipes. .Sp Browse the \fI/usr/share/magicrescue/recipes\fR directory to see what recipes are available. A recipe is a text file, and you should read the comments inside it before using it. Either use the recipe as it is or copy it somewhere and modify it. .Sp For information on creating your own recipes, see the \*(L"\s-1RECIPES\*(R"\s0 section. .IP "\fB\-I\fR \fIfile\fR" 7 .IX Item "-I file" Reads input files from \fIfile\fR in addition to those listed on the command line. If \fIfile\fR is \f(CW\*(C`\-\*(C'\fR, read from standard input. Each line will be interpreted as a file name. .IP "\fB\-M\fR \fIoutput_mode\fR" 7 .IX Item "-M output_mode" Produce machine-readable output to stdout. \fIoutput_mode\fR can be: .RS 7 .IP "\fBi\fR" 4 .IX Item "i" Print each input file name before processing .IP "\fBo\fR" 4 .IX Item "o" Print each output file name after processing .IP "\fBio\fR" 4 .IX Item "io" Print both input and output file names. Input file names will be prefixed by \&\f(CW\*(C`i\*(C'\fR and a space. Output file names will be prefixed by \f(CW\*(C`o\*(C'\fR and a space. .RE .RS 7 .Sp Nothing else will be written to standard output in this mode. .RE .IP "\fB\-O\fR [\fB+\fR|\fB\-\fR|\fB=\fR][\fB0x\fR]\fIoffset\fR" 7 .IX Item "-O [+|-|=][0x]offset" Resume from the specified \fIoffset\fR in the first device. If prefixed with \&\fB0x\fR it will be interpreted as a hex number. .Sp The number may be prefixed with a sign: .RS 7 .IP "\fB=\fR" 4 .IX Item "=" Seek to an absolute position (default) .IP "\fB+\fR" 4 .IX Item "+" Seek to a relative position. On regular files this does the same as the above. .IP "\fB\-\fR" 4 .IX Item "-" Seek to \s-1EOF,\s0 minus the offset. .RE .RS 7 .RE .SH "USAGE" .IX Header "USAGE" Say you have destroyed the file system on /dev/hdb1 and you want to extract all the jpeg files you lost. This guide assumes you have installed Magic Rescue in \fI/usr/local\fR, which is the default. .PP Make sure \s-1DMA\s0 and other optimizations are enabled on your disk, or it will take hours. In Linux, use hdparm to set these options: .PP .Vb 1 \& $ hdparm \-d 1 \-c 1 \-u 1 /dev/hdb .Ve .PP Choose your output directory, somewhere with lots of disk space. .PP .Vb 1 \& $ mkdir ~/output .Ve .PP Look in the \fI/usr/local/share/magicrescue/recipes\fR directory for the recipes you want. Magic Rescue comes with recipes for some common file types, and you can make your own too (see the next section). Open the recipes you want to use in a text editor and read their comments. Most recipes require 3rd party software to work, and you may want to modify some parameters (such as \&\fBmin_output_file\fR) to suit your needs. .PP Then invoke \fBmagicrescue\fR .PP .Vb 1 \& $ magicrescue \-r jpeg\-jfif \-r jpeg\-exif \-d ~/output /dev/hdb1 .Ve .PP It will scan through your entire hard disk, so it may take a while. You can stop it and resume later of you want to. To do so, interrupt it (with \s-1CTRL+C\s0) and note the progress information saying what address it got to. Then restart it later with the \fB\-O\fR option. .PP When it has finished you will probably find thousands of .jpg files in \&\fI~/output\fR, including things you never knew was in your browser cache. Sorting through all those files can be a huge task, so you may want to use software or scripts to do it. .PP First, try to eliminate duplicates with the \fBdupemap\fR(1) tool included in this package. .PP .Vb 1 \& $ dupemap delete,report ~/output .Ve .PP If you are performing an undelete operation you will want to get rid of all the rescued files that also appear on the live file system. See the \&\fBdupemap\fR(1) manual for instructions on doing this. .PP If that's not enough, you can use use \fBmagicsort\fR(1) to get a better overview: .PP .Vb 1 \& $ magicsort ~/output .Ve .SH "RECIPES" .IX Header "RECIPES" .SS "Creating recipe files" .IX Subsection "Creating recipe files" A recipe file is a relatively simple file of 3\-5 lines of text. It describes how to recognise the beginning of the file and what to do when a file is recognised. For example, all jfif images start with the bytes \f(CW\*(C`0xff 0xd8\*(C'\fR. At the 6th byte will be the string \f(CW\*(C`JFIF\*(C'\fR. Look at \fIrecipes/jpeg\-jfif\fR in the source distribution to follow this example. .PP Matching magic data is done with a \*(L"match operation\*(R" that looks like this: .PP \&\fIoffset\fR \fIoperation\fR \fIparameter\fR .PP where \fIoffset\fR is a decimal integer saying how many bytes from the beginning of the file this data is located, \fIoperation\fR refers to a built-in match operation in \fBmagicrescue\fR, and \fIparameter\fR is specific to that operation. .IP "\(bu" 4 The \fBstring\fR operation matches a string of any length. In the jfif example this is four bytes. You can use escape characters, like \f(CW\*(C`\en\*(C'\fR or \f(CW\*(C`\exA7\*(C'\fR. .IP "\(bu" 4 The \fBint32\fR operation matches 4 bytes ANDed with a bit mask. To match all four bytes, use the bit mask \f(CW\*(C`FFFFFFFF\*(C'\fR. If you have no idea what a bit mask is, just use the \fBstring\fR operation instead. The mask \f(CW\*(C`FFFF0000\*(C'\fR in the jfif example matches the first two bytes. .IP "\(bu" 4 The \fBchar\fR operation is like \*(L"string\*(R", except it only matches a single character. .PP To learn these patterns for a given file type, look at files of the desired type in a hex editor, search through the resource files for the \fBfile\fR(1) utility () and/or search the Internet for a reference on the format. .PP If all the operations match, we have found the start of the file. Finding the end of the file is a much harder problem, and therefore it is delegated to an external shell command, which is named by the \fBcommand\fR directive. This command receives the block device's file descriptor on stdin and must write to the file given to it in the \f(CW$1\fR variable. Apart from that, the command can do anything it wants to try and extract the file. .PP For some file types (such as jpeg), a tool already exists that can do this. However, many programs misbehave when told to read from the middle of a huge block device. Some seek to byte 0 before reading (can be fixed by prefixing cat|, but some refuse to work on a file they can't seek in). Others try to read the whole file into memory before doing anything, which will of course fail on a muti-gigabyte block device. And some fail completely to parse a partially corrupted file. .PP This means that you may have to write your own tool or wrap an existing program in some scripts that make it behave better. For example, this could be to extract the first 10MB into a temporary file and let the program work on that. Or perhaps you can use \fItools/safecat\fR if the file may be very large. .SS "Recipe format reference" .IX Subsection "Recipe format reference" Empty lines and lines starting with \f(CW\*(C`#\*(C'\fR will be skipped. A recipe contains a series of match operations to find the content and a series of directives to specify what to do with it. .PP Lines of the format \fIoffset\fR \fIoperation\fR \fIparameter\fR will add a match operation to the list. Match operations will be tried in the order they appear in the recipe, and they must all match for the recipe to succeed. The \&\fIoffset\fR describes what offset this data will be found at, counting from the beginning of the file. \fIoperation\fR can have the following values: .IP "\fBstring\fR \fIstring\fR" 7 .IX Item "string string" The parameter is a character sequence that may contain escape sequences such as \exFF. .IP "\fBchar\fR \fIcharacter\fR" 7 .IX Item "char character" The parameter is a single character (byte), or an escape sequence. .IP "\fBint32\fR \fIvalue\fR \fIbitmask\fR" 7 .IX Item "int32 value bitmask" Both \fIvalue\fR and \fIbitmask\fR are expressed as 8\-character hex strings. \&\fIbitmask\fR will be ANDed with the data, and the result will be compared to \fIvalue\fR. The byte order is as you see it in the hex editor, i.e. big-endian. .PP The first match operation in a recipe is special, it will be used to scan through the file. Only the \fBchar\fR and \fBstring\fR operations can be used there. To add more operation types, look at the instructions in \fImagicrescue.c\fR. .PP A line that doesn't start with an integer is a directive. This can be: .IP "\fBextension\fR \fIext\fR" 7 .IX Item "extension ext" Mandatory. \fIext\fR names the file extension for this type, such as \f(CW\*(C`jpg\*(C'\fR. .IP "\fBcommand\fR \fIcommand\fR" 7 .IX Item "command command" Mandatory. When all the match operations succeed, this \fIcommand\fR will be executed to extract the file from the block device. \fIcommand\fR is passed to the shell with the block device's file descriptor (seeked to the right byte) on stdin. The shell variable \f(CW$1\fR will contain the file its output should be written to, and it must respect this. Otherwise \fBmagicrescue\fR cannot tell whether it succeeded. .IP "\fBrename\fR \fIcommand\fR" 7 .IX Item "rename command" Optional. After a successful extraction this command will be run. Its purpose is to gather enough information about the file to rename it to something more meaningful. The script must not perform the rename command itself, but it should write to standard output the string \f(CW\*(C`RENAME\*(C'\fR, followed by a space, followed by the new file name. Nothing else must be written to standard output. If the file should not be renamed, nothing should be written to standard output. Standard input and \f(CW$1\fR will work like with the \fBcommand\fR directive. .IP "\fBmin_output_file\fR \fIsize\fR" 7 .IX Item "min_output_file size" Default: 100. Output files less than this size will be deleted. .IP "\fBallow_overlap\fR \fIbytes\fR" 7 .IX Item "allow_overlap bytes" By default, recipes will not match on overlapping byte ranges. \&\fBallow_overlap\fR disables this, and it should always be used for recipes where the extracted file may be larger than it was on disk. If \fIbytes\fR is negative, overlap checking will be completely disabled. Otherwise, overlap checking will be in effect for everything but the last \fIbytes\fR of the output. For example, if the output may be up to 512 bytes bigger than the input, \fBallow_overlap\fR should be set to 512. .PP To test whether your recipe actually works, either just run it on your hard disk or use the \fItools/checkrecipe\fR script to pick out files that should match but don't. .PP If you have created a recipe that works, please mail it to me at jbj@knef.dk so I can include it in the distribution. .SH "WHEN TO NOT USE MAGIC RESCUE" .IX Header "WHEN TO NOT USE MAGIC RESCUE" Magic Rescue is not meant to be a universal application for file recovery. It will give good results when you are extracting known file types from an unusable file system, but for many other cases there are better tools available. .IP "\(bu" 4 If there are intact partitions present somewhere, use \fBgpart\fR to find them. .IP "\(bu" 4 If file system's internal data structures are more or less undamaged, use \&\fBThe Sleuth Kit\fR. At the time of writing, it only supports \s-1NTFS, FAT,\s0 ext[23] and \s-1FFS,\s0 though. .IP "\(bu" 4 If Magic Rescue does not have a recipe for the file type you are trying to recover, try \fBforemost\fR instead. It recognizes more file types, but in most cases it extracts them simply by copying out a fixed number of bytes after it has found the start of the file. This makes postprocessing the output files more difficult. .PP In many cases you will want to use Magic Rescue in addition to the tools mentioned above. They are not mutually exclusive, e.g. combining \&\fBmagicrescue\fR with \fBdls\fR from The Sleuth Kit could give good results. In many cases you'll want to use \fBmagicrescue\fR to extract its known file types and another utility to extract the rest. .PP When combining the results of more than one tool, \fBdupemap\fR(1) can be used to eliminate duplicates. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "Similar programs" 4 .IX Item "Similar programs" .RS 4 .PD 0 .IP "\fBgpart\fR(8)" 4 .IX Item "gpart(8)" .PD . Tries to rebuild the partition table by scanning the disk for lost partitions. .IP "\fBforemost\fR(1)" 4 .IX Item "foremost(1)" . Does the same thing as \fBmagicrescue\fR, except that its \*(L"recipes\*(R" are less complex. Finding the end of the file must happen by either matching an \s-1EOF\s0 string or just extracting a fixed number of bytes every time. It supports more file types than Magic Rescue, but extracted files usually have lots of trailing garbage, so removal of duplicates and sorting by size is not possible. .IP "\fBThe Sleuth Kit\fR" 4 .IX Item "The Sleuth Kit" . This popular package of utilities is extremely useful for undeleting files from a FAT/NTFS/ext2/ext3/FFS file system that's not completely corrupted. Most of the utilities are not very useful if the file system has been corrupted or overwritten. It is based on The Coroner's Toolkit (). .IP "\s-1JPEG\s0 recovery tools" 4 .IX Item "JPEG recovery tools" This seems to be the file type most people are trying to recover. Available utilities include , , and . .RE .RS 4 .RE .IP "Getting disk images from failed disks" 4 .IX Item "Getting disk images from failed disks" \&\fBdd\fR(1), \fBrescuept\fR(1), , , , .IP "Processing \fBmagicrescue\fR's output" 4 .IX Item "Processing magicrescue's output" \&\fBdupemap\fR(1), \fBfile\fR(1), \fBmagicsort\fR(1), .IP "Authoring recipes" 4 .IX Item "Authoring recipes" \&\fBmagic\fR(4), \fBhexedit\fR(1), .IP "Filesystem-specific undelete utilities" 4 .IX Item "Filesystem-specific undelete utilities" There are too many to count them, especially for ext2 and \s-1FAT.\s0 Find them on Google and Freshmeat. .SH "AUTHOR" .IX Header "AUTHOR" Jonas Jensen .SH "LATEST VERSION" .IX Header "LATEST VERSION" You can find the latest version at