DragonFly On-Line Manual Pages
CPDUP(1) DragonFly General Commands Manual CPDUP(1)
NAME
cpdup - mirror filesystems
SYNOPSIS
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]
[-X file] [-x] [[user@]host:]source_dir [[user@]host:]target_dir
DESCRIPTION
The cpdup utility makes an exact mirror copy of the source in the
destination, creating and deleting files and directories as necessary.
UTimes, hardlinks, softlinks, devices, permissions, and flags are
mirrored. 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 measure, 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.
-v[v[v]]
Set verboseness. By default cpdup does not report its progress
except 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
reported 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
target.
-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
counters.
-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
space.
-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
destination. When you specify a destination directory, the MD5
checkfile is only updated as needed and may not be updated even if
modifications are made to a source file. If you do not specify a
destination 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
checkfile.
-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
source.
-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
target if everything matches and the contents are verified to be
the same.
-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.
-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
exclusion 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.
REMOTE COPYING
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
machine(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
particular, 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.
EXIT STATUS
The cpdup utility exits 0 on success, and >0 if an error occurs.
SEE ALSO
cp(1), cpio(1), scp(1), ssh(1), tar(1)
HISTORY
The cpdup command was originally created to update servers at BEST
Internet 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.
BUGS
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
filesystem.
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
recommended 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.
DragonFly 5.9-DEVELOPMENT December 28, 2020 DragonFly 5.9-DEVELOPMENT