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