Rsync Remote Arguments: Preserve Paths Across SSH

rsync is often the right tool for moving files over SSH, but a remote path crosses several parsers: the local shell, the rsync client, the remote shell used to start the server-side rsync process, and rsync’s own option and file-list protocol. Spaces and punctuation in a pathname can therefore fail in ways that look like an SSH authentication problem. Worse, a --delete mistake can remove data even when quoting is perfect.

Rsync’s argument handling has evolved. The upstream manual documents that newer rsync versions preserve remote arguments by default, beginning with version 3.2.4, while older behavior may depend on remote-shell splitting. Confirm both local and remote versions before designing around a specific mode. This guide focuses on SSH transport; rsync daemon modules use a different connection and authorization model.

Local quoting and remote argument handling are different layers

The local shell must first pass the remote specification as a single rsync argument. For a path containing spaces, this form is documented by rsync:

rsync -aiv -- 'host.example.net:a simple file.pdf' ./incoming/

The quotes here protect the argument from the local shell. They do not themselves quote the path for the remote shell. Rsync parses the host:path form, builds a file list, and coordinates with the remote rsync process. On current versions, protected/secluded argument handling transports those values through the rsync protocol rather than asking the remote shell to re-split every pathname. Do not add extra layers of single quotes around a path based on an old workaround without checking the current manual; with modern behavior, that can make literal quote characters part of the remote filename.

Always keep local path arguments quoted too:

source_dir='/srv/build output/release/'
destination='[email protected]:/srv/www/releases/current/'
rsync -a -- "$source_dir" "$destination"

The shell quotes preserve each local argument. The -- terminates options for rsync so a local pathname beginning with - is not parsed as a flag. Verify the syntax and option behavior supported by the installed rsync version, especially if the command runs on macOS or a minimal container with a different release than the deployment host.

Version compatibility is an endpoint property

Check rsync --version on the local host and the remote host. The remote version may differ from the client version because a login shell’s PATH, package set, or forced-command configuration selects a different binary. Do not infer remote capability solely from the local executable. A deployment script can print the version and protocol information into a redacted diagnostic log before transferring production data.

Newer rsync versions changed the default handling of remote arguments to preserve filenames with special characters. Older releases may require an explicit protected-argument option such as --protect-args / -s, while modern documentation uses the “secluded args” name and describes the protocol behavior. Compatibility switches such as --old-args intentionally restore legacy splitting semantics for scripts that depended on them; they should not be enabled casually. If older peers must be supported, test the exact client/remote pair and pass only documented options supported by both sides.

Do not write a homemade ssh host "rsync ... $path" wrapper around rsync to solve a space problem. That adds an extra remote shell parse and can execute shell syntax if the path contains metacharacters. Use rsync’s own remote-shell integration and argument handling. If a custom remote shell is required, configure it explicitly with -e or RSYNC_RSH, quote the local configuration value carefully, and verify the remote command with a safe test target.

SSH and rsync serve different layers. SSH authenticates and establishes a remote command channel; rsync negotiates its protocol and sends the file list and data. Host-key verification remains important, and a successful SSH login alone does not confirm that the remote rsync binary, destination permissions, or path semantics are correct. Use a restricted deployment account and a constrained authorized command when the server should permit only file transfer.

Distinguish SSH, daemon, and local transfer syntax

These forms have different meanings:

rsync -a ./tree/ host.example.net:/srv/archive/tree/
rsync -a ./tree/ host.example.net::module/tree/
rsync -a ./tree/ rsync://host.example.net/module/tree/

The first uses a remote shell, commonly SSH. The second uses rsync daemon syntax with a double colon. The third uses an rsync daemon URL. Daemon modules have their own module names, access rules, authentication settings, and path mapping; they do not imply an interactive shell account. Choose the transport that matches the security and operational policy rather than changing colon syntax until the error disappears.

Trailing slashes alter the source/destination layout. source/ copies the contents of the directory, while source typically creates the named directory beneath the destination. Test with --dry-run --itemize-changes and inspect the exact relative paths before any destructive synchronization. A trailing slash mistake can put data one level deeper or shallower than expected without producing a command failure.

Deletion and update flags need a separate review

--delete removes destination entries that do not exist in the source. It is not a quoting option and should not be added merely because a deployment wants “sync.” Confirm which side is sender, the source root, the destination root, and the effect of an empty or partially mounted source. A typo in the remote path can turn a cleanup into a broad deletion. Use a dry run first and consider --delete-delay if deletions should occur after updates, while remembering that it still deletes files.

--delay-updates places updated files into temporary locations and moves them into place near the end of the transfer. This can reduce the time a reader sees a mixture of old and new file contents, but it does not provide a transaction over the complete directory tree. Readers may still observe some files updated before others, and deletions are a separate concern. For an atomic release, transfer into a new versioned directory, verify it, then switch a symlink or other deployment pointer using a deliberate activation mechanism.

The --partial option can retain incomplete files after interrupted transfers. That can help resume large files, but those partial files should not be treated as valid artifacts by a reader. Keep staging directories separate from active content and validate checksums or signatures after transfer. Cleanup policy should not remove files that another active rsync process is using.

The archive option -a is shorthand for a set of recursion and metadata flags, not every preservation feature. It does not automatically mean ACLs, extended attributes, hard links, or every platform-specific metadata item are copied. Add -A, -X, or -H only when required and supported by both endpoints, and consider the privileges needed to preserve owners and groups. A successful copy with missing metadata can still be an incorrect deployment.

Build a safe, observable transfer wrapper

A deployment wrapper should validate paths, use a fixed host alias, start with a dry run, and make destructive behavior an explicit operator choice:

#!/bin/sh
set -u

source_dir=${1:?usage: publish-tree SOURCE DESTINATION}
destination=${2:?usage: publish-tree SOURCE DESTINATION}
case $source_dir in
  (/*) ;;
  (*) printf '%s\n' 'source must be an absolute path' >&2; exit 64 ;;
esac

rsync -aiv --dry-run -- "$source_dir" "$destination"

This is a preview, not the actual transfer. A production wrapper should separate preview and execution modes, print the selected endpoints and versions, and require a controlled approval before enabling --delete. Avoid taking free-form command options from an environment variable and expanding them unquoted; that turns configuration into accidental word splitting and option injection. Use a structured configuration format or explicit flags with validation.

For a real transfer, capture rsync’s status directly and preserve diagnostic output. Rsync’s exit code can identify partial transfer and protocol errors; do not discard it with || true or a pipeline into a logger. In Bash, pipefail can help for pipelines, but redirecting stderr to a log file and saving the command status explicitly is often clearer. Redact usernames, private hostnames, and credentials in shared CI logs as appropriate.

Use bandwidth limits and timeouts only after checking the version and protocol semantics. A timeout can interrupt a transfer after some destination files were updated. Treat a retry as reconciliation, not as proof that the previous attempt rolled back. Design the destination tree so an incomplete staging transfer cannot become the active release.

Remote pathnames still have edge cases

Filesystems permit names containing spaces, quotes, wildcard characters, leading hyphens, and newlines on common Unix systems. A shell loop over ls output is not a safe way to build a file list. Use rsync’s source-path handling, --files-from with a documented NUL-delimited format where supported, or another structured path-list mechanism that preserves every byte of the name. Confirm whether the option applies to local or remote path arguments in your version.

Symlinks also affect the transfer contract. Archive mode preserves symlinks by default rather than following their targets, while options such as --copy-links change that. A symlink in an upload tree can point outside the expected root, and a symlink on the destination can redirect writes depending on the options and receiver behavior. Decide whether to preserve, dereference, or reject links, and test them in a disposable tree.

The remote shell account’s startup files and forced commands can affect which rsync binary starts and what output is sent on the protocol channel. An unexpected banner or echo in a noninteractive startup file can corrupt a transfer. Keep interactive output out of remote noninteractive shell startup and use a dedicated account with a clean environment. Verify that the remote command does not rely on aliases or prompt initialization.

Validate outcomes and keep a rollback path

Before a large or destructive transfer, run a dry run and review itemized changes. Test a file with spaces, a leading hyphen, nested paths, a symlink, a deleted source, a network interruption, and a remote permission failure. Confirm that the destination and source roles are correct in both upload and download direction. Use disposable directories, not live production paths.

After transfer, verify the expected file inventory and checksums. Rsync’s --checksum can compare content but incurs additional I/O; size and modification-time quick checks are faster but are not a cryptographic integrity proof. For releases, generate a manifest, verify it at the destination, and only then activate the new directory. Keep the previous release until health checks pass and rollback is still possible.

When troubleshooting remote-argument errors, collect local and remote rsync versions, the exact redacted command shape, the remote shell, and the precise failing pathname class. Do not post access tokens, signed URLs, or private key paths into tickets. The robust fix is usually to align supported rsync behavior and preserve one pathname as data at every layer, not to add another set of quotes until one example happens to work.

Related:

Sources: