SalvageNTFS (CVS) USAGE

Contents
========

1. ntfsdump
2. ntfsrecover
3. ntfsls
4. ntfsdumpdata
5. ntfsdumpclusters

1. ntfsdump
===========

Usage: `ntfsdump <volume> [<offset> [<length>]]`

`ntfsdump` scans a volume for "FILE records" (entries in the Master File Table)
and dumps them to the standard output, displaying the FILE record as it is
found on-disk. Its output takes the following form:

$ ntfsls /dev/sda2
SalvageNTFS Dump
Written by Will Glynn

... (ten thousand entries)
File {
  Record: 0x302AE1
  Record size: 344 / 1024
  Sequence number: 6
  Attributes:
    $STANDARD_INFORMATION (0x10): normal file
    $FILE_NAME (0x30): "cdex_150.exe", parent ref 0x291E#1
    $DATA (0x80): length = 0x1E84A6 [non-resident: 489 clusters at 0x08307B]
}
... (hundreds of thousands of entries)

When run against an entire volume, `ntfsdump` will output every FILE record it
finds. This is useful when sent to a log file, as it can then be searched
(using standard utilities like `less` or `grep`) to locate record numbers for
items that one wishes to recover.

2. ntfsrecover
==============

Usage: `ntfsrecover <volume> <record>`

Given a record number, `ntfsrecover` will read the FILE record at that
location, attempt to de-reference any $ATTRIBUTE_LIST attributes, and output
the requested file or directory to a corresponding location inside the current
working directory. Examples:

  - When run against a normal file named "abc.txt", `ntfsrecover` will create
    "abc.txt" in the current working directory.
  - When run against a directory named "My Documents", `ntfsrecover` will
    create "My Documents" in the current working directory and will recursively
    recover all files and directories it contains.

Additionally, `ntfsrecover` preserves file modificaton times. In the case of
failure, `ntfsrecover` outputs the FILE record it was processing and
terminates.

3. ntfsls
=========

Usage: `ntfsls <volume> <record>`

Given a record number, `ntfsls` will read the FILE record at that location,
attempt to de-reference any $ATTRIBUTE_LIST attributes, and output the contents
of a directory entry to the standard output. Its output takes the form:

$ ntfsls /dev/sda2 0x300ACE
SalvageNTFS Data Dump
Written by Will Glynn

Directory {
	0x185D#1: "Administrator", parent ref 0x0ACE#1
	0x0AD0#1: "All Users", parent ref 0x0ACE#1
	0x0ACF#1: "Default User", parent ref 0x0ACE#1
}

The numbers in the left column are "reference numbers" and correspond to the
location of a FILE record within the Master File Table. At this time, it is
necessary to manually locate the starting position of the Master File Table and
adjust these numbers accordingly for later operations.

Directories have a useful property, however: the indexed files (those "inside"
the directory) store a reference to the parent record. In this case, `ntfsls`
retrieved the contents of record 0x300ACE, which contains files that say their
parent's reference is 0x0ACE. (The number after the pound sign is the sequence
number, which can be ignored at this point.) Therefore, the Master File Table
begins at record 0x300ACE minus 0x0ACE, or 0x300000. Therefore, "Administrator"
can be found at record 0x300000 plus 0x185D, or 0x30185D.

4. ntfsdumpdata
===============

Usage: `ntfsdumpdata <volume> <record> [<output file>]`

Given a record number, `ntfsdumpdata` will output a FILE record's $DATA
attribute to the specified output file, or a derived filename if none is given.
(The automatic name currently takes the form "<record>-<filename>".)

5. ntfsdumpclusters
===================

Usage: `ntfsdumpclusters <volume> <cluster> <length> <output file>`

This is a debugging tool, more than anything. (In fact, `dd` could also be used
to perform its functions.) Given a volume, the location and length of requested
data, and a filename, `ntfsdumpclusters` will write the requested clusters to
the output file. Specific information may be requested by SalvageNTFS project
members for analysis (in support requests or bug reports), and
`ntfsdumpclusters` is a starting point for that.

