Annotation of src/usr.bin/rsync/rsync.1, Revision 1.21
1.21 ! deraadt 1: .\" $OpenBSD: rsync.1,v 1.20 2020/01/04 11:53:53 schwarze Exp $
1.1 benno 2: .\"
3: .\" Copyright (c) 2019 Kristaps Dzonsons <kristaps@bsd.lv>
4: .\"
5: .\" Permission to use, copy, modify, and distribute this software for any
6: .\" purpose with or without fee is hereby granted, provided that the above
7: .\" copyright notice and this permission notice appear in all copies.
8: .\"
9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16: .\"
1.21 ! deraadt 17: .Dd $Mdocdate: January 4 2020 $
1.12 schwarze 18: .Dt OPENRSYNC 1
1.1 benno 19: .Os
20: .Sh NAME
1.11 jmc 21: .Nm openrsync
1.1 benno 22: .Nd synchronise local and remote files
23: .Sh SYNOPSIS
1.12 schwarze 24: .Nm openrsync
1.17 bket 25: .Op Fl aDglnoprtvx
1.10 jmc 26: .Op Fl e Ar program
1.21 ! deraadt 27: .Op Fl -address Ns = Ns Ar sourceaddr
1.13 naddy 28: .Op Fl -del
1.16 schwarze 29: .Op Fl -numeric-ids
30: .Op Fl -port Ns = Ns Ar service
1.10 jmc 31: .Op Fl -rsync-path Ns = Ns Ar program
32: .Op Fl -version
1.1 benno 33: .Ar source ...
34: .Ar directory
35: .Sh DESCRIPTION
36: The
37: .Nm
38: utility synchronises files in the destination
39: .Ar directory
40: with one or more
41: .Ar source
42: files.
43: Either the
44: .Ar source
45: or the destination
46: .Ar directory
47: may be remote,
48: but not both.
49: The arguments are as follows:
50: .Bl -tag -width Ds
1.14 schwarze 51: .It Fl a , -archive
1.6 florian 52: Shorthand for
1.10 jmc 53: .Fl Dgloprt .
1.21 ! deraadt 54: .It Fl -address Ns = Ns Ar sourceaddr
! 55: When connecting to an rsync daemon, use
! 56: .Ar sourceaddr
! 57: as the source address for connections, which is useful on machines with
! 58: multiple interfaces.
1.6 florian 59: .It Fl D
1.16 schwarze 60: Also transfer device and special files.
1.6 florian 61: Shorthand for
1.16 schwarze 62: .Fl -devices -specials .
1.13 naddy 63: .It Fl -del , -delete
1.10 jmc 64: Delete files in
65: .Ar directory
66: not found in
67: .Ar source
68: directories.
69: Only applicable with
70: .Fl r .
1.6 florian 71: .It Fl -devices
1.16 schwarze 72: Also transfer device files.
1.10 jmc 73: .It Fl e Ar program , Fl -rsh Ns = Ns Ar program
1.16 schwarze 74: Specify alternative communication program, defaults to
1.8 deraadt 75: .Xr ssh 1 .
1.14 schwarze 76: .It Fl g , -group
1.16 schwarze 77: Set the group name to match the source.
78: For example, group
1.3 benno 79: .Qq kristaps
1.16 schwarze 80: with ID 1000 on a remote server is matched to group
1.3 benno 81: .Qq kristaps
1.16 schwarze 82: on the local machine with ID 2000.
83: If
84: .Fl -numeric-ids
85: is also given or if the remote group name is unknown on the local machine,
86: set the numeric group ID to match the source instead.
1.14 schwarze 87: .It Fl l , -links
1.16 schwarze 88: Also transfer symbolic links.
1.1 benno 89: The link is transferred as a standalone file: if the destination does
90: not exist, it will be broken.
1.14 schwarze 91: .It Fl n , -dry-run
1.16 schwarze 92: Do not actually modify the destination.
93: Mainly useful in combination with
94: .Fl v .
95: .It Fl -numeric-ids
96: Ignore user and group names, use numeric user and group IDs only.
97: Has no effect unless
98: .Fl g
99: or
100: .Fl o
101: is also given.
1.14 schwarze 102: .It Fl o , -owner
1.16 schwarze 103: Set the user name to match the source, with similar matching logic as for
104: .Fl g .
105: If
106: .Fl -numeric-ids
107: is also given or if the remote user name is unknown on the local machine,
108: set the numeric user ID to match the source instead.
109: Only works if run as root.
1.14 schwarze 110: .It Fl p , -perms
1.1 benno 111: Set destination file or directory permissions to match the source when
112: it is updated.
1.16 schwarze 113: .It Fl -port Ns = Ns Ar service
114: Specify an alternative TCP port number.
115: The
116: .Ar service
117: can be given as a decimal integer or as a name to be looked up in the
118: .Xr services 5
119: database.
120: The default is
121: .Dq rsync .
1.14 schwarze 122: .It Fl r , -recursive
1.1 benno 123: If
124: .Ar source
125: designates a directory, synchronise the directory and the entire subtree
126: connected at that point.
127: If
128: .Ar source
1.16 schwarze 129: ends with a slash, only the subtree is synchronised, not the
130: .Ar source
131: directory itself.
1.1 benno 132: If
133: .Ar source
134: is a file, this has no effect.
1.10 jmc 135: .It Fl -rsync-path Ns = Ns Ar program
136: Run
1.16 schwarze 137: .Ar program
1.10 jmc 138: on the remote host instead of the default
1.16 schwarze 139: .Pa rsync .
1.6 florian 140: .It Fl -specials
1.16 schwarze 141: Also transfer fifo and unix domain socket files.
1.14 schwarze 142: .It Fl t , -times
1.1 benno 143: Set destination file and directory modification time to match the source
144: when it is updated or created.
1.14 schwarze 145: .It Fl v , -verbose
1.1 benno 146: Increase verbosity.
147: Specify once for files being transferred, twice for specific status,
148: thrice for per-file transfer information, and four times for per-file
149: breakdowns.
1.17 bket 150: .It Fl x
151: Do not cross filesystem boundaries.
152: If this option is repeated, all mount point directories from the copy are
153: omitted.
154: Otherwise, it includes an empty directory at each mount point it encounters.
1.5 deraadt 155: .It Fl -version
156: Print version and exit.
1.1 benno 157: .El
158: .Pp
159: A remote
160: .Ar source
161: or
162: .Ar directory
1.16 schwarze 163: has the syntax
164: .Ar host : Ns Ar path
1.1 benno 165: for connecting via
166: .Xr ssh 1 ,
167: or
1.16 schwarze 168: .Cm rsync Ns :// Ns Ar host Ns / Ns Ar path
1.1 benno 169: or
1.16 schwarze 170: .Ar host Ns :: Ns Ar path
1.1 benno 171: for connecting to a remote daemon.
172: Subsequent to the first remote
173: .Ar source ,
174: the host may be dropped to become just
1.16 schwarze 175: .Pf : Ar path
1.1 benno 176: or
1.16 schwarze 177: .Pf :: Ar path .
1.1 benno 178: .Pp
179: For connecting to a remote daemon with
1.16 schwarze 180: .Cm rsync Ns :// Ns Ar host
1.1 benno 181: or
1.16 schwarze 182: .Ar host Ns :: Ns Ar path ,
1.1 benno 183: the first path component is interpreted as a
184: .Qq module :
1.16 schwarze 185: .Ar host Ns :: Ns Ar module Ns / Ns Ar path .
1.1 benno 186: This only applies to the first
187: .Ar source
188: invocation; subsequent to that, the module should not be specified.
189: .Pp
190: By default, new destination files and directories are given the current
191: time and the source file permissions.
192: Updated files retain their existing permissions.
193: It is an error if updated files have their file types change (e.g.,
194: updating a directory with a file).
195: .Pp
196: At this time,
197: .Ar source
198: may only consist of regular files, directories
199: .Pq only with Fl r ,
200: or symbolic links
201: .Pq only with Fl l .
202: The destination
203: .Ar directory
204: must be a directory and is created if not found.
205: .\" .Sh ENVIRONMENT
206: .\" .Sh FILES
1.16 schwarze 207: .Sh EXIT STATUS
208: The
209: .Nm
210: utility exits 0 on success, 1 if an error occurs, or 2 if the remote
211: protocol version is older than the local protocol version.
1.1 benno 212: .Sh EXAMPLES
213: All examples use
214: .Fl t
215: so that destination files inherit the source time.
216: If not changed, subsequent invocations of
217: .Nm
218: will then consider the file up to date and not transfer block hashes.
219: .Pp
220: To update the out-of-date remote files
221: .Pa host:dest/bar
222: and
223: .Pa host:dest/baz
224: with the local
225: .Pa ../src/bar
226: and
227: .Pa ../src/baz :
228: .Pp
229: .Dl % rsync -t ../src/bar ../src/baz host:dest
230: .Pp
231: To update the out-of-date local files
232: .Pa bar
233: and
234: .Pa baz
235: with the remote files
236: .Pa host:src/bar
237: and
238: .Pa host:src/baz :
239: .Pp
240: .Dl % rsync -t host:src/bar :src/baz \&.
241: .Pp
242: To update the out-of-date local files
243: .Pa ../dest/bar
244: and
245: .Pa ../dest/baz
246: with
247: .Pa bar
248: and
249: .Pa baz :
250: .Pp
251: .Dl % rsync -t bar baz ../dest
252: .\" .Sh DIAGNOSTICS
253: .Sh SEE ALSO
1.20 schwarze 254: .Xr ssh 1
1.16 schwarze 255: .Sh STANDARDS
256: .Nm
257: is compatible with rsync protocol version 27
258: as supported by the samba.org implementation of rsync.
259: .Sh HISTORY
260: The
261: .Nm
262: utility has been available since
263: .Ox 6.5 .
264: .Sh AUTHORS
265: The
266: .Nm
267: utility was written by
268: .An Kristaps Dzonsons Aq Mt kristaps@bsd.lv .
1.1 benno 269: .\" .Sh CAVEATS
270: .\" .Sh BUGS