How to Properly Use rsync with IPv6 Addresses Over SSH: Syntax and Escaping Techniques


3 views

When using rsync with IPv6 addresses via SSH, the primary syntax issue stems from how colons are interpreted in the destination specification. The standard rsync format:

rsync [options] source user@host:destination

becomes ambiguous when the host contains colons (like IPv6 addresses). Consider this failed example:

rsync -avz /local/path/ root@fdff::ffff:ffff:ffff:/remote/path

There are three reliable methods to handle IPv6 addresses in rsync commands:

Method 1: Square Brackets Encapsulation

The most elegant solution is wrapping the IPv6 address in square brackets:

rsync -avz /local/path/ root@[fdff::ffff:ffff:ffff]:/remote/path

Method 2: Using the rsync-specific Syntax

rsync provides an alternative syntax that avoids colon ambiguity:

rsync -avz /local/path/ rsync://root@fdff::ffff:ffff:ffff/remote/path

Method 3: SSH Config File Approach

For frequent use, configure SSH to handle the IPv6 address:

Host myserver
    HostName fdff::ffff:ffff:ffff
    User root

Then use the alias:

rsync -avz /local/path/ myserver:/remote/path

When dealing with complex scenarios:

Port Specification: Combine with -e flag for custom ports:

rsync -avz -e 'ssh -p 2222' /local/path/ root@[fdff::ffff:ffff:ffff]:/remote/path

Link-local Addresses: Don't forget the zone index:

rsync -avz /local/path/ root@[fe80::1%eth0]:/remote/path
  • Ensure IPv6 connectivity is properly configured
  • Verify SSH server listens on IPv6 (ss -tulnp | grep sshd)
  • Check firewall rules for IPv6 traffic
  • Test basic SSH connectivity first

IPv6 may introduce different routing behavior than IPv4. For large transfers:

rsync -avz --partial --progress --rsh="ssh -T -c aes128-ctr -o Compression=no -x" \
    /local/path/ root@[fdff::ffff:ffff:ffff]:/remote/path

This disables SSH compression (letting rsync handle it) and uses faster cipher options.

When using rsync with IPv6 addresses via SSH, the fundamental syntax conflict arises from the dual use of colons:

# Problematic format:
rsync -avz /local/path/ root@2001:db8::1:/remote/path/

This fails because rsync interprets the IPv6 address's colons as path separators.

The most reliable solution is to wrap the IPv6 address in square brackets:

# Correct escaping:
rsync -avz /local/path/ root@[2001:db8::1]:/remote/path/

For complex scenarios, consider these additional methods:

# Using SSH config aliases
Host v6server
    HostName 2001:db8::1
    User root

# Then simply use:
rsync -avz /local/path/ v6server:/remote/path/

When dealing with non-standard SSH ports:

rsync -avz -e 'ssh -p 2222' /local/path/ root@[2001:db8::1]:/remote/path/

For troubleshooting connection issues:

# Test SSH connectivity first
ssh -v root@[2001:db8::1]

# Verify rsync syntax
rsync --dry-run -avv root@[2001:db8::1]:/remote/path/ /tmp/test/

IPv6 connections may benefit from these rsync optimizations:

rsync -avz --compress-level=3 --partial --progress \
    /local/path/ root@[2001:db8::1]:/remote/path/

Always prefer SSH key authentication:

# Generate keys if needed
ssh-keygen -t ed25519

# Copy to IPv6 host
ssh-copy-id root@[2001:db8::1]