Imported Upstream version 1.0
[packages/binwalk.git] / docs / README
index 8c61a0f..e3f2a3f 100644 (file)
@@ -4,105 +4,188 @@ DESCRIPTION
        it was designed for identifying files embedded inside of firmware images. Binwalk file signatures
        are compatible with the magic signatures used by the Unix file utility.
 
-       Binwalk includes a custom magic signature file, 'magic.binwalk'. This file contains improved 
-       signatures for files that are commonly found in firmware images such as compressed/archived files, 
-       Linux kernels, bootloaders, filesystems, etc. 
+       Binwalk includes customized/improved signatures for files that are commonly found in firmware images
+       such as compressed/archived files, firmware headers, Linux kernels, bootloaders, filesystems, etc. 
 
-       Since version 0.3.3 an additional option, -C, is included. Specifying this option displays the 
-       value of each file offset in various data types (long, short, date, etc), as defined in 'magic.bincast'.
-       This is useful for identifying header fields such as date and length values.
+       Binwalk can scan for executable code by searching for opcodes associated with the function prologues/epiloges 
+       of various architectures.
 
-       Since version 0.3.8 an additional option, -A, is included. This option scans the specified file(s) for
-       executable code by searching for opcodes associated with the function prologues/epiloges of various
-       architectures. These opcode signatures are defined in 'magic.binarch'.
+       Binwalk can display the value of each file offset in various data types (long, short, date, etc). This is 
+       useful for identifying unknown firmware header fields such as date and length values.
 
-USAGE
+       Binwalk can extract embedded files from firmware images and invoke external applications for further analysis,
+       decompression or extraction.
 
-       The only required options to Binwalk are the file(s) that you want to search:
+INSTALLATION
+
+       To install binwalk, run the following command from the src directory:
+
+               # python setup.py install
+
+DEPENDENCIES
+
+       Binwalk is currently supported on the Linux and Mac OSX platforms.
+
+       Binwalk depends on the libmagic library (version 5.05 or newer) and its corresponding magic Python module. Debian 
+       users can install these dependencies via apt-get:
+
+               $ sudo apt-get install libmagic1 python-magic
+
+       Note that some distributions/platforms may not have libmagic readily available, or may use an older version of 
+       libmagic that is incompatible with binwalk. In this case, you may download the source code for the file utility at:
+
+               ftp://ftp.astron.com/pub/file/
+
+       Follow the file utility's documentation to build and install both libmagic and the Python magic module.
+
+
+BASIC USAGE
+
+       The only required options to binwalk are the file(s) that you want to search:
 
                $ binwalk firmware1.bin firmware2.bin firmware3.bin
 
-       By default binwalk will include short signatures for gzip, lzma and jffs2 file fomats, and exclude 
-       invalid results. These default filters can be disabled with the -d option, which will speed up the 
-       scan time but may cause binwalk to miss gzip, lzma or jffs2 files:
+       Binwalk signatures and system-wide configuration files can be updated to the latest from the SVN
+       trunk with the --update option (this likely will need to be run as root):
+
+               # binwalk --update
+
+       To see more verbose information about the file being scanned, specify the --verbose option. This option
+       is automatically enabled if more than one target file is specified on the command line:
+
+               $ binwalk --verbose firmware.bin
+
+       Output can be logged to a file with the --file option:
+
+               $ binwalk --file=binwalk.log firmware.bin
+
+       Output to stdout can be suppressed with the --quiet option:
+
+               $ binwalk --file=binwalk.log --quiet firmware.bin
+
+       By default, scans start at the first byte of the specified file (offset 0) and end at the end of the
+       specified file. These settings can be controlled with the --offset and --length options, respectively.
+       For example, the following command will scan 128 bytes starting at offset 64:
+
+               $ binwalk --offset=64 --length=128 firmware.bin
+
+       By default, binwalk will scan every byte for possible signatures. To scan every 2 bytes, 4 bytes, 8 bytes,
+       etc, use the --align option:
+
+               $ binwalk --align=4 firmware.bin
+
+       By default binwalk will use the signatures from the magic.binwalk file, but you may specify an alternate
+       signature file with the --magic option:
+
+               $ binwalk --magic=/usr/share/misc/magic firmware.bin
+
+       To search for a sequence of bytes without creating a signature file, use the --raw-bytes option:
+
+               $ binwalk --raw-bytes="\x00\x01\x02\x03" firmware.bin
+
+
+TYPES OF SCANS
 
-               $ binwalk -d firmware.bin
+       By default binwalk will scan for file signatures inside the specified target file(s), however, other
+       types of scans are also supported.
 
-       If searching for specific files, the scan time can be significantly improved by specifying the -y
-       option. The -y option only searches for signatures that match the specified string(s):
+       To scan for known x86/MIPS/ARM/PPC opcodes, use the --opcodes option:
 
-               $ binwalk -y jffs2 firmware.bin
-               $ binwalk -y jffs2 -y cramfs firmware.bin
+               $ binwalk --opcodes firmware.bin
 
-       By default binwalk will use the signatures from the binwalk.magic file, but you may specify any other
-       libmagic-compatible signature file with the -m option. Note that for full maigc file compatibility,
-       you must specify the -s option to disable 'smart' matching:
+       To cast each offset in the file as various data types (big/little endian shorts/longs, date fields, etc),
+       use the --cast option (best used with the --length / --offset options):
 
-               $ binwalk -m /usr/share/misc/magic -s firmware.bin
+               $ binwalk --cast --length=64 firmware.bin
 
-       By default binwalk will check for valid file signatures anywhere in the target file. This means that
-       scanning a 4MB file is the equivalent of running the Unix file utility 4 million times. To
-       decrease scan time, you may specify the byte alignment via the -b option. If, for example,
-       you specify a byte alignment of 16, then binwalk will assume that everything in the file is
-       16-byte aligned and will only look for signatures every 16 bytes:
 
-               $ binwalk -b 16 firmware.bin
+CONTROLLING SCAN BEHAVIOR
 
-       You may also specify at what offset into the firmware image to start searching, and how many
-       bytes should be searched. The following command searches 1000 bytes of data starting at an offset
-       of 100:
-               
-               $ binwalk -o 100 -l 1000 firmware.bin
+       Some signatures - notably those whose magic signatures are less than 3 bytes - are excluded by default
+       from binwalk scans. These can be individually included with the --include option, or globally with --all
+       (multiple --include options may be specified):
 
-       All integer arguments, such as -o, and -l, can be entered as decimal (ex: 16) or hexadecimal
-       (ex: 0x10, \x10, 10H, 10h) values.
+               $ binwalk --include=minix firmware.bin
+               $ binwalk --all firmware.bin
 
-       By default, all magic signatures that are only two bytes long are ignored as they have a high
-       rate of false positive matches. To include these magic signatures, specify the -a option:
+       By default results marked as invalid are not displayed. They can be displayed by specifying the --show-invalid
+       option:
 
-               $ binwalk -a firmware.bin
+               $ binwalk --show-invalid firmware.bin
 
-       By default, binwalk will apply several default filters in order to improve scan reliability.
-       These filters can be explicitly disabled with the -d option:
+       By default binwalk will stop scanning for signatures at any given offset once a valid signature has been
+       found at that offset. To display all signatures that match at all offsets, use the --keep-going option:
 
-               $ binwalk -d firmware.bin
+               $ binwalk --keep-going firmware.bin
 
-       You can also include individual signatures from the default exclude list with the -i option:
 
-               $ binwalk -i gzip firmware.bin
+FILTERING SCAN RESULTS
+
+       It may at times be desirable to exclude certian signatures from the scan results. This can be done with the
+       --exclude option (multiple --exclude options may be specified):
+
+               $ binwalk --exclude='lzma compressed data' firmware.bin
+
+       It may at times be desirable to only search for a certian signature or group of signatures. This can be 
+       done with the --search option (multiple --search options may be specified):
        
-       Include and exclude filters may also be specified in order to limit the search results. Multiple
-       include / exclude filters may be specified, and are case insensitive. If an include filter is specified,
-       only descriptions that match that filter will be displayed. If an exclude filter is specified, all
-       results will be displayed except those that match the exclude filter. If both exclude and include
-       filters are specified, exclude filters trump include filters.
+               $ binwalk --search=filesystem firmware.bin
 
-       Only search for gzip results:
+       The --grep option is useful for filtering output that contains multiple results per line, such as occurs 
+       with the --cast option:
 
-               $ binwalk -y gzip firmware.bin
+               $ binwalk --cast --grep=2012 firmware.bin
 
-       Search for everything except results that contain the string 'system':
+EXTRACTING FILES
 
-               $ binwalk -x system firmware.bin
+       Binwalk can extract matches found inside the target file(s), and optionally execute an external command
+       each time a file is extracted using the --dd option. At a minimum, a string to search for in the output
+       description and a file extension must be specified. A command to execute may also be specified. These 
+       three fields are colon delimited.
 
-       Search only for results that are file systems, but that are not JFFS2 file systems:
+       To extract all matches that contain the text 'gzip compressed data' and save them with a file extension
+       of 'gz':
 
-               $ binwalk -y filesystem -x jffs2 firmware.bin
+               $ binwalk --dd='gzip compressed data:gz' firmware.bin
+       
+       To extract all matches that contain the text 'gzip compressed data', save them with a file extension of
+       'gz' and execute the 'gunzip' command against the extracted file (note the use of the %e place holder for
+       the path to the extracted file):
 
-       To update to the latest magic file definitions, use the -u option:
+               $ binwalk --dd='gzip compressed data:gz:gunzip %e' firmware.bin
+       
+       There are some file types that are commonly extracted, and specifying a --dd option for each one is tiresome.
+       The -e option will load extract rules from the system/user extract.conf file (see the CONFIGURATION FILES section
+       below):
 
-               # binwalk -u
+               $ binwalk -e firmware.bin
+       
+       To specify a different extraction rule file, use --extract:
 
-       Some scans can take some time to complete and may not display many results during this time. 
-       You can press the enter key at any time to force binwalk to display its current scan progress:
+               $ binwalk --extract=./my_extract.conf firmware.bin
+       
+       Extracting files with --dd or --extract can leave a lot of uneccessary files laying around. These can be 
+       automatically cleaned up with the --rm option. If specified, any extracted file that had a command run against
+       it will be deleted after the command has finished execution. Additionally, if files created by the executed
+       command are 0 bytes in size, they will also be removed:
 
-               $ binwalk -v firmware.bin
+               $ binwalk --rm firmware.bin
 
-               Scan Time:    Dec 09, 2011 @ 18:00:42
-               Magic File:   /usr/local/etc/binwalk/magic.binwalk
-               Signatures:   76
-               Target File:  firmware.bin
-               MD5 Checksum: 1c802dbacdcfc0b96b900f8680d9d196
+       Some file types do not specify their file size in their header, but rather rely on a footer or delimiter to
+       signify the end of the file. When extracted these files will by default be copied from the start of the header
+       to the end of the target file. If there are many of these files, this can take up unecessary disk space. For
+       those files which are supported, specifying the --delay option will delay the extraction of these files until
+       the end of the file can be found:
+
+               $ binwalk --delay firmware.bin
+
+       
+DISPLAYING SCAN PROGRESS
+
+       Some scans can take some time to complete and may not display many results during this time. You can press the 
+       enter key at any time to force binwalk to display its current scan progress:
+
+               $ binwalk -v firmware.bin
 
                DECIMAL         HEX             DESCRIPTION
                ------------------------------------------------------------------------------------------
@@ -114,52 +197,47 @@ USAGE
                Progress:  12424 / 12074736  (0.10%)
 
 
-       
+SIGNATURE FILES
 
-INSTALLATION
+       There are three signature files used by binwalk:
 
-       To build and install binwalk, run:
+               o magic/binwalk - The default signature file.
+               o magic/binarch - The signature file used with --opcodes.
+               o magic/bincast - The signature file used with --cast.
 
-               $ ./configure   
-               $ make
-               # make install
+       Users may create their own signatures that will be added to the respective system-wide files when performing a scan.
+       This is as easy as editing the following files in the user home directory:
 
-DEPENDENCIES
+               o .binwalk/magic/binwalk
+               o .binwalk/magic/binarch
+               o .binwalk/magic/bincast
 
-       Binwalk is currently supported on the Linux and Mac OSX platforms. 
-       
-       To build from source, you must have the libmagic, zlib and libcurl libraries. 
-       Debian users can install zlib and libcurl via apt-get:
+       Although the system-wide signature files can also be altered, the system-wide signature files will be overwritten when
+       upgrading binwalk, or using the --update option. The user files will not be touched however, and will survive these updates.
 
-               $ sudo apt-get install libmagic-dev zlib1g-dev libcurl4-openssl-dev
-       
-       Note that some distributions/platforms may not have libmagic readily available,
-       or may use a version of libmagic that is incompatible with binwalk. In this
-       case, you may download the source code for the Unix file utility at: 
-       
-               ftp://ftp.astron.com/pub/file/
 
-       Building and installing the file utility will also install libmagic.
-       
-FILES
-
-       docs/README             Project README file
-       docs/COPYING            Project license file
-        src/binwalk.c          Main binwalk source code file
-        src/binwalk.h          Main binwalk source header file
-       src/common.c            Common functions used by binwalk
-       src/common.h            Common function declarations and definitions
-       src/dd.c                Code for dumping sections of the target file to disk
-       src/dd.h                DD code functions header file.
-       src/filter.c            Result filtering functions
-       src/filter.h            Filter functions header file
-       src/magic.binarch       Custom magic signature file for opcode scans
-        src/magic.bincast      Custom magic signature file for casting data types
-        src/magic.binwalk      Custom magic signature file for binwalk
-       src/md5.c               MD5 algorithm code by Peter Deutsch
-       src/md5.h               MD5 algorithm header by Peter Deutsch
-       src/mparse.c            Minimal magic file parsing library
-       src/mparse.h            Parsing library header file
-       src/update.c            Magic file update routines
-       src/update.h            Updates header file
+CONFIGURATION FILES
+
+       There is one configuration file used by binwalk only when the --extract option is specified:
+
+               o config/extract.conf
+
+       This file contains a list of extract rules, identical to the arguments that would be passed to the --dd option.
+
+       Users can override and add to this list of extract rules by adding their own rules to the following file in the user home
+       directory:
+
+               o .binwalk/config/extract.conf
+
+       Note that when overriding a system-wide extract rule, the 'type' field in the user extract rule must exactly match the 'type'
+       field in the system-wide extract rule.
+
+       Although the system-wide extract.conf file can also be altered, this file will be overwritten when upgrading binwalk or using
+       the --update option. The user extract.conf file will not be touched however, and will survive these updates.
+
+MORE INFORMATION
+
+       For more detailed and up to date information, visit the binwalk wiki page at:
+
+               http://code.google.com/p/binwalk/wiki/TableOfContents