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