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