path: root/usr.bin/rsync/rsync.1

.\"	$OpenBSD: rsync.1,v 1.11 2019/03/18 18:11:07 jmc Exp $
.\"
.\" Copyright (c) 2019 Kristaps Dzonsons <kristaps@bsd.lv>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: March 18 2019 $
.Dt RSYNC 1
.Os
.Sh NAME
.Nm rsync ,
.Nm openrsync
.Nd synchronise local and remote files
.Sh SYNOPSIS
.Nm rsync
.Op Fl aDglnoprtv
.Op Fl e Ar program
.Op Fl -archive
.Op Fl -delete
.Op Fl -devices
.Op Fl -group
.Op Fl -links
.Op Fl -dry-run
.Op Fl -owner
.Op Fl -perms
.Op Fl -port Ns = Ns Ar portnumber
.Op Fl -recursive
.Op Fl -rsh Ns = Ns Ar program
.Op Fl -rsync-path Ns = Ns Ar program
.Op Fl -specials
.Op Fl -times
.Op Fl -verbose
.Op Fl -version
.Ar source ...
.Ar directory
.Sh DESCRIPTION
The
.Nm
utility synchronises files in the destination
.Ar directory
with one or more
.Ar source
files.
Either the
.Ar source
or the destination
.Ar directory
may be remote,
but not both.
The arguments are as follows:
.Bl -tag -width Ds
.It Fl a , Fl -archive
Archive mode.
Shorthand for
.Fl Dgloprt .
.It Fl D
Transfer device and special files.
Shorthand for
.Fl -devices -specials
.It Fl -delete
Delete files in
.Ar directory
not found in
.Ar source
directories.
Only applicable with
.Fl r .
.It Fl -devices
Transfer device files.
.It Fl e Ar program , Fl -rsh Ns = Ns Ar program
Specify alternative program, defaults to
.Xr ssh 1 .
.It Fl g , Fl -group
Set group identifier to match the source.
Groups are matched by name: group
.Qq kristaps
with id 1000 on a remote server will be properly assigned group
.Qq kristaps
on the local machine with id 2000.
If the sender's group is unknown on the local machine, it is used
verbatim.
.It Fl l , Fl -links
Transfer symbolic links.
The link is transferred as a standalone file: if the destination does
not exist, it will be broken.
.It Fl n , Fl -dry-run
Dry-run mode.
Does not actually modify the destination.
.It Fl o , Fl -owner
Set user identifier to match the source.
This behaves like
.Fl g
and only works if run as root.
.It Fl p , Fl -perms
Set destination file or directory permissions to match the source when
it is updated.
.It Fl -port Ns = Ns Ar portnumber
Specify alternative port number.
.It Fl r , Fl -recursive
If
.Ar source
designates a directory, synchronise the directory and the entire subtree
connected at that point.
If
.Ar source
ends with a slash, only the subtree is synchronised, not the root
directory.
If
.Ar source
is a file, this has no effect.
.It Fl -rsync-path Ns = Ns Ar program
Run
.Ar prog
on the remote host instead of the default
.Ar rsync .
.It Fl -specials
Transfer fifo and unix domain socket files.
.It Fl t , Fl -times
Set destination file and directory modification time to match the source
when it is updated or created.
.It Fl v , Fl -verbose
Increase verbosity.
Specify once for files being transferred, twice for specific status,
thrice for per-file transfer information, and four times for per-file
breakdowns.
.It Fl -version
Print version and exit.
.El
.Pp
A remote
.Ar source
or
.Ar directory
has syntax
.Ar host:path
for connecting via
.Xr ssh 1 ,
or
.Ar rsync://host/path
or
.Ar host::path
for connecting to a remote daemon.
Subsequent to the first remote
.Ar source ,
the host may be dropped to become just
.Ar :path
or
.Ar ::path .
.Pp
For connecting to a remote daemon with
.Ar rsync://host
or
.Ar host::path ,
the first path component is interpreted as a
.Qq module :
.Ar host::module/path .
This only applies to the first
.Ar source
invocation; subsequent to that, the module should not be specified.
.Pp
By default, new destination files and directories are given the current
time and the source file permissions.
Updated files retain their existing permissions.
It is an error if updated files have their file types change (e.g.,
updating a directory with a file).
.Pp
At this time,
.Ar source
may only consist of regular files, directories
.Pq only with Fl r ,
or symbolic links
.Pq only with Fl l .
The destination
.Ar directory
must be a directory and is created if not found.
.Pp
.Nm
is compatible with the GPL-licensed
rsync protocol version 27.
.\" The following requests should be uncommented and used where appropriate.
.\" .Sh CONTEXT
.\" For section 9 functions only.
.\" .Sh RETURN VALUES
.\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only.
.\" .Sh FILES
.\" .Sh EXIT STATUS
.\" For sections 1, 6, and 8 only.
.Sh EXAMPLES
All examples use
.Fl t
so that destination files inherit the source time.
If not changed, subsequent invocations of
.Nm
will then consider the file up to date and not transfer block hashes.
.Pp
To update the out-of-date remote files
.Pa host:dest/bar
and
.Pa host:dest/baz
with the local
.Pa ../src/bar
and
.Pa ../src/baz :
.Pp
.Dl % rsync -t ../src/bar ../src/baz host:dest
.Pp
To update the out-of-date local files
.Pa bar
and
.Pa baz
with the remote files
.Pa host:src/bar
and
.Pa host:src/baz :
.Pp
.Dl % rsync -t host:src/bar :src/baz \&.
.Pp
To update the out-of-date local files
.Pa ../dest/bar
and
.Pa ../dest/baz
with
.Pa bar
and
.Pa baz :
.Pp
.Dl % rsync -t bar baz ../dest
.Pp
To update the out-of-date remote files in
.Pa host:dest
on a remote host running
.Nm
with the local host running
.Nm :
.Pp
.Dl % rsync --rsync-path rsync -t ../dest/* host:dest
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.Sh SEE ALSO
.Xr ssh 1 ,
.Xr rsync 5 ,
.Xr rsyncd 5
.\" .Sh STANDARDS
.\" .Sh HISTORY
.\" .Sh AUTHORS
.\" .Sh CAVEATS
.\" .Sh BUGS