Robocopy

From Wikipedia, the free encyclopedia

Robocopy, or "Robust File Copy", is a command-line directory replication command. It was available as part of the Windows Resource Kit, and introduced as a standard feature of Windows Vista and Windows Server 2008.

Robocopy is designed for reliable mirroring of directories or directory trees. It has features to ensure all NTFS attributes and properties are copied, and includes additional restart code for network connections subject to disruption.

[edit] Features

Robocopy is notable for capabilities above and beyond the built-in Windows copy and xcopy commands, including the following:

• Ability to tolerate network outages and resume copying where it previously left off (incomplete files are noted with a date stamp corresponding to 1980-01-01 and contain a recovery record so Robocopy knows from where to continue).
• Ability to correctly copy attributes, owner information, alternate data streams, auditing information, and timestamps by default, without the need for numerous often forgotten command line switches.
• Ability to correctly copy NTFS ACLs, (when /COPYALL provided), and to assert the Windows NT "backup right" (/B) so an administrator may copy an entire directory, including files denied readability to the administrator.
• Persistence by default, with a programmable number of automatic retries if a file cannot be opened.
• A "mirror" mode, which keeps trees in sync by optionally deleting files out of the destination that are no longer present in the source.
• Ability to copy large numbers of files that would otherwise crash the built-in XCOPY utility.
• A progress indicator on the command line that updates continuously.
• Ability to copy long file and folder names exceeding 256 characters — up to a theoretical 32,000 characters — without errors.^[1]
• Supports multithreaded copying (Windows 7 only).^[2]

Notably, Robocopy cannot copy open files that are in use by other users or applications. The so-called Backup mode is an administrative privilege that allows Robocopy to override permissions settings (specifically, NTFS ACLs) for the purpose of making backups. The Windows Volume Shadow Copy service is the only Windows subsystem that can copy open files while they are in use. Robocopy does not implement accessing the Volume Shadow Copy service in any way, inhibiting its usefulness as a backup utility for volumes that may be in use. However, one can use separate utilities such as VSHADOW or DISKSHADOW (included with Windows Server 2008) to create a shadow copy of a given volume with which to backup using Robocopy.

On the other hand, by design, the original Robocopy version is not able to replicate security attributes of files which have had their security permissions changed after an initial mirroring. ^[3] This behavior was changed on Robocopy versions included in Windows 2008 and Windows Vista. The downside of this approach is that it means Robocopy does not behave consistently between different platforms. ^[4]

[edit] GUI front-end

Although Robocopy itself is a command-line tool, Microsoft Technet has also provided a GUI front-end, the GUI requires the .NET Framework 2.0. It has been developed by Derk Benisch, a systems engineer with the MSN Search group at Microsoft.^[5] Robocopy GUI also includes version XP026 of Robocopy (Vista version). When downloaded from the TechNet link below, the version reported is "Microsoft Robocopy GUI 3.1.2." When this version of RoboCopy is run, it then reports on its header:

  ROBOCOPY     ::     Robust File Copy for Windows     ::     Version XP026

Subsequently, a tool called RichCopy was made available on Technet. While it is not based on Robocopy any more, it offers many similar features. ^[6]

[edit] Common usage examples

Copy directory contents recursively, all contents of foo to bar:

 robocopy C:\foo C:\bar /E

Copy directory recursively (/E), and copy all file information (/COPYALL, equivalent to /COPY:DATSOU, D=Data, A=Attributes, T=Timestamps, S=Security=NTFS ACLs, O=Owner info, U=aUditing info), do not retry locked files (/R:0). Note directory Timestamps will not be reset if using a Robocopy version older than XP026:

 robocopy C:\foo C:\bar /COPYALL /E /R:0

Mirror foo to bar, destroying any files in bar that are not present in foo (/MIR), copy files in restartable mode (/Z) in case network connection is lost:

 robocopy C:\foo \\backupserver\bar /MIR /Z

[edit] Folder copier, not file copier

The syntax of Robocopy is markedly different from that of standard copy commands, in that it only accepts the names of folders, not files, as its source and destination arguments. Names of files and wild-card designations (such as "*.*") are not acceptable as source or destination. Files may be selected or excluded using the optional filespec filtering argument. Filespecs can only refer to the filenames relative to the folders already selected for copying, and fully-qualified path names are not accepted.

For example, in order to copy the file foo.txt from directory c:\bar to c:\baz, one could use the following syntax:

 robocopy c:\bar c:\baz foo.txt

[edit] Partial list of command line switches

The following is a list of the more common command line options for Robocopy: ^[7]

[edit] Common options

/MIR 

Activates mirror mode, deleting any files in the destination that are not present in the source (equivalent to /E and /PURGE).

/Z 

Copy files in restartable mode. "Restartable" means Robocopy should write a recovery record inside an incomplete file so if the operation is interrupted or aborted, a future run of Robocopy can resume copying where the previous one left off, instead of starting over at the beginning. This is useful for reliably copying large files or many files over an unreliable network such as a VPN or the Internet. An incomplete file has the same file size as the complete file, and is noted with a date stamp in the file system being within 24 hours of 1980-01-01 00:00.

/COPYALL 

Makes sure NTFS security information is copied. Equivalent to /COPY:DATSOU, where D=Data, A=Attributes, T=Timestamps, S=Security=NTFS ACLs, O=Owner info, U=aUditing info

/B 

Opens files in backup mode. Backup mode allows files to be opened without security restrictions, but requires additional rights on both the source and destination systems.

/ZB 

Use restartable mode; if access denied use backup mode.

[edit] Specialized options

/S 

Copies subdirectories unless they are empty (like XCOPY).

/E 

Copies subdirectories, even empty ones (like XCOPY).

/M 

Copies only files with the Archive attribute and reset it (like XCOPY /M option).

/MOV 

Moves the files, removing them from the source folder.

/MOVE 

Moves files AND dirs (folders) (delete from source after copying).

/MON:n 

This will monitor and trigger a copy after n changes (and MOT minutes).

/MOT:n 

This will set the minimum monitor interval (n minutes) before another copy is triggered.

/XA:attributes 

Excludes files with any of the given attributes set. Example: /XA:H will skip copying any hidden files.

/XF filespec 

Excludes files indicated by filespec. Wildcards are accepted. Example: /XF *.bak will skip copying any file with an extension of .bak.

/XD dirspec 

Excludes directories indicated by dirspec by name/path. Wildcards work (i.e. /XD BKUP* skips copying all directories whose name starts with "BKUP", regardless of where in the source tree they are found).

/XC 

Exclude changed files.

/XN 

Exclude newer files.

/XO 

Exclude older files (Please note that the Robocopy GUI (3.1.1) does not use this switch correctly, meaning it still copies older files over newer ones. Version 3.1.2 corrects this problem.)

/XX 

Exclude extra files and directories. An "extra" file is present in destination but not source.

/XL 

Exclude lonely files and directories. A "lonely" file is present in source but not destination.

/IS 

Include same files.

/IT 

Include tweaked files (ie.: if one file has Archive attribute, while the other file has Archive and Read-only properties).

/XJ 

Exclude junctions. When copying user accounts to another place in Windows Vista, it is important to exclude junctions. The junction in '\Users\...\AppData\Local' named 'Application Data' points to its parent folder, creating a loop which will break Robocopy. Furthermore, if a junction point is contained in a source disk which is mirrored using /MIR (or /E /PURGE) to a target disk, and a junction point from the source disk is copied to the target disk, it will "point to" your source disk, potentially resulting in modification of the contents of the source disk.

/R:n 

Tells Robocopy to retry 'n' times before giving up in the event of error (default is 1 million).

/IPG:n 

Tells Robocopy to pause 'n' milliseconds between packets for network transfers. Useful to preserve bandwidth on slow lines.

/L 

List only - don't copy, timestamp or delete any files.

/W:n 

Wait time between retries (default is 30 seconds).

/PURGE 

Deletes files no longer in the source location.

/FFT 

assume FAT File Times (2-second granularity).

/DST 

Compensate for one-hour DST time differences ## available in XP026 which comes with "Robocopy GUI" or later, all other options on this page are for the XP version of Robocopy (XP010) ##

/DCOPY:T 

COPY Directory Timestamps. ### available in XP026 (WinXP) & XP027 or later (Vista)

/MAXAGE:n 

MAXimum file AGE - exclude files older than n days/date.

/MINAGE:n 

MINimum file AGE - exclude files newer than n days/date.

(If n < 1900 then n = no of days, else n = YYYYMMDD date).

/MT:n 

Multithreaded copying (Windows 7 only). n value ranges from 1 to 128 (default is 8)

[edit] Logging options

/NFL 

No file list – don't log file names.

/NDL 

No directory list – do not log directory names.

/NS 

No size – don't log file sizes.

/NC 

No class – don't log file classes.

/X 

Report all extra files, not just those selected.

/V 

Produce verbose output, showing skipped files.

/TS 

Include source file time stamps in the output.

/FP 

Include full pathname of files in the output.

/NP 

No progress – don't display % copied.

/ETA 

Show estimated time of arrival of copied files.

/LOG:file.txt 

Replace file.txt with the status of the run.

/LOG+:file.txt 

Append the status of the run to file.txt.

/TEE 

Output to console window, as well as the log file.

/NJH 

No job header.

/NJS 

No job summary.

(See a full list here)

[edit] Known flaws

This article's section does not cite any references or sources. Please help improve this article by adding citations to reliable sources. Unsourced material may be challenged and removed. (April 2008)

• XP026 version does not give return codes for ERRORLEVEL use when extra dir/file exist
• A new option in Vista (XP027) /EFSRAW : Copy any encrypted files using EFS RAW mode; is not available for XP (XP026).
• Robocopy will not copy folder timestamps from the source folder. Instead, it will use the current date and time when creating new folders. To match the timestamps to the original, another file utility must be used. This flaw has been addressed in version XP026 and the Windows Vista version of Robocopy (switch /DCOPY:T).
• Copying files in restartable mode is much slower (about 6x over a network) than in normal or backup mode due to the necessary management overhead.
• Although version XP026 can now copy compressed files this causes heavy fragmentation.
• Backup mode cannot circumvent explicit NTFS deny ACL's if the copier isn't the objects' owner. (Error message: ERROR 5 (0x00000005) Copying NTFS Security to Destination Directory. Access denied.)You can overcome this error by just copying the data in the files with these Options setting: /COPY:DT instead of the /COPYALL option
• Robocopy does not preserve Hardlinks
• Robocopy cannot copy files over FTP links
• Robocopy is known to sometimes hang when copying data across a network, leaving the computer unable to shut down and the internet inaccessible ^[8]

[edit] ErrorLevel Return Codes

The return code from Robocopy is a bit map, defined as follows:^[9]

• 0×10 Serious error. Robocopy did not copy any files. This is either a usage error or an error due to insufficient access privileges on the source or destination directories.
• 0×08 Some files or directories could not be copied (copy errors occurred and the retry limit was exceeded). Check these errors further.
• 0×04 Some Mismatched files or directories were detected. Examine the output log. Housekeeping is probably necessary.
• 0×02 Some Extra files or directories were detected. Examine the output log. Some housekeeping may be needed.
• 0×01 One or more files were copied successfully (that is, new files have arrived).
• 0×00 No errors occurred, and no copying was done. The source and destination directory trees are completely synchronized.

One can use this information in a batch file to report the most serious anomalies, as follows:

if errorlevel 16 echo ***FATAL ERROR*** & goto end
if errorlevel 8 echo **FAILED COPIES** & goto end
if errorlevel 4 echo *MISMATCHES* & goto end
if errorlevel 2 echo EXTRA FILES & goto end
if errorlevel 1 echo Copy successful & goto end
if errorlevel 0 echo –no change– & goto end
:end

Alternatively, full details of the return code could be reported as follows:

if errorlevel 16 echo ***FATAL ERROR*** & goto end
if errorlevel 15 echo FAIL MISM XTRA COPY & goto end
if errorlevel 14 echo FAIL MISM XTRA & goto end
if errorlevel 13 echo FAIL MISM COPY & goto end
if errorlevel 12 echo FAIL MISM & goto end
if errorlevel 11 echo FAIL XTRA COPY & goto end
if errorlevel 10 echo FAIL XTRA & goto end
if errorlevel 9 echo FAIL COPY & goto end
if errorlevel 8 echo FAIL & goto end
if errorlevel 7 echo MISM XTRA COPY & goto end
if errorlevel 6 echo MISM XTRA & goto end
if errorlevel 5 echo MISM COPY & goto end
if errorlevel 4 echo MISM & goto end
if errorlevel 3 echo XTRA COPY & goto end
if errorlevel 2 echo XTRA & goto end
if errorlevel 1 echo COPY & goto end
if errorlevel 0 echo –no change– & goto end
:end

[edit] Versions

[edit] See also

• copy (command)
• XCOPY
• List of DOS commands
• rsync
• SyncToy

[edit] References

[edit] External links

• Windows Server 2003 Resource Kit Tools
• Robocopy GUI from Microsoft Tech-Net
• RichCopy, an Advanced Alternative to RoboCopy