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