Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
CPDUP(1)		FreeBSD	General	Commands Manual		      CPDUP(1)

     cpdup -- mirror filesystems

     cpdup [-C]	[-v[v[v]]] [-d]	[-n] [-u] [-I] [-f] [-F	ssh-arg] [-s0] [-i0]
	   [-j0] [-l] [-q] [-o]	[-m] [-H path] [-M file] [-V] [-VV] [-S] [-R]
	   [-k]	[-K file] [-X file] [-x] [[user@]host:]source_dir

     The cpdup utility makes an	exact mirror copy of the source	in the desti-
     nation, creating and deleting files and directories as necessary.
     UTimes, hardlinks,	softlinks, devices, permissions, and flags are mir-
     rored.  By	default, cpdup asks for	confirmation if	any file or directory
     needs to be removed from the destination and does not copy	files which it
     believes to have already been synchronized	(by observing that the source
     and destination files' sizes and mtimes match).  cpdup does not cross
     mount points in either the	source or the destination.  As a safety	mea-
     sure, cpdup refuses to replace a destination directory with a file.

     The following options are available:

     -C	   If the source or target is a	remote host, request that the ssh(1)
	   session be compressed.  This	is the same as -F -C.

	   Set verboseness.  By	default	cpdup does not report its progress ex-
	   cept	when asking for	confirmation.  A single	-v will	only report
	   modifications made to the destination.  -vv will report directories
	   as they are being traversed as well as modifications	made to	the
	   destination.	 -vvv will cause all files and directories to be re-
	   ported whether or not modifications are made.

     -d	   Print directories as	they are being traversed.  Useful to watch the
	   progress; this typically produces much less output than -vv.

     -n	   Go through the motions but don't actually make any changes to the

     -u	   Causes the output generated by -v and -d to be unbuffered.  This
	   can be useful for obtaining prompt progress updates through a pipe.

     -I	   will	cause cpdup to print a summary at the end with performance

     -f	   Forces file updates to occur	even if	the files appear to be the
	   same.  If the -H option is used, this option	will force a byte for
	   byte	comparison between the original	file and the file in the
	   hardlink path, even if all the stat info matches, but will still
	   use a hardlink if they match.

     -F	ssh-arg
	   Pass	ssh-arg	to ssh.	 For example "-F -p222".  Note the lack	of a

     -s0   Disable the disallow-file-replaces-directory	safety feature.	 This
	   safety feature is enabled by	default	to prevent user	mistakes from
	   blowing away	everything accidentally.

     -i0   Do not request confirmation when removing something.

     -j0   Do not try to recreate CHR or BLK devices.

     -l	   Line	buffer verbose output.

     -q	   Quiet operation.

     -o	   Do not remove any files, just overwrite/add.

     -m	   Generate and	maintain a MD5 checkfile called	.MD5.CHECKSUMS in each
	   directory on	the source and do an MD5 check on each file of the
	   destination when the	destination appears to be the same as the
	   source.  If the check fails,	the source is recopied to the destina-
	   tion.  When you specify a destination directory, the	MD5 checkfile
	   is only updated as needed and may not be updated even if modifica-
	   tions are made to a source file.  If	you do not specify a destina-
	   tion	directory the cpdup command forcefully regenerates the MD5
	   checkfile for every file in the source.

     -M	file
	   Works the same as -m	but allows you to specify the name of the MD5

     -H	path
	   cpdup will create a hardlink	from a file found under	path to	the
	   target instead of copying the source	to the target if the file
	   found via path is identical to the source.  Note that a remote host
	   specification should	not be used for	this option's path, but	the
	   path	will be	relative to the	target machine.

	   This	allows one to use cpdup	to create incremental backups of a
	   filesystem.	Create a direct	`level 0' backup, and then specify the
	   level 0 backup path with this option	when creating an incremental
	   backup to a different target	directory.  This method	works so long
	   as the filesystem does not hit a hardlink limit.  If	the system
	   does	hit a hardlink limit, cpdup will generate a warning and	copy
	   the file instead.  Note that	cpdup must record file paths for any
	   hardlinked file while operating and therefore uses a	great deal
	   more	memory when dealing with hardlinks or hardlink-based backups.
	   Example use:

		 cpdup -i0 -s0 -I -H /backup/home.l0 /home /backup/home.l1

	   WARNING: If this option is used cpdup must record the paths for all
	   files it encounters while it	operates and it	is possible that you
	   may run the process out of memory.

	   The file found via the hardlink path	will be	byte-by-byte compared
	   with	the source if the -V or	-f option is also used,	otherwise only
	   the stat info is checked to determine whether it matches the

     -V	   This	forces the contents of regular files to	be verified, even if
	   the files appear to the be the same.	 Whereas the -f	(force)	option
	   forces a copy regardless, this option will avoid rewriting the tar-
	   get if everything matches and the contents are verified to be the

     -VV   This	works the same as -V but ignores mtime entirely, making	it
	   suitable for	comparing HAMMER master	and slave filesystems or
	   copies made without mtime retention.

     -S	   This	places cpdup into slave	mode and is used to initiate the slave
	   protocol on a remote	machine.  This option is not intended to be
	   used	by humans.

     -R	   Place the slave into	read-only mode.	 Can only be used when the
	   source is remote.  Useful for unattended backups via	SSH keys.

     -k	   Generate and	maintain a FSMID checkfile called  .FSMID.CHECK	in
	   each	directory on the target.  cpdup	will check the FSMID for each
	   source file or directory against the	checkfile on the target	and
	   will	not copy the file or recurse through the directory when	a
	   match occurs.  Any source file or directory with the	same name as
	   the checkfile will be ignored.  The FSMID will be re-checked	after
	   the copy has	been completed and cpdup will loop on that directory
	   or file until it is sure it has an exact copy.

	   Warning: FSMID is not always	supported by a filesystem and may not
	   be synchronized if a	crash occurs.  DragonFly will simulate an FS-
	   MID when it is otherwise not	supported by the filesystem, and users
	   should be aware that	simulated FSMIDs may change state in such
	   cases even if the underlying	hierarchy does not due to cache
	   flushes.  Additionally, the FSMID may not reflect changes made to
	   remote filesystems by other hosts.  For example, using these	op-
	   tions with NFS mounted sources will not work	well.

     -K	file
	   Works the same as -k	but allows you to specify the name of the FS-
	   MID checkfile.

     -x	   Causes cpdup	to use the exclusion file .cpignore in each directory
	   on the source to determine which files to ignore.  When this	option
	   is used, the	exclusion filename itself is automatically excluded
	   from	the copy.  If this option is not used then the filename
	   .cpignore is	not considered special and will	be copied along	with
	   everything else.

     -X	file
	   Works similarly to -x but allows you	to specify the name of the ex-
	   clusion file.  This file is automatically excluded from the copy.
	   Only	one exclusion file may be specified.

	   When	an absolute path is used, the same exclusive file is read for
	   every directory and may contain full	paths or wildcarded paths
	   based on the	full source path as specified on the cpdup command
	   line.  In this situation, the exclusive file	is read	from the host
	   running the command,	NOT from the source host (if remote).

	   When	a relative path	is used	(or -x is specified), the exclusion
	   file	is only	applicable to the directory it resides in on the
	   source host and only	path elements (the directory elements) are
	   matched against it.

     cpdup can mirror directory	structures across machines and can also	do
     third-party copies.  This also works between machines that	use different
     byte order.  ssh(1) sessions are used and cpdup is	run on the remote ma-
     chine(s) in slave mode.  You can use the -F option	to pass	additional
     flags to the ssh command if necessary.

     The syntax	of remote path specifications is similar to scp(1).  In	par-
     ticular, that means that a	local path containing a	colon must be preceded
     by	a slash	to prevent it being considered a remote	host: `foo:bar'	causes
     cpdup to look for a directory called `bar'	on host	`foo', while
     `./foo:bar' denotes the directory `foo:bar' on the	local machine.

     cpdup also	supports a `localhost:'	prefix which is	silently discarded but
     prevents any colons in the	remainder of the path from being interpreted
     as	a host:path form.  this	form can be used with relative filenames when
     you do not	want colons in the filename to be misinterpreted.

     The cpdup utility exits 0 on success, and >0 if an	error occurs.

     cp(1), cpio(1), scp(1), ssh(1), tar(1)

     The cpdup command was originally created to update	servers	at BEST	Inter-
     net circa 1997 and	was placed under the FreeBSD copyright for inclusion
     in	the ports area in 1999.	 The program was written by Matthew Dillon,
     Dima Ruban, and later significantly improved by Oliver Fromme.

     UFS(5) has	a hardlink limit of 32767.  Many programs, in particular CVS
     with regards to its CVS/Root file,	will generate a	lot of hard links.
     When using	the -H option it may not be possible for cpdup to maintain
     these hard	links.	If this	occurs,	cpdup will be forced to	copy the file
     instead of	link it, and thus not be able to make a	perfect	copy of	the

     When so-called sparse files (i.e. files with "holes") are copied, the
     holes will	be filled in the target	files, so they occupy more physical
     disk space	than the source	files.

     For compatibility reasons,	the slave protocol is not as efficient for
     writing remote files as it	is for reading them.  Therefore	it is recom-
     mended to run cpdup on the	target machine when making remote copies, so
     the source	machine	is remote.  If you do it the other way,	cpdup will run
     somewhat slower.

FreeBSD	13.0		       November	24, 2009		  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help