Unison Bidirectional File Synchronization Tool For Unix, Windows, and Mac OS X

Unison Introduction

Unison is a an Open Source bidirectional file-synchronization tool for Linux, Windows, and Mac OS X. It allows for two replicas of a collection of files and directories to be stored on different hosts; They can be modified separately, and then each can be brought up to date by propagating the changes in each replica to the other. I sync everything from my source. But Unison literally keeps track of what has changed on both sides, and recommends updates to you to keep them both synchronized.

I like the way Unison works. It doesn't change anything on either side until it shows you exactly what it is going to do. It recommends what changes should take place, and you can just press return to accept the changes or you can press another key to change how the synchronization works. It is an easy user interface to work with once you come to an understanding of what it is doing. After Unison asks you what it needs to know, it then prompts you to make all the sync changes, and upon getting a y for yes it applies the changes. Ultimately, you choose which way the update goes, whether from your local machine to the remote or from the remote to your local workstation.

The Unison man page says it's a file-synchronization tool for Unix and Windows. That's not exactly true since I have it working on my Mac OS X Leopard 10.5 I am going to explain here how I got it working on my Mac. I'm sure you can use these instructions and the associated URLs to get it working on any platform.

Installing Unison On the Mac

Step One: Install Apple XCode Tools

To get Unison working on the mac, first you need to download the Apple XCode Tools I installed XCode v3.0 and that worked for me on Mac OS X 10.5. You will have to register with Apple Developer Connection as a free ADC Online Member. After you sign up and login to Apple Developer Connection, click on Download and then Developer Tools scroll down until you see Xcode 3.0. Download the 1.1gb disk image and associated PDF document. Install Xcode software on your computer.

Step Two: Install FInk Project

I recommend the Fink Project over DarwinPorts or MacPorts since it is more comprehensive than the Fink Project and you end up with the Gnome GUI and programs getting installed that use the Gnome GUI.

If you still choose DarwinPorts (also known as MacPorts) you can download and install DarwinPorts 1.5. After you install DarwinPorts open up a command shell and run this command:

• sudo /opt/local/bin/port -d selfupdate which ensures that you have the latest version of the software installed on your Mac.

Step Three: Install Unison On The Mac

• MacPorts: These instructions will download and automatically build unison-2.13.16 on your Mac with the same version on Ubuntu. Unison requires the same version on each side to work at all: sudo /opt/local/bin/port install unison
• Fink: sudo fink install unison

Step Four: Setup SSH Connection Between the Two machines To Sync

You can setup a Secure Shell (SSH) connection between the two computers that Unison will use to transfer the data over. Get the details of how to Setup SSH on Mac OS X from Apple Developer Connection Generally here are the steps:

• Generate your SSH Keys which are stored in home/.ssh directory. Don't put a password on the public key so it can automatically log into the other system and run the unison commands.
• Transfer a copy of your public key (id_dsa.pub) over to the target computer under home/.ssh/authorized_keys2 and make sure it's read only by the owner.
• Make sure the Secure Shell Daemon (SSHD) is running on the remote computer, and then test the connection: From your local computer you should be able to do remote commands automatically now: ssh remote-computer "uname -a"
• If your remote system is Ubuntu Linux, to get SSH up and running you just do:
  • sudo apt-get install ssh
  • sudo /etc/init.d/ssh start

Step Five: Get the two sets of files fairly close in sync

• Make sure you have good backups on both sets of files. I just ran the tar command to backup everything and store it outside of the directory tree you are attempting to sync. That way if you wipe everything out, you can recover You have to realize that to "sync" means the potential to delete files and we have to ensure it's deleting the right files Unison won't haul off and delete all your files. I'm just paranoid. And that's a good thing.
• I'm sure you can give unison a sync command to copy all of the files from one side to the other, but if you don't have any files on one side, I would issue an rsync command to copy them over:
  • Change directory to your home folder (if that's what you are syncing)
  • rsync -avuzb Documents remote-linux:"/home/jeffrey" that copies the Documents folder from my local Mac to my Linux home directory /home/jeffrey/Documents. It's a one-way copy, and will only copy files that don't exist. This in itself is a great way to do backups if that's all you need. You could run it several times a day via a cron job on your Linux system (where it copies files the other way; You would probably want it to test to see if the laptop exists on the network first; Sounds like a future shell script I'll be writing ).
  • Now that the two sides are relatively in sync, Unison will keep them that way. You will need to run Unison periodically by hand, since you have to make decisions as to what direction the files are updated (unless you can instruct Unison to always send updates from the last updated changed file (since the last update) to the other system which I think is reasonable, but I haven't seen any automated option like this... let me know if you find this; then you wouldn't have to deal with any user interface and could automate the process more which I like).

Step Six: Verify that Unison Is Working

Pick a small directory on your home directory and issue a Unison sync command:

• unison Documents ssh://myLinux//home/jeffrey/Documents
• Unison will examine the files on the server and compare them to your local computer, it may take a few minutes.
• It will prompt you to make decisions about files that need to be synchronized. Refer to the Unison User Manual on how to answer these questions (they are pretty intuitive I think).

Step Seven: Setup the Unison Profile

The Unison Profile tells Unison how it will sync. I am syncing the files from my Mac to my Linux workstation. The filename of the profile you create is what you will give to the unison command: unison mac2linux I stored the Unison Profile at /Users/jeffrey/Library/Application Support/Unison/mac2linux:

# sample command-line: unison Documents ssh://myLinux//home/jeffrey/Documents
# compare the folders
root = /Users/jeffrey 
root = ssh://myLinux//home/jeffrey
path = Documents 
path = Pictures 
path = Movies
path = Music 
path = Desktop

Step Eight: Run the Unison Bidirectional File Sync

unison mac2linux If you installed Fink Project, you work through a nice Gnome GUI.

Step Nine: Refer to the Unison User Manual and Reference Guide

The Unison User Manual and Reference Guide is well done and will provide you a lot of additional helpful information. You should read through that as well. And if you learn other great stuff to do, make sure and put some pointers back on this page!!

References

• Unison Home Page
• Unison User Manual and Reference Guide
• DarwinPorts Home Page
• DariwnPorts Readme
• MacPorts User Guide
• How To Setup SSH on Mac OS X
• Rsync Home Page

-- JeffreyThompson - 26 Dec 2007