Unison

These instructions are for solving a specific problem: synchronizing data data between two Windows computers using SSH to access a central repository on a Linux (Debian Testing) server that is listening on a nonstandard port (in this example the port is 8000).  These instructions were inspired by instructions found on the official Unison Wiki.

These instructions assume that the SSH server is already setup and functioning correctly.  It also assumes that the Unison command line binary is installed on the server.  This is important because part of the syncing process launches Unison on the server to facilitate communication.  The following steps should be carried out on each of the Windows clients.

1. Download and install PuTTY.  You want the Windows installer with everything, of course.

2. Make a connection to the SSH server with PuTTY.  This lets you answer the question about accepting the server's key.

3. Download and unzip Unison.  You can put the .exe anywhere; I have mine on my desktop.  My Debian server currently runs version 2.13.  It is critical that the server and the client run the same version (at least the same major and minor numbers).  Otherwise they will simple refuse to communicate.  You probably want the GTK+ gui version.

4.  Download and install the GTK+ Runtime Environment.  Of course, this is only important if you want to use the gui.

5.  Run the Unison gui and create a new pair.  You'll notice that when you select SSH for the remote location the port section is ghosted.  But not to worry, we'll take care of that later.

6.  Edit the .prf file that was created in step 5.  You can find the file in C:\Documents and Settings\My User Name\.unison\.  Add a line at the bottom that reads sshcmd = ssh.bat.  A sample .prf file would look as follows:

root = C:\Documents and Settings\My User Name\sync
root = ssh://www.mydomain.com/sync
sshcmd = ssh.bat

Of course, you can substitute an IP address for the domain name.  Sshcmd tells Unison to run the following command to create the SSH connection.  This allows us to setup the custom port, which was the whole point of going through all this extra complexity.

7. Create a file called ssh.bat and place it in the same folder as the Unison binary.  The ssh.bat file should contain the following line, adjusted for your connection settings:

@plink.exe www.mydomain.com -ssh -P 8000 -l username -pw password "unison -server -auto"

The "@" is important.  I can verify that it doesn't work without it.  If it's removed, it appears that the last command is broken into several segments.  So just leave it in.  (Everyone agrees it is highly desirable, even if we don't know what it really does.)  Plink.exe is the command line binary that PuTTY uses for creating SSH connections.  -ssh tells PuTTY we want an SSH connection (it can do other types).  -P 8000 tells it we want port 8000.  Linux uses -p, Windows uses -P.  Go figure.  -l sets the username and -pw sets the password.  "Unison -server -auto" runs this command on the Linux server after connecting, which then talks to the local instance of Unison and makes all of that magic synchronization stuff happen.

8. Run Unison.  Everything should work!  If it doesn't, swiftly download and install the latest version of Kubuntu.  :)  All your problems will be solved.

Note:  I started getting really annoyed with how long it took to create the initial SSH connection to my server.  It seemed to me that it was caused by the server delay for entering the username and password.  A quick search of the internet revealed that adding the following two lines to the bottom of the /etc/ssh/sshd_config file fixes the problem:

UseDNS no
AddressFamily inet

"UseDNS no" disables DNS lookups by the SSH server.  They don't make a lot of sense anyway because it is quite unlikely that I'm connecting from a computer that has a DNS entry.  "AddressFamily inet" tells it that I only want to use IPv4.  Seeing as how it is very unlikely that everything in the food chain between my system and the server supports IPv6, this just speeds up the process of having the server figure that out.