How to Install Unison on Ubuntu 18.04 Server

Unison is an open-source file-synchronization tool for OSX, Linux, Unix, and Windows. It allows two replicas of a collection of files and directories to be stored on different hosts (or different disks on the same host), modified separately, and then brought up to date by propagating the changes in each replica to the other.

This article will walk you through the steps to install and configure Unison on a pair of servers and use it to back up a directory. We will also configure Unison to use SSH as the secure communication protocol and create a cron job to periodically run Unison.

To begin this tutorial, you'll need two Ubuntu 18.04 servers, configured using the Basic Server Setup with Ubuntu 18.04 guide.

This lab guide will use two servers, one primary server that hosts the data that you will back up and another is backup server that will host the backed up data.

Create Additional Non-Root Users

First, on the primary server create a new user called primuser and make it sudoer using the following commands:

$ sudo adduser primuser
$ sudo usermod -aG sudo primuser

Finally, switch to the primuser account:

$ su - primuser

Now on backup server create a new user called bkpuser and make it sudoer using the following commands:

$ sudo adduser bkpuser
$ sudo usermod -aG sudo bkpuser

Finally, switch to the bkpuser account:

$ su - bkpuser

Install Unison on Both Servers

We will install unison on both servers using the following commands:

$ sudo apt-get update
$ sudo apt-get install unison

Configure SSH

Type the following command from the primuser home directory on the primary server to generate a SSH key pair:

$ ssh-keygen -t rsa -b 4096 -f .ssh/primuser

The above command creates the public and private SSH keys in the following two files:


The .ssh/primuser file contain the private SSH key and .ssh/ contain public key. You need to copy the contents of the public key file to the backup server. The easiest way to display the contents of the public key file for copying is to use the cat command to print the contents to the terminal:

$ cat .ssh/

On the backup server in the bkpuser home directory, open the .ssh/authorized_keys file with a text editor. Here, you will use nano:

$ nano .ssh/authorized_keys

Paste the public key into the editor, then save and exit.

You can now test that the SSH configuration is working by logging into the backup server from the primary server via SSH.

$ ssh -i .ssh/primuser bkpuser@backup_server_ip

Accept the fingerprint by pressing Y and then ENTER, and log in and out. You just needed to confirm that SSH works between the servers and save the backup server's SSH fingerprint.

Next, check that Unison will connect by running the following command from the primuser home directory on the primary server:

$ ssh -i .ssh/primuser unison -version

If everything is working you will see a response showing the version of Unison on the backup server:

unison version 2.48.3

Configure Unison

We need to create the configuration directory under the primauser's home directory on the primary server:

$ mkdir .unison

Open a new file with the name default.prf in a text editor in the .unison directory. This file contains the Unison configuration. Open the file with the following command:

$ nano .unison/default.prf

Then enter the following:

force = /home/primuser/data
sshargs = -i /home/primuser/.ssh/primuser

Back Up a Directory with Unison

Create a directory that will hold the data to back up by running the following command from the primuser home directory:

$ mkdir backup_data

Next, use the touch command to create three empty files:

touch backup_data/file{1..3}

Now that you have the data directory and some test files to back up, you can run Unison to back up the files to the backup server. The following command will do this:

$ unison -batch -auto /home/primuser/backup_data ssh://bkpuser@backup_server_ip//home/bkpuser/backup_data

This command will print a long message the first time that it is run. The message reads as follows:

Contacting server...
Connected [//primary_server_ip//home/primuser/backup_data -> //primary_server_ip//home/bkpuser/backup_data]
Looking for changes
Warning: No archive files were found for these roots, whose canonical names are:
This can happen either
because this is the first time you have synchronized these roots,
or because you have upgraded Unison to a new version with a different
archive format. 

Update detection may take a while on this run if the replicas are

Unison will assume that the 'last synchronized state' of both replicas
was completely empty.  This means that any files that are different
will be reported as conflicts, and any files that exist only on one
replica will be judged as new and propagated to the other replica.
If the two replicas are identical, then no changes will be reported.

If you see this message repeatedly, it may be because one of your machines
is getting its address from DHCP, which is causing its host name to change
between synchronizations.  See the documentation for the UNISONLOCALHOSTNAME
environment variable for advice on how to correct this.

Donations to the Unison project are gratefully accepted:

  Waiting for changes from server
Reconciling changes
dir      ---->            / 
Propagating updates
UNISON 2.48.3 started propagating changes at 12:52:43.70 on 10 Apr 2019
[BGN] Copying  from /home/primuser/backup_data to //backup_server_ip//home/bkpuser/backup_data
[END] Copying 
UNISON 2.48.3 finished propagating changes at 12:52:43.71 on 10 Apr 2019
Saving synchronizer state
Synchronization complete at 12:52:43  (1 item transferred, 0 skipped, 0 failed)

After each synchronization run the backup server will have an exact copy of the data directory on the primary server.

Warning: Any new files or changes in the data directory on the backup server will get lost when you run Unison.

Create a Unison Cron Job

Run the crontab command on the primary server with the -e flag to open it in edit mode:

$ crontab -e

Once you have the crontab open, add the following command to the first empty line under the existing text:

* */5 * * * /usr/bin/unison -log -logfile /var/log/unison.log -auto -batch -silent /home/primuser/backup_data ssh://bkpuser@backup_server_ip//home/bkpuser/backup_data

In this example, Unison is run every 5 hours. You can change this to any frequency that better meets your requirements.

Once you've made these changes, save and close the file.

Next, create the log file that Unison will write to on the primary server. The following command will create this file:

$ sudo touch /var/log/unison.log

Next, make the primuser the owner of the file.

$ sudo chown primuser /var/log/unison.log

You can check the status of the Unison backups by reading the log file at /var/log/unison.log. Unison will only log something when it has either backed up a new or updated file or if it encountered an error.

Wrapping up
In this tutorial, you installed and configured the Unison file synchronization software to back up a directory over SSH. You also configured cron to automatically run backups at a specified schedule.