Remote Backup

The Department recommends unison to backup files on home/laptop machines. Unison file synchronization provides:
  1. Universal access to the same set of files by maintainingg replicas on each machine where those files are needed
  2. Confidence that changes to files on any machine will be correctly merged with the other replicas
  3. Efficient backup of files on home/laptop machines by keeping a replica on the file server

About Unison

Unison, created by Bejamin Pierce at UPenn, is a cross-platform file synchronization tool. It can provide secure, bi-directional, and efficient replication of files between machines. In the Department's configuration, unison is run from a client (usually a laptop or a home machine), which establishes an SSH connection to a Linux machine in the Department. A local instance of unison is then spawned on that Departmental Linux machine. Each instance analyzes its specified local file tree and then negotiates with the other instance to see which files are different. Then the minimum amount of data is compressed and transmitted over the secure SSH tunnel in order to synchronize the two file trees.

For more information and to download the latest binaries, see the unison website

Using GUI Unison on Windows

Unison requires a compatible command-line ssh program to make the SSH connection to the Department. A good choice is Cygwin, which includes Open-SSH. Unison also requires that the location of the ssh tool be in Windows' PATH Environment Variable, which can be set on the Advanced tab of the System control panel. For Cygwin, the path to add is C:\cygwin\bin. Ensure that ssh is working correctly by running ssh from a command shell before using Unison. See the ssh web page for instructions on setting up ssh in the Department.

After downloading the graphical unison from the website above, double click it to run the program. The first screen will ask you to specify the local file tree that you want to synchronize. You will most likely want to choose something like

C:\Documents and Settings\username\My Documents
The next screen configures the connection to the remote host. Select the SSH button, enter as the host's name, enter your user name to login with ssh, and then enter the remote path you want to synchronize with. This will probably be something like
/u/username/My Documents/
Unison will then analyze files on each machine and determine which files need to be updated. Click Go to synchronize the files. Restart will re-examine the files on each machine. Files that are changed on both file trees will display a ?. The Action menu has options to resolve those conflicts.

Using Command Line Unison

This text will describe a quick way to start and automate the command line version of unison. The website mentioned above and running unison -help have more in-depth instructions.

Both the command-line and GUI versions of unison use preferences files to save connection and synchronization settings. If you followed the GUI instructions above, you will already have a preferences file called default.prf. In Windows, it will be located in C:\Documents and Settings\username\.unison\. On Linux, it is inside .unison in your home directory.

If you don't already have a preferences file, create a text file called default.prf in the directory mentioned above with the following text in it (replace username with your user name and modify the paths as you wish):

root = C:\Documents and Settings\username\My Documents
root = ssh://<username>/<tierfs dir="">/My Documents/
When you run unison, it will connect with those settings. .prf files can be much more intricate, directing files to ignore, paths to explicitly include, etc. See the Unison Documentation.

-times Options for Command Line and GUI

The first time unison does a file synchronization to the server, it uses the current date and time the synchronization occurs as it creates the files on the server side. In order to keep the correct date and time, the -times options should be used when running the unison program.

Using Unison to Backup a Home Machine or Laptop

Putting unison -silent in a cron job or a Windows Scheduled Task (in Control Panel) will automatically synchronise your files. This is useful for scheduling backups of a home or laptop machine to a file server, as Unison ensures that data is only uploaded when files change.

If you intend to backup a large amount of data, please synchronize your files onto the appropriate Tiered Filesystem.


Unison maintains a database cache on each machine in order to speed up analysis of the file trees. Unison may, at some point, complain that the caches are out of sync. Deleting the cache files on both the client and the remote host should fix the problem. Under Windows, they are located in C:\Documents and Settings\username\.unison\. On Linux, they are inside .unison in your home directory. Database files are named ar followed by a string of random characters.

The caches only work when synchronizing between the same pair of machines. As a result, it is required that the same target machine be specified when ssh'ing to the gateway, or the above problem will occur. See this page for more information.