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 GIMP. This contains the Gtk+ libraries. Of course, this is only important if you want to use the GUI.
5. Add the GIMP bin directory to the windows path. To do this, click on Start, right-click on My Computer, click on Properties, select the Advanced tab, and click on the Environment Variables button. Highlight Path in the System Variables section and click Edit. Add a semicolon to the end of the list followed by C:\Program Files\GIMP-2.0\bin. While we are here we also want to add the path for the PuTTY programs, which is C:\Program Files\PuTTY. For example, my list is as follows:

   %SystemRoot%\system32;%SystemRoot%;%SystemRoot%\System32\Wbem;C:\WINDOWS\system32\WindowsPowerShell\v1.0;C:\Program Files\GNU\GnuPG\pub;C:\Program Files\GIMP-2.0\bin;C:\Program Files\PuTTY

6. 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.
7. Edit the .prf file that was created in step 6. 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. Also add lines that read fastcheck = true and perms = 0 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 fastcheck = true perms = 0 #Optional list of subdirectories to sync path = Directory1 path = Directory2 path = Directory3

   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. Fastcheck = true tells Unison to use the modification time and length of a file as a ‘pseudo inode number,’ which significantly speeds up the scanning process. Note: on current versions of Unison, fastcheck is now the default in Windows. Perms = 0 tells the system not to synchronize permissions between Linux and Windows, because, after all, they use significantly different permission systems, and life is too short to try to make them always work together. You can use the path command to enumerate the subdirectories you wish to sync. If no path is specified, all subdirectories will be synced.

8. 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 exactly what it 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.

9. Run Unison. Everything should work! If it doesn’t, swiftly download and install the latest testing version of Debian. All your current problems will be completely obliterated and replaced by a new and more interesting (meaning more time consuming) set of problems. 😉

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 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.