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