Introduction

When managing multiple computers or virtualized environments, it is often necessary to synchronize files or keep data accessible regardless of the system you are using. Protocols like SMB, NFS, FTP, or SSHFS facilitate file sharing, but their initial setup can be complex. In these cases, tools like rsync, scp, or Unison offer fast, automated, and easy-to-maintain synchronization.

What is Unison?

Unison is a file-synchronization tool similar to rsync, designed specifically for bidirectional synchronization of file replicas across different computers or operating systems. It allows two replicas of a collection of files and directories to be updated stored on different hosts (or different disks on the same host) independently, and then brought up to date by propagating the changes in each replica to the other.

While this article focuses on configuring Unison between two Linux machines, it can also synchronize data across different operating systems or local directories.

Example setup scenario

The synchronization will be performed securely over SSH. At least one host must run an SSH server, while the second machine acts as the SSH client.

NOTE: Although Unison supports a native socket protocol, using SSH avoids opening additional network ports and provides secure, encrypted transmission.

Our target scenario includes:

  1. One machine acts as the primary server, while client machines initiate synchronization tasks.
  2. Unattended synchronization runs automatically at scheduled intervals using passwordless SSH certificates and a cron job.
  3. Unison operates in batch mode (-auto -batch), automatically accepting default resolution rules for non-conflicting changes.

Prerequisites:

  1. Two machines with identical versions of Unison installed.
  2. An SSH server running on the destination machine.

NOTE: If Unison binary versions or OCaml compiler versions differ significantly between distributions, build Unison from source on both hosts.

SSH key setup

For automated background jobs, configure key-based SSH authentication:

  • Generate an SSH key pair on the client machine:
$ ssh-keygen -t ed25519 -b 4096 -C "unison synchronization key" -f $HOME/.ssh/unison_work
  • Copy the public key to the destination server using ssh-copy-id:
$ ssh-copy-id -i $HOME/.ssh/unison_work.pub {user}@{server_FQDN_or_IP}
  • Add the private key to the client's SSH agent:
$ ssh-add $HOME/.ssh/unison_work
  • Verify passwordless SSH login from client to server:
$ ssh -i $HOME/.ssh/unison_work {user}@{server_FQDN_or_IP}

Unison profile configuration

Unison uses profile files (.prf) to define synchronization targets and rules.

  • Create a profile file on the client at $HOME/.unison/Documents.prf.
  • Ensure the destination directory exists on both hosts.
  • Add the following configuration to Documents.prf:
# Unison preferences
label = Common documents
root = /home/{user}/Documents
root = ssh://{user}@{server_FQDN_or_IP}//home/{user}/Documents
sshargs = -i /home/{user}/.ssh/unison_work -C
  • Test the profile manually from the command line:
$ unison Documents -auto -batch
  • Verify that files inside Documents are synchronized bidirectionally.

Cron automation

To schedule unattended background synchronization (e.g. hourly), add a cron entry on the client using crontab -e:

0 * * * * unison Documents -auto -batch > /dev/null 2>&1

With this entry in place, cron will invoke Unison every hour to maintain synchronized file replicas automatically.