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