OPENRSYNC(1)

📦
version 2025-01 · 2 versions
, in nixos 26.05

💖 OPENRSYNC(1) 💖

okay so this is openrsync, from the General Commands Manual bestie, and we're about to synchronise local and remote files like it's nothing ✨

🌸 NAME 🌸

openrsync — synchronise local and remote files 🦋

🎀 SYNOPSIS 🎀

openrsync [-aDgIJlnOoprtVvx] [-e program] [--address=sourceaddr]
          [--compare-dest=directory] [--contimeout=seconds] [--del]
          [--exclude pattern] [--exclude-from=file] [--include pattern]
          [--include-from=file] [--max-size=size] [--min-size=size]
          [--no-motd] [--numeric-ids] [--port=service]
          [--rsync-path=program] [--size-only] [--timeout=seconds]
          source ... directory

✨ DESCRIPTION ✨

so the way this works 💅 — openrsync makes the files in the destination directory match up with one or more source files. The glow-up, basically.

Either the source or the destination directory may be remote, but not both. That's the rule, no cap 🙅

The arguments are as follows:

🌈 OPTIONS 🌈

  • -a, --archive — the iconic shorthand, literally just -Dgloprt bundled up 🎀
  • --address=sourceaddr — when you're connecting to an rsync daemon, use sourceaddr as the source address for the connections. Super handy on machines with multiple interfaces, iykyk 🦋
  • --compare-dest=directory — use directory as an alternate base directory to compare files against, on the destination machine. If a file in directory is found and it's identical to the sender's file, the file just won't be transferred — saving you that bandwidth, periodt. Multiple --compare-dest directories may be provided. If directory is a relative path, it's relative to the destination directory. 🫶
  • --contimeout=seconds — set the connection timeout, in seconds. Exit if no connection gets established within the specified time. The default is 0, which means no timeout at all ⏳
  • -D — also transfer device and special files. Shorthand for --devices --specials 👑
  • --del, --delete — delete files in directory that aren't found in the source directories. Only applicable with -r ⚠️ (yes, it deletes. be so for real before you run it 💀)
  • -e program, --rsh=program — specify an alternative communication program. Defaults to ssh(1) 🔐
  • --exclude pattern — exclude files matching pattern 🙈
  • --exclude-from=file — load patterns and rules from file 🍓
  • --devices — also transfer device files 🧚
  • -g, --group — set the group name to match the source. Example time bestie: group "kristaps" with ID 1000 on a remote server gets matched to group "kristaps" on the local machine with ID 2000. But if --numeric-ids is also given, or if the remote group name is unknown on the local machine, set the numeric group ID to match the source instead 💖
  • -I, --ignore-times — do not skip based on file size and modification time 👀
  • --include pattern — include files matching pattern ⭐
  • --include-from=file — load patterns and rules from file 🌸
  • -J, --omit-link-times — don't set symlink modification times to match the source 🦋
  • -l, --links — also transfer symbolic links. The link is transferred as a standalone file: if the destination doesn't exist, it will be broken 😭 (we love a standalone queen but she's fragile)
  • --max-size size — don't transfer any file larger than size bytes. Alternatively, size may instead use a multiplier, as documented in scan_scaled(3), to specify the size 📏
  • --min-size size — don't transfer any file smaller than size bytes. See --max-size for the definition of size 📐
  • -n, --dry-run — do not actually modify the destination. Mainly useful in combination with -v 🔍 (vibe check first, always)
  • --no-motd — do not display the Message of the Day 🙅‍♀️
  • --numeric-ids — ignore user and group names, use numeric user and group IDs only. Has no effect unless -g or -o is also given. ⚠️
  • -O, --omit-dir-times — don't set directory modification times to match the source 🎀
  • -o, --owner — set the user name to match the source, with similar matching logic as for -g. If --numeric-ids is also given, or if the remote user name is unknown on the local machine, set the numeric user ID to match the source instead. Only works if run as root 👑🔥
  • -p, --perms — set destination file or directory permissions to match the source when it's updated 🛡️
  • --port=service — specify an alternative TCP port number. The service can be given as a decimal integer or as a name to be looked up in the services(5) database. The default is "rsync" 🔌
  • -r, --recursive — if source designates a directory, synchronise the directory and the entire subtree connected at that point. If source ends with a slash, only the subtree is synchronised, not the source directory itself. If source is a file, this has no effect 🌳 (the slash matters, bestie, don't play with it)
  • --rsync-path=program — run program on the remote host instead of the default rsync 🚀
  • --size-only — skip files based only on size, don't check timestamp ⏱️
  • --specials — also transfer fifo and unix domain socket files 🧚‍♀️
  • --timeout=seconds — set the I/O timeout in seconds. Exit if no data was transferred for the specified time. The default is 0, which means no timeout 💤
  • -t, --times — set destination file and directory modification time to match the source when it's updated or created 🕰️
  • -V, --version — print version and exit 👋
  • -v, --verbose — increase verbosity. Specify once for files being transferred, twice for specific status, thrice for per-file transfer information, and four times for per-file breakdowns 🗣️🗣️🗣️🗣️
  • -x — do not cross filesystem boundaries. If this option is repeated, all mount point directories from the copy are omitted. Otherwise, it includes an empty directory at each mount point it encounters 🚧

okay now the ✨lore✨ about remote paths, because this is where people get confused:

A remote source or directory has the syntax host:path for connecting via ssh(1), or rsync://host/path or host::path for connecting to a remote daemon. Subsequent to the first remote source, the host may be dropped to become just :path or ::path 🌐

For connecting to a remote daemon with rsync://host or host::path, the first path component is interpreted as a "module": host::module/path. This only applies to the first source invocation; subsequent to that, the module should not be specified ⚠️

By default, new destination files and directories are given the current time and the source file permissions. Updated files retain their existing permissions. It is an error if updated files have their file types change (e.g., updating a directory with a file) 💀

At this time, source may only consist of regular files, directories (only with -r), or symbolic links (only with -l). The destination directory must be a directory and is created if not found 🫶

🔥 EXIT STATUS 🔥

  • 0 — success, slay 💅
  • 1 — an error occurred 😭
  • 2 — the remote protocol version is older than the local protocol version 💀

🌈 EXAMPLES 🌈

A common invocation of openrsync is for archiving from a remote host to the local computer:

% openrsync -av --delete remote:rpath /local/path

This will update the contents of /local/path/rpath with those on the remote server. Switching remote and local will update the remote contents instead:

% openrsync -av --delete /local/path remote:rpath
ngl all examples use -t so that destination files inherit the source time. If not changed, subsequent invocations of openrsync will then consider the file up to date and not transfer block hashes ✨

To update the out-of-date remote files host:dest/bar and host:dest/baz with the local ../src/bar and ../src/baz:

% openrsync -t ../src/bar ../src/baz host:dest

To update the out-of-date local files bar and baz with the remote files host:src/bar and host:src/baz:

% openrsync -t host:src/bar :src/baz .

To update the out-of-date local files ../dest/bar and ../dest/baz with bar and baz:

% openrsync -t bar baz ../dest

To update the out-of-date remote files in host:dest on a remote host running openrsync with the local host running rsync(1):

% rsync --rsync-path openrsync -t ../dest/* host:dest

👀 SEE ALSO 👀

ssh(1)

📜 STANDARDS 📜

openrsync is compatible with rsync protocol version 27 as supported by the samba.org implementation of rsync 🤝

🦋 HISTORY 🦋

The openrsync utility has been available since OpenBSD 6.5 🎀

👑 AUTHORS 👑

The openrsync utility was written by Kristaps Dzonsons <kristaps@bsd.lv> 💖

and that's the whole page bestie!! this one came from Debian, dated $Mdocdate$, and it's OPENRSYNC(1) all the way down 🫶✨ go forth and synchronise responsibly, mwah 💅

📦 where this page comes from