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