path: root/ntfsprogs/ntfsclone.8 (plain)
blob: c4f44dadf381b7a6e21281062ed868778531d097

1	.\" Copyright (c) 2003\-2005 Richard Russon.
2	.\" Copyright (c) 2003\-2006 Szabolcs Szakacsits.
3	.\" Copyright (c) 2004 Per Olofsson.
4	.\" This file may be copied under the terms of the GNU Public License.
5	.\"
6	.TH NTFSCLONE 8 "February 2006" "ntfs-3g 2014.2.15"
7	.SH NAME
8	ntfsclone \- Efficiently clone, image, restore or rescue an NTFS
9	.SH SYNOPSIS
10	.B ntfsclone
11	[\fIOPTIONS\fR]
12	.I SOURCE
13	.br
14	.B ntfsclone \-\-save\-image
15	[\fIOPTIONS\fR]
16	.I SOURCE
17	.br
18	.B ntfsclone \-\-restore\-image
19	[\fIOPTIONS\fR]
20	.I SOURCE
21	.br
22	.B ntfsclone \-\-metadata
23	[\fIOPTIONS\fR]
24	.I SOURCE
25	.SH DESCRIPTION
26	.B ntfsclone
27	will efficiently clone (copy, save, backup, restore) or rescue an NTFS
28	filesystem to a sparse file, image, device (partition) or standard output.
29	It works at disk sector level and
30	copies only the used data. Unused disk space becomes zero (cloning to
31	sparse file), encoded with control codes (saving in special image format),
32	left unchanged (cloning to a disk/partition) or
33	filled with zeros (cloning to standard output).
34
35	.B ntfsclone
36	can be useful to make backups, an exact snapshot of an NTFS filesystem
37	and restore it later on, or for developers to test NTFS read/write
38	functionality, troubleshoot/investigate users' issues using the clone
39	without the risk of destroying the original filesystem.
40
41	The clone, if not using the special image format, is an exact copy of the
42	original NTFS filesystem from sector to sector thus it can be also mounted
43	just like the original NTFS filesystem.
44	For example if you clone to a file and the kernel has loopback device and
45	NTFS support then the file can be mounted as
46	.RS
47	.sp
48	.B mount \-t ntfs \-o loop ntfsclone.img /mnt/ntfsclone
49	.sp
50	.RE
51	.SS Windows Cloning
52	If you want to copy, move or restore a system or boot partition to another
53	computer, or to a different disk or partition (e.g. hda1\->hda2, hda1\->hdb1
54	or to a different disk sector offset) then you will need to take extra care.
55
56	Usually, Windows will not be able to boot, unless you copy, move or restore
57	NTFS to the same partition which starts at the same sector on the same type
58	of disk having the same BIOS legacy cylinder setting as the original
59	partition and disk had.
60
61	The ntfsclone utility guarantees to make an exact copy of NTFS but it
62	won't deal with booting issues. This is by design: ntfsclone is a
63	filesystem, not system utility. Its aim is only NTFS cloning, not Windows
64	cloning. Hereby ntfsclone can be used as a very fast and reliable
65	build block for Windows cloning but itself it's not enough.
66	.SS Sparse Files
67	A file is sparse if it has unallocated blocks (holes). The reported size of
68	such files are always higher than the disk space consumed by them. The
69	.BR du
70	command can tell the real disk space used by a sparse file.
71	The holes are always read as zeros. All major Linux filesystem like,
72	ext2, ext3, reiserfs, Reiser4, JFS and XFS, supports
73	sparse files but for example the ISO 9600 CD\-ROM filesystem doesn't.
74	.SS Handling Large Sparse Files
75	As of today Linux provides inadequate support for managing (tar,
76	cp, gzip, gunzip, bzip2, bunzip2, cat, etc) large sparse files.
77	The only main Linux filesystem
78	having support for efficient sparse file handling is XFS by the
79	XFS_IOC_GETBMAPX
80	.BR ioctl (2) .
81	However none of the common utilities supports it.
82	This means when you tar, cp, gzip, bzip2, etc a large sparse file
83	they will always read the entire file, even if you use the "sparse support"
84	options.
85
86	.BR bzip2 (1)
87	compresses large sparse files much better than
88	.BR gzip (1)
89	but it does so
90	also much slower. Moreover neither of them handles large sparse
91	files efficiently during uncompression from disk space usage point
92	of view.
93
94	At present the most efficient way, both speed and space\-wise, to
95	compress and uncompress large sparse files by common tools
96	would be using
97	.BR tar (1)
98	with the options
99	.B \-S
100	(handle sparse files "efficiently") and
101	.B \-j
102	(filter the archive through bzip2). Although
103	.BR tar
104	still reads and analyses the entire file, it doesn't pass on the
105	large data blocks having only zeros to filters and it also avoids
106	writing large amount of zeros to the disk needlessly. But since
107	.BR tar
108	can't create an archive from the standard input, you can't do this
109	in\-place by just reading
110	.BR ntfsclone
111	standard output. Even more sadly, using the \-S option results
112	serious data loss since the end of 2004 and the GNU
113	.BR tar
114	maintainers didn't release fixed versions until the present day.
115	.SS The Special Image Format
116	It's also possible, actually it's recommended, to save an NTFS filesystem
117	to a special image format.
118	Instead of representing unallocated blocks as holes, they are
119	encoded using control codes. Thus, the image saves space without
120	requiring sparse file support. The image format is ideal for streaming
121	filesystem images over the network and similar, and can be used as a
122	replacement for Ghost or Partition Image if it is combined with other
123	tools. The downside is that you can't mount the image directly, you
124	need to restore it first.
125
126	To save an image using the special image format, use the
127	.B \-s
128	or the
129	.B \-\-save\-image
130	option. To restore an image, use the
131	.B \-r
132	or the
133	.B \-\-restore\-image
134	option. Note that you can restore images from standard input by
135	using '\-' as the
136	.I SOURCE
137	file.
138	.SS Metadata\-only Cloning
139	One of the features of
140	.BR ntfsclone
141	is that, it can also save only the NTFS metadata using the option
142	.B \-m
143	or
144	.B \-\-metadata
145	and the clone still will be
146	mountable. In this case all non\-metadata file content will be lost and
147	reading them back will result always zeros.
148
149	The metadata\-only image can be compressed very
150	well, usually to not more than 1\-8 MB thus it's easy to transfer
151	for investigation, troubleshooting.
152
153	In this mode of ntfsclone,
154	.B NONE
155	of the user's data is saved, including the resident user's data
156	embedded into metadata. All is filled with zeros.
157	Moreover all the file timestamps, deleted and unused spaces inside
158	the metadata are filled with zeros. Thus this mode is inappropriate
159	for example for forensic analyses.
160	This mode may be combined with \fB\-\-save\-image\fP to create a
161	special image format file instead of a sparse file.
162
163	Please note, filenames are not wiped out. They might contain
164	sensitive information, so think twice before sending such an
165	image to anybody.
166	.SH OPTIONS
167	Below is a summary of all the options that
168	.B ntfsclone
169	accepts. Nearly all options have two equivalent names. The short name is
170	preceded by
171	.B \-
172	and the long name is preceded by
173	.B \-\- .
174	Any single letter options, that don't take an argument, can be combined into a
175	single command, e.g.
176	.B \-fv
177	is equivalent to
178	.B "\-f \-v" .
179	Long named options can be abbreviated to any unique prefix of their name.
180	.TP
181	\fB\-o\fR, \fB\-\-output\fR FILE
182	Clone NTFS to the non\-existent
183	.IR FILE .
184	If
185	.I FILE
186	is '\-' then clone to the
187	standard output.
188	.TP
189	\fB\-O\fR, \fB\-\-overwrite\fR FILE
190	Clone NTFS to
191	.IR FILE ,
192	overwriting if exists.
193	.TP
194	\fB\-s\fR, \fB\-\-save\-image\fR
195	Save to the special image format. This is the most efficient way space and
196	speed\-wise if imaging is done to the standard output, e.g. for image
197	compression, encryption or streaming through a network.
198	.TP
199	\fB\-r\fR, \fB\-\-restore\-image\fR
200	Restore from the special image format specified by
201	.I SOURCE
202	argument. If the
203	.I SOURCE
204	is '\-' then the image is read from the standard input.
205	.TP
206	\fB\-n\fR, \fB\-\-no\-action\fR
207	Test the consistency of a saved image by simulating its restoring without
208	writing anything. The NTFS data contained in the image is not tested.
209	The option \fB\-\-restore\-image\fR must also be present, and the options
210	\fB\-\-output\fR and \fB\-\-overwrite\fR must be omitted.
211	.TP
212	\fB\-\-rescue\fR
213	Ignore disk read errors so disks having bad sectors, e.g. dying disks, can be
214	rescued the most efficiently way, with minimal stress on them. Ntfsclone works
215	at the lowest, sector level in this mode too thus more data can be rescued.
216	The contents of the unreadable sectors are filled by character '?' and the
217	beginning of such sectors are marked by "BadSectoR\\0".
218	.TP
219	\fB\-m\fR, \fB\-\-metadata\fR
220	Clone
221	.B ONLY METADATA
222	(for NTFS experts). Only cloning to a (sparse) file is allowed, unless used
223	the option \fB\-\-save\-image\fP is also used.
224	You can't metadata\-only clone to a device.
225	.TP
226	\fB\-\-ignore\-fs\-check\fR
227	Ignore the result of the filesystem consistency check. This option is allowed
228	to be used only with the
229	.B \-\-metadata
230	option, for the safety of user's data. The clusters which cause the
231	inconsistency are saved too.
232	.TP
233	\fB\-t\fR, \fB\-\-preserve\-timestamps\fR
234	Do not wipe the timestamps, to be used only with the
235	.B \-\-metadata
236	option.
237
238
239	.TP
240	\fB\-\-new\-serial\fR, or
241	.TP
242	\fB\-\-new\-half\-serial\fR
243	Set a new random serial number to the clone. The serial number is a 64
244	bit number used to identify the device during the mounting process, so
245	it has to be changed to enable the original file system
246	and the clone to be mounted at the same time on the same computer.
247
248	The option \fB\-\-new\-half\-serial\fP only changes the upper part of the
249	serial number, keeping the lower part which is used by Windows unchanged.
250
251	The options \fB\-\-new\-serial\fP and \fB\-\-new\-half\-serial\fP can
252	only be used when cloning a file system of restoring from an image.
253
254	The serial number is not the volume UUID used by Windows
255	to locate files which have been moved to another volume.
256
257	.TP
258	\fB\-f\fR, \fB\-\-force\fR
259	Forces ntfsclone to proceed if the filesystem is marked
260	"dirty" for consistency check.
261	.TP
262	\fB\-q\fR, \fB\-\-quiet\fR
263	Do not display any progress-bars during operation.
264	.TP
265	\fB\-h\fR, \fB\-\-help\fR
266	Show a list of options with a brief description of each one.
267	.SH EXIT CODES
268	The exit code is 0 on success, non\-zero otherwise.
269	.SH EXAMPLES
270	Clone NTFS on /dev/hda1 to /dev/hdc1:
271	.RS
272	.sp
273	.B ntfsclone \-\-overwrite /dev/hdc1 /dev/hda1
274	.sp
275	.RE
276	Save an NTFS to a file in the special image format:
277	.RS
278	.sp
279	.B ntfsclone \-\-save\-image \-\-output backup.img /dev/hda1
280	.sp
281	.RE
282	Restore an NTFS from a special image file to its original partition:
283	.RS
284	.sp
285	.B ntfsclone \-\-restore\-image \-\-overwrite /dev/hda1 backup.img
286	.sp
287	.RE
288	Save an NTFS into a compressed image file:
289	.RS
290	.sp
291	.B ntfsclone \-\-save\-image \-o \- /dev/hda1 | gzip \-c > backup.img.gz
292	.sp
293	.RE
294	Restore an NTFS volume from a compressed image file:
295	.RS
296	.sp
297	.B gunzip \-c backup.img.gz | \\\\
298	.br
299	.B ntfsclone \-\-restore\-image \-\-overwrite /dev/hda1 \-
300	.sp
301	.RE
302	Backup an NTFS volume to a remote host, using ssh. Please note, that
303	ssh may ask for a password!
304	.RS
305	.sp
306	.B ntfsclone \-\-save\-image \-\-output \- /dev/hda1 | \\\\
307	.br
308	.B gzip \-c | ssh host 'cat > backup.img.gz'
309	.sp
310	.RE
311	Restore an NTFS volume from a remote host via ssh. Please note, that
312	ssh may ask for a password!
313	.RS
314	.sp
315	.B ssh host 'cat backup.img.gz' | gunzip \-c | \\\\
316	.br
317	.B ntfsclone \-\-restore\-image \-\-overwrite /dev/hda1 \-
318	.sp
319	.RE
320	Stream an image file from a web server and restore it to a partition:
321	.RS
322	.sp
323	.B wget \-qO \- http://server/backup.img | \\\\
324	.br
325	.B ntfsclone \-\-restore\-image \-\-overwrite /dev/hda1 \-
326	.sp
327	.RE
328	Clone an NTFS volume to a non\-existent file:
329	.RS
330	.sp
331	.B ntfsclone \-\-output ntfs\-clone.img /dev/hda1
332	.sp
333	.RE
334	Pack NTFS metadata for NTFS experts. Please note that bzip2 runs
335	very long but results usually at least 10 times smaller archives
336	than gzip on a sparse file.
337	.RS
338	.sp
339	.B ntfsclone \-\-metadata \-\-output ntfsmeta.img /dev/hda1
340	.br
341	.B bzip2 ntfsmeta.img
342	.sp
343	Or, outputting to a compressed image :
344	.br
345	.B ntfsclone \-mst \-\-output - /dev/hda1 | bzip2 > ntfsmeta.bz2
346	.sp
347	.RE
348	Unpacking NTFS metadata into a sparse file:
349	.RS
350	.sp
351	.B bunzip2 \-c ntfsmeta.img.bz2 | \\\\
352	.br
353	.B cp \-\-sparse=always /proc/self/fd/0 ntfsmeta.img
354	.sp
355	.RE
356	.SH KNOWN ISSUES
357	There are no known problems with
358	.BR ntfsclone .
359	If you think you have found a problem then please send an email describing it
360	to the development team:
361	.nh
362	ntfs\-3g\-devel@lists.sf.net
363	.hy
364	.sp
365	Sometimes it might appear ntfsclone froze if the clone is on ReiserFS
366	and even CTRL\-C won't stop it. This is not a bug in ntfsclone, however
367	it's due to ReiserFS being extremely inefficient creating large
368	sparse files and not handling signals during this operation. This
369	ReiserFS problem was improved in kernel 2.4.22.
370	XFS, JFS and ext3 don't have this problem.
371	.hy
372	.SH AUTHORS
373	.B ntfsclone
374	was written by Szabolcs Szakacsits with contributions from Per Olofsson
375	(special image format support) and Anton Altaparmakov.
376	It was ported to ntfs-3g by Erik Larsson and Jean-Pierre Andre.
377	.SH AVAILABILITY
378	.B ntfsclone
379	is part of the
380	.B ntfs-3g
381	package and is available at:
382	.br
383	.nh
384	http://www.tuxera.com/community/
385	.hy
386	.SH SEE ALSO
387	.BR ntfsresize (8)
388	.BR ntfsprogs (8)
389	.BR xfs_copy (8)
390	.BR debugreiserfs (8)
391	.BR e2image (8)
392