ntfsprogs/ntfsclone.8.in

.\" Copyright (c) 2003\-2005 Richard Russon.
.\" Copyright (c) 2003\-2006 Szabolcs Szakacsits.
.\" Copyright (c) 2004 Per Olofsson.
.\" Copyright (c) 2010\-2013 Jean-Pierre Andre.
.\" This file may be copied under the terms of the GNU Public License.
.\"
.TH NTFSCLONE 8 "February 2013" "ntfs-3g @VERSION@"
.SH NAME
ntfsclone \- Efficiently clone, image, restore or rescue an NTFS
.SH SYNOPSIS
.B ntfsclone
[\fIOPTIONS\fR]
.I SOURCE
.br
.B ntfsclone \-\-save\-image
[\fIOPTIONS\fR]
.I SOURCE
.br
.B ntfsclone \-\-restore\-image
[\fIOPTIONS\fR]
.I SOURCE
.br
.B ntfsclone \-\-metadata
[\fIOPTIONS\fR]
.I SOURCE
.SH DESCRIPTION
.B ntfsclone
will efficiently clone (copy, save, backup, restore) or rescue an NTFS
filesystem to a sparse file, image, device (partition) or standard output.
It works at disk sector level and
copies only the used data. Unused disk space becomes zero (cloning to
sparse file), encoded with control codes (saving in special image format),
left unchanged (cloning to a disk/partition) or
filled with zeros (cloning to standard output).

.B ntfsclone
can be useful to make backups, an exact snapshot of an NTFS filesystem
and restore it later on, or for developers to test NTFS read/write
functionality, troubleshoot/investigate users' issues using the clone
without the risk of destroying the original filesystem.

The clone, if not using the special image format, is an exact copy of the
original NTFS filesystem from sector to sector thus it can be also mounted
just like the original NTFS filesystem.
For example if you clone to a file and the kernel has loopback device and
NTFS support then the file can be mounted as
.RS
.sp
.B   mount \-t ntfs \-o loop ntfsclone.img /mnt/ntfsclone
.sp
.RE
.SS Windows Cloning
If you want to copy, move or restore a system or boot partition to another 
computer, or to a different disk or partition (e.g. hda1\->hda2, hda1\->hdb1
or to a different disk sector offset) then you will need to take extra care.

Usually, Windows will not be able to boot, unless you copy, move or restore 
NTFS to the same partition which starts at the same sector on the same type 
of disk having the same BIOS legacy cylinder setting as the original 
partition and disk had.

The ntfsclone utility guarantees to make an exact copy of NTFS but it 
won't deal with booting issues. This is by design: ntfsclone is a 
filesystem, not system utility. Its aim is only NTFS cloning, not Windows 
cloning. Hereby ntfsclone can be used as a very fast and reliable 
build block for Windows cloning but itself it's not enough.
.SS Sparse Files
A file is sparse if it has unallocated blocks (holes). The reported size of
such files are always higher than the disk space consumed by them.  The
.BR du
command can tell the real disk space used by a sparse file.
The holes are always read as zeros. All major Linux filesystem like,
ext2, ext3, reiserfs, Reiser4, JFS and XFS, supports
sparse files but for example the ISO 9600 CD\-ROM filesystem doesn't.
.SS Handling Large Sparse Files
As of today Linux provides inadequate support for managing (tar,
cp, gzip, gunzip, bzip2, bunzip2, cat, etc) large sparse files.
The only main Linux filesystem
having support for efficient sparse file handling is XFS by the
XFS_IOC_GETBMAPX
.BR ioctl (2) .
However none of the common utilities supports it.
This means when you tar, cp, gzip, bzip2, etc a large sparse file
they will always read the entire file, even if you use the "sparse support"
options.

.BR bzip2 (1)
compresses large sparse files much better than
.BR gzip (1)
but it does so
also much slower. Moreover neither of them handles large sparse
files efficiently during uncompression from disk space usage point
of view.

At present the most efficient way, both speed and space\-wise, to
compress and uncompress large sparse files by common tools
would be using
.BR tar (1)
with the options
.B \-S
(handle sparse files "efficiently") and
.B \-j
(filter the archive through bzip2). Although
.BR tar
still reads and analyses the entire file, it doesn't pass on the
large data blocks having only zeros to filters and it also avoids
writing large amount of zeros to the disk needlessly. But since
.BR tar
can't create an archive from the standard input, you can't do this
in\-place by just reading
.BR ntfsclone
standard output. Even more sadly, using the \-S option results 
serious data loss since the end of 2004 and the GNU
.BR tar
maintainers didn't release fixed versions until the present day.
.SS The Special Image Format
It's also possible, actually it's recommended, to save an NTFS filesystem
to a special image format.
Instead of representing unallocated blocks as holes, they are
encoded using control codes. Thus, the image saves space without
requiring sparse file support. The image format is ideal for streaming
filesystem images over the network and similar, and can be used as a
replacement for Ghost or Partition Image if it is combined with other
tools. The downside is that you can't mount the image directly, you
need to restore it first.

To save an image using the special image format, use the
.B \-s
or the
.B \-\-save\-image
option. To restore an image, use the
.B \-r
or the
.B \-\-restore\-image
option. Note that you can restore images from standard input by
using '\-' as the
.I SOURCE
file.
.SS Metadata\-only Cloning
One of the features of
.BR ntfsclone
is that, it can also save only the NTFS metadata using the option
.B \-m
or
.B \-\-metadata
and the clone still will be
mountable. In this case all non\-metadata file content will be lost and
reading them back will result always zeros.

The metadata\-only image can be compressed very
well, usually to not more than 1\-8 MB thus it's easy to transfer
for investigation, troubleshooting.

In this mode of ntfsclone,
.B NONE
of the user's data is saved, including the resident user's data
embedded into metadata. All is filled with zeros.
Moreover all the file timestamps, deleted and unused spaces inside
the metadata are filled with zeros. Thus this mode is inappropriate
for example for forensic analyses.
This mode may be combined with \fB\-\-save\-image\fP to create a
special image format file instead of a sparse file.

Please note, filenames are not wiped out. They might contain
sensitive information, so think twice before sending such an
image to anybody.
.SH OPTIONS
Below is a summary of all the options that
.B ntfsclone
accepts.  Nearly all options have two equivalent names.  The short name is
preceded by
.B \-
and the long name is preceded by
.B \-\- .
Any single letter options, that don't take an argument, can be combined into a
single command, e.g.
.B \-fv
is equivalent to
.B "\-f \-v" .
Long named options can be abbreviated to any unique prefix of their name.
.TP
\fB\-o\fR, \fB\-\-output\fR FILE
Clone NTFS to the non\-existent
.IR FILE .
If
.I FILE
is '\-' then clone to the
standard output.
.TP
\fB\-O\fR, \fB\-\-overwrite\fR FILE
Clone NTFS to
.IR FILE ,
overwriting if exists.
.TP
\fB\-s\fR, \fB\-\-save\-image\fR
Save to the special image format. This is the most efficient way space and
speed\-wise if imaging is done to the standard output, e.g. for image
compression, encryption or streaming through a network.
.TP
\fB\-r\fR, \fB\-\-restore\-image\fR
Restore from the special image format specified by
.I SOURCE
argument. If the
.I SOURCE
is '\-' then the image is read from the standard input.
.TP
\fB\-n\fR, \fB\-\-no\-action\fR
Test the consistency of a saved image by simulating its restoring without
writing anything. The NTFS data contained in the image is not tested.
The option \fB\-\-restore\-image\fR must also be present, and the options
\fB\-\-output\fR and \fB\-\-overwrite\fR must be omitted.
.TP
\fB\-\-rescue\fR
Ignore disk read errors so disks having bad sectors, e.g. dying disks, can be
rescued the most efficiently way, with minimal stress on them. Ntfsclone works
at the lowest, sector level in this mode too thus more data can be rescued.
The contents of the unreadable sectors are filled by character '?' and the
beginning of such sectors are marked by "BadSectoR\\0".
.TP
\fB\-m\fR, \fB\-\-metadata\fR
Clone
.B ONLY METADATA
(for NTFS experts). Only cloning to a (sparse) file is allowed, unless used
the option \fB\-\-save\-image\fP is also used.
You can't metadata\-only clone to a device.
.TP
\fB\-\-ignore\-fs\-check\fR
Ignore the result of the filesystem consistency check. This option is allowed
to be used only with the
.B \-\-metadata
option, for the safety of user's data. The clusters which cause the
inconsistency are saved too.
.TP
\fB\-t\fR, \fB\-\-preserve\-timestamps\fR
Do not wipe the timestamps, to be used only with the
.B \-\-metadata
option.


.TP
\fB\-\-new\-serial\fR, or
.TP
\fB\-\-new\-half\-serial\fR
Set a new random serial number to the clone. The serial number is a 64
bit number used to identify the device during the mounting process, so
it has to be changed to enable the original file system
and the clone to be mounted at the same time on the same computer.

The option \fB\-\-new\-half\-serial\fP only changes the upper part of the
serial number, keeping the lower part which is used by Windows unchanged.

The options \fB\-\-new\-serial\fP and \fB\-\-new\-half\-serial\fP can
only be used when cloning a file system of restoring from an image.

The serial number is not the volume UUID used by Windows
to locate files which have been moved to another volume.

.TP
\fB\-f\fR, \fB\-\-force\fR
Forces ntfsclone to proceed if the filesystem is marked
"dirty" for consistency check.
.TP
\fB\-q\fR, \fB\-\-quiet\fR
Do not display any progress-bars during operation.
.TP
\fB\-h\fR, \fB\-\-help\fR
Show a list of options with a brief description of each one.
.SH EXIT CODES
The exit code is 0 on success, non\-zero otherwise.
.SH EXAMPLES
Clone NTFS on /dev/hda1 to /dev/hdc1:
.RS
.sp
.B ntfsclone \-\-overwrite /dev/hdc1 /dev/hda1
.sp
.RE
Save an NTFS to a file in the special image format:
.RS
.sp
.B ntfsclone \-\-save\-image \-\-output backup.img /dev/hda1
.sp
.RE
Restore an NTFS from a special image file to its original partition:
.RS
.sp
.B ntfsclone \-\-restore\-image \-\-overwrite /dev/hda1 backup.img
.sp
.RE
Save an NTFS into a compressed image file:
.RS
.sp
.B ntfsclone \-\-save\-image \-o \- /dev/hda1 | gzip \-c > backup.img.gz
.sp
.RE
Restore an NTFS volume from a compressed image file:
.RS
.sp
.B gunzip \-c backup.img.gz | \\\\
.br
.B ntfsclone \-\-restore\-image \-\-overwrite /dev/hda1 \-
.sp
.RE
Backup an NTFS volume to a remote host, using ssh. Please note, that 
ssh may ask for a password!
.RS
.sp
.B ntfsclone \-\-save\-image \-\-output \- /dev/hda1 | \\\\
.br
.B gzip \-c | ssh host 'cat > backup.img.gz'
.sp
.RE
Restore an NTFS volume from a remote host via ssh. Please note, that 
ssh may ask for a password!
.RS
.sp
.B ssh host 'cat backup.img.gz' | gunzip \-c | \\\\
.br
.B ntfsclone \-\-restore\-image \-\-overwrite /dev/hda1 \-
.sp
.RE
Stream an image file from a web server and restore it to a partition:
.RS
.sp
.B wget \-qO \- http://server/backup.img | \\\\
.br
.B ntfsclone \-\-restore\-image \-\-overwrite /dev/hda1 \-
.sp
.RE
Clone an NTFS volume to a non\-existent file:
.RS
.sp
.B ntfsclone \-\-output ntfs\-clone.img /dev/hda1
.sp
.RE
Pack NTFS metadata for NTFS experts. Please note that bzip2 runs
very long but results usually at least 10 times smaller archives 
than gzip on a sparse file.
.RS
.sp
.B ntfsclone \-\-metadata \-\-output ntfsmeta.img /dev/hda1
.br
.B bzip2 ntfsmeta.img
.sp
Or, outputting to a compressed image :
.br
.B ntfsclone \-mst \-\-output - /dev/hda1 | bzip2 > ntfsmeta.bz2
.sp
.RE
Unpacking NTFS metadata into a sparse file:
.RS
.sp
.B bunzip2 \-c ntfsmeta.img.bz2 | \\\\
.br
.B cp \-\-sparse=always /proc/self/fd/0 ntfsmeta.img
.sp
.RE
.SH KNOWN ISSUES
There are no known problems with
.BR ntfsclone .
If you think you have found a problem then please send an email describing it
to the development team:
.nh
ntfs\-3g\-devel@lists.sf.net
.hy
.sp
Sometimes it might appear ntfsclone froze if the clone is on ReiserFS
and even CTRL\-C won't stop it. This is not a bug in ntfsclone, however
it's due to ReiserFS being extremely inefficient creating large
sparse files and not handling signals during this operation. This
ReiserFS problem was improved in kernel 2.4.22.
XFS, JFS and ext3 don't have this problem.
.hy
.SH AUTHORS
.B ntfsclone
was written by Szabolcs Szakacsits with contributions from Per Olofsson 
(special image format support) and Anton Altaparmakov.
It was ported to ntfs-3g by Erik Larsson and Jean-Pierre Andre.
.SH AVAILABILITY
.B ntfsclone
is part of the
.B ntfs-3g
package and is available at:
.br
.nh
http://www.tuxera.com/community/
.hy
.SH SEE ALSO
.BR ntfsresize (8)
.BR ntfsprogs (8)
.BR xfs_copy (8)
.BR debugreiserfs (8)
.BR e2image (8)