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