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