• View
• Edit
• History
• Print

Using Unison on Specific Operating Systems

Generic Unix
Mac OS X
Windows
Help Requests

---

Generic Unix Questions

Is it OK to mount my remote filesystem using NFS and run unison locally, or should I run a remote server process?

NFS-mounting the replicas is fine, as long as the local network is fast enough. Unison needs to read a lot of files (in particular, it needs to check the last-modified time of every file in the repository every time it runs), so if the link bandwidth is low then running a remote server is much better.

I've heard that the Unix file locking mechanism doesn't work very well under NFS. Is this a problem for Unison?

No.

What will happen if I try to synchronize a special file (e.g., something in /dev, /proc, etc.)?

Unison will refuse to synchronize such files. It only understands ordinary files, directories, and symlinks.

Is it possible to run Unison from inetd (the Unix internet services daemon)?

Toby Johnson has contributed a detailed chroot min-HOWTO describing how to do this. (Yan Seiner wrote an earlier howto, on which Toby's is based.)

Why does synchronization always fail with Uncaught exception Failure("input_value: integer too large")?

This is because of an incompatibilitly in an underlying programming layer and shows up when you're synchronizing between 32 and 64 bit systems.

A workaround is the following one: on the 32 bit system nothing changes, but on the 64 bit system you don't use a native 64 bit version of unison, but a 32 bit one that is run in the 32 bit compatibility mode.

There are two possibilities to achieve that: a) there may be a way to run a usual dynamically linked 32 bit binary with a 32 bit compatible runtime environment or b) you use a statically linked 32 bit binary that doesn't depend on such a runtime environment.

To get a statically linked 32 bit binary there are in turn again two possibilities: a) you compile it statically (or have someone else do that and just download it) or b) you use a tool like the ELF statifier (http://statifier.sourceforge.net/) or Ermine (http://www.magicErmine.com) on a dynamically linked binary to convert it into a statically linked one.

---

OS X

Does Unison work on Mac OSX?

Recent versions of Unison work well on OS X, including support for synchronizing files with resource forks, handling of creator strings, etc. Both the text-mode interface and a native OSX graphical user interface are available. (Thanks in particular to Ben Willmore for huge improvements to the latter!)

A couple of caveats:

• Trying to sync resource forks is probably not worth the time and trouble for most users, so to tell unison to ignore resource forks, include this line in the profile:

        rsrc = false 

• Unison will be confused by some files that are frequently updated by OSX, and will report lots of errors of the form "XXX has been modified during synchronization." These files --- in particular, files with names like .FBCLockFolder and .FBCIndex --- should be ignored by adding these lines to your profile:

        ignore = Name .FBCIndex
        ignore = Name .FBCLockFolder

• Some more items you may want to ignore (The wiki may wrap big lines below, so unwrap so everything after "ignore = " is on just one line):

        ignore = Name {Cache*,.Trash*,.VolumeIcon.icns,.HSicon,Temporary*,.Temporary*,TheFindByContentFolder}
        ignore = Name {TheVolumeSettingsFolder,.Metadata,.filler,.idsff,.Spotlight,.DS_Store,.CFUserTextEncoding} 

• Spotlight (10.4+) and TimeMachine (10.5+) running in background can slow down your mac, and you may want to temporarily disable them during a big sync. Also, it may be possible to tell spotlight never to index a folder by making the name end in ".noindex" For example, you could create in /Users/Shared/ a folder named Downloads.noindex and tell Firefox to store downloads there.
• Unison does not run on Mac OS 9 or earlier.

Can Unison synchronize an OS X machine with a Unix machine?

Yes, but new OS X users may be confused by restrictions on file names: although OS X respects case in file names, two files whose names differ only in case may not coexist on the same file system. If such files exist on the Unix side, Unison will report the error but not identify the offending files. Unix users can identify such files with the aid of a script like this:

Installing Unison from Fink (on OS X) does not work.

We've had reports that fink installation only works when the unstable packages are selected. See here for more information.

How do I install a Terminal-only Unison using Mac Ports?

Mac Geekery has a short tutorial describing how to do it.

How do I install a Terminal-only Unison using Homebrew?

        brew install unison

How do I build a GUI version of Unison for OS X?

As described in the Unison manual, there are two Mac GUIs: UISTYLE=macnew and UISTYLE=macnew09. Unfortunately, neither will build out of the box under OS X 10.8, Mountain Lion (and possibly under earlier OS X versions as well). The macnew09 GUI uses the BWToolkit plugin for Interface Builder; unfortunately, Xcode 4 currently does not support .ibplugin files. Both GUIs target OS X 10.5, which is no longer supported as a build target by Xcode 4. The macnew GUI could probably be revived without too much work, but you'll need to check it out yourself.

How do I pass environment variables to the Aqua version of Unison?

Create a file .MacOSX/environment.plist in your home directory containing:

You can easily set the value of UNISONLOCALHOSTNAME in .MacOSX/environment.plist to the current hostname with the following command:

For more information about this file, see here.

How do I synchronize Spotlight comments using Unison?

Spotlight comments of a file "foo" are stored in the .DS_Store file of the directory containing "foo". In order to synchronize them, Unison should first not ignore .DS_Store files, and second import the Spotlight information for files in a directory whose .DS_Store has been modified. (In many cases if the file "foo" is modified as well, it will trigger an automatic import, but it may happen that only comments are changed, in this case the file is not modified and upon synchronization automatic Spotlight update will not occur.)

In order to do a Spotlight import of files in directories whose .DS_Store has been modified, one may use the following script daily (it searches for modified .DS_Store during the last day).

I installed the command line version of Unison using the "Install command-line tool" menu option, but the wrong version of Unison is being launched.

The command-line tool is a very small executable that searches for an existing Unison binary to launch it. If several versions of Unison are present, one cannot predict which one will be launched. It is thus recommended to have only one version of the Unison OS X binary.

To find where Unison binaries are installed, you can run the following command

---

Windows

How do I install under windows? I install GTK and try to run unison and I get "This application has failed to start because libgtk-win32-2.0-0.dll was not found. Re-installing the application may fix this problem."

The answer is to download the dependencies and include the gtk bin directory in your path. You can do this temporarily in the command-line by typing this:

set path=;c:\program files\common files\gtk\2.0\bin

or you can do it permanently by right-clicking on your "my computer" and clicking on properties, going to the "environment variables" button, choosing "path" and adding ";c:\program files\common files\gtk\2.0\bin" (no quotes) to the end of that value.

If the libraries are not on your system, you can install them from http://gtk-win.sourceforge.net/home/index.php/Main/Downloads. Also check the GTK website http://www.gtk.org/ to ensure you have all the dependent packages. Install the GTK package and merge the files of the other packages into similarly named directories of the GTK package install.

Unison creates two different windows, the main user interface and a blank console window. Is there any way to get rid of the second one?

The extra console window is there for ssh to use to get your password. Unfortunately, in the present version of unison the window will appear whether you're using ssh or not. Karl Moerder contributed some scripts that he uses to make the command window a bit more attractive. He starts unison from a shortcut to a .cmd file. This lets him control the attributes of the command window, making it small and gray and centering the passphrase request. His scripts can be found here.

It is also possible to get rid of the window entirely (for users that only want socket mode connections) by playing games with icons. If you make a symbolic link to the executable, you can edit the properties box to make this window come up iconic. That way when you click on the link, you seem to just get a unison window (except on the task bar, where the text window shows).

Or use this Autohotkey script:

#SingleInstance ignore
#NoTrayIcon
DetectHiddenWindows, On
Run, unison-gtk.exe, , Hide, OutputVarPID
WinWait, ahk_pid %OutputVarPID% ahk_class gdkWindowToplevel, , 10
if(ErrorLevel == 1) {
    MsgBox, The window does not exist.
}
WinShow, ahk_pid %OutputVarPID% ahk_class gdkWindowToplevel

It looks like the root preferences are specified using backslashes, but path and ignore preferences are specified with forward slashes. What's up with that?

Unison uses two sorts of paths: native filesystem paths, which use the syntax of the host filesystem, and "portable" paths relative to the roots of the replicas, which always use / to separate the path components. Roots are native filesystem paths; the others are root-relative.

I'm having trouble getting unison working with openssh under Windows. Any suggestions?

Antony Courtney contributed the following comment:

I ran in to some difficulties trying to use this ssh client with Unison, and tracked down at least one of the problems. I thought I'd share my experiences, and provide a 'known good' solution for other users who might want to use this Windows / Unison / ssh / Cygwin combination. If you launch Unison from bash, it fails (at least for me). Running unison_win32-gtkui.exe, I get a dialog box that reads:

and a message is printed to stderr in the bash window that reads:

My guess is that this is caused by some incompatibility between the Ocaml Win32 library routines and Cygwin with regard to setting up argv[] for child processes.

The solution is to launch Unison from a DOS command prompt instead; or see section X.

How can I get Unison to talk through a Putty link on Windows?

Martin Cleaver has written up a set of instructions here.

I'm using Windows XP + Cygwin. Unison stops responding after I enter my ssh password. What can I do to fix it?

This appears to be a problem with the Cygwin DLL version 1.5.11, perhaps in conflict with Win XP. Downgrading to DLL version 1.5.10-3 usually solves the problem.

To downgrade using the Cygwin setup program, run Cygwin's setup.exe, chose the "Base" tree of packages and toggle the "cygwin: the UNIX emulation engine" package until it is set to install v1.5.10-3.

Thanks to Michael McDougall for this answer.

(Uh oh... Michael writes, later: Actually, I've been communicating with one of the people afflicted with this bug and I think my solution is out of date. It looks like the new Cygwin DLL still has the bug, but the Cygwin setup program only lets you downgrade one version--now you can choose between 1.5.11 and 1.5.12, both of which break Unison.)

Karl Crary has a different workaround for this problem, using socket connections and port forwarding. The key idea is to create a script looking like this:

Is there a way, under Windows, to click-start Unison and make it synchronize according to a particular profile?

Greg Sullivan sent us the following useful trick:

In order to make syncing a particular profile "clickable" from the Win98 desktop, when the profile uses ssh, you need to create a .bat file that contains nothing but "unison profile-name" (assuming unison.exe is in the PATH). I first tried the obvious strategy of creating a shortcut on the desktop with the actual command line "unison profile-name", but that hangs. The .bat file trick works, though, because it runs command.com and then invokes the .bat file.

Brian Mork (increa.com) created unison profiles and the syntax for a desktop shortcut. The result is a single-click Unison icon synchronization on the desktop that you can click and walk away. Synchronization happens through an SSH link from Windows XP to Max OS 10.6 (or Windows XP to whatever other computer you have).

FAT32 file name length problems

Implementations of the FAT32 filesystem may have limitations not only on the lengths of individual file names, but also the length of full path names of the file (160 characters, I think?). When Unison is in the process of syncing, it performs its work in a new subdirectory, increasing the total path name length of your files. If your files are already pushing the limits of FAT32, your unison operation may abort. Giving your files or directories shorter names may help to avoid this problem.

FAT32 time stamps

File modification times are rounded to the nearest two-seconds on FAT32, but not on NTFS. So syncing between NTFS and FAT32 while preserving modification times may result in the file properties of all your files being updated on every synchronization. This may be corrected in a future update of unison by ignoring such 1-second differences.

Using UNISON between two Windows machines on a vpn

This is very similar to the instructions referenced elsewhere on this page by Martin Cleaver (see: How can I get Unison to talk through a Putty link on Windows?). The main differences are: 1) I used freeSSHd for the ssh server; and, 2) operating on a vpn allows the luxury of dispensing with public/private keys and instead using just username/password for authentication. Another layer of encryption doesn't add anything of value.

On the computer that will function as the server:

1) download and install freeSSHd; if given the option, tell it to run as a service so that it will autoload each reboot (if you are using a utility like WinPatrol make sure that you allow the service to be installed)

2) add an environment variable named HOME if one doesn't already exist and point it to a directory that you might want to use someday as the root path when doing relative addressing. Do this even if you do not intend to use relative addressing as this environment variable must exist.

3) configure freeSSHd by clicking the icon in the systray and, at a minimum, confirm the port to use (22 is default), set up at least one username and password, and establish any ip address restrictions under Host restrictions that make sense for your use.

4) ensure that your router, if you are using one, will pass port 22 through to the server.

5) ensure that your firewall will allow port 22 and, to the extent it is program based rather than port based, will allow freeSSHd to communicate with the outside world.

6) copy the windows text-based executable to a place where it can be run. TIP: shorten and change the name so that it is easier to deal with. I use unisont.exe which is a lot easier to work with than unison-2.13.16-win-text.exe.

7) verify that unison will run on your system by opening a dos prompt and running the shortened executable with a command line option of "-version" (I would type "unisont -version"). This should echo to the screen the version of Unison.

On the computer that will function as the client:

1) download and install PuTTY here.

2) download or copy the Unison executables that you wish to use (either the text based, the GUI or both) to the client machine.

3) run Putty to confirm you can establish a connection to your server. You will tell Putty itself (via the Session screen) the host name (or host ip address) and the port number, along with the protocol (ssh). TIP: Once you have filled in the host name, select 'Save' to save the putty session information. This will be useful later. Then, click 'Open' (the connection). At that point, it should first display a relatively long message window and give you the option of establishing the connection even though there is no registry or cache that matches the server. At that point, if you answer "Yes", then the registry/cache item will be created which will allow future connections to operate without this interruption. Putty then opens a dos window and presents you with a login prompt. Use the username and password you established in step 3, above. If the username and password are accepted, you will be presented with a dos prompt for your server. Type 'exit' to terminate the connection.

4) establish a batch file which provides the link between Unison and plink. I used plinker.bat and it contains a single line with the following:

As has been noted in other tutorials, the "@" sign is critical. Where I have typed mypassword, use your password. Where I have typed myusername, use your user name. Where I have typed mysavedputtysession, use your saved putty session name.

5) establish a profile for use by Unison. Here is a test profile that I used successfully, which I named profiletest.prf:

Where I typed remoteipaddress you can enter either the ip address of the server (e.g., 158.130.66.9) or a host name that windows can locate (e.g., myserver).

6) run the text version of Unison from a dos prompt. I used the following command line:

Remember that I renamed the Unison executable to unisont.exe on both the server and the client so that it would be easier to work with.

7) run the GUI version of Unison, select the profiletest profile and click OK

Thanks to Colin Alston who seemed to use just the right words to unlock the mystery (for me, anyway) at: http://www.karnaugh.za.net/show?id=96

I'm having trouble getting GTK unison to work in windows.

Your GTK folder should have the following structure,

• *.dll
• lib\gtk-2.0\2.10.0\engines\*.dll
• lib\gtk-2.0\2.10.0\immodules\*.dll
• lib\gtk-2.0\2.10.0\loaders\*.dll

for me, I dump all the dlls into my unison folder in the above structure and it works fine. i.e. becomes portable

Setting up Unison via COPSSH between two WinXP hosts

[Instructions posted to the unison-users list by Hans Henderson (hh - feel free to contact me - hans@pobox.com) ]

After a lot of mucking around and experimentation I got Unison's native ssh transport working from one XP host to another, so I thought I'd mention a couple of items against which I was banging my head a while, to save others the pain. Sorry I don't have time (nor a posting place) for a full cookbook-style howto.

I used COPSHH to set up the OpenSHH server - this also sets up cygwin, nice side benefit. I also used Putty for testing, but now I believe it's not used at all in my final setup. One key item is that the unison executable should either:

1. be in the SSH's environment's path - I messed around a lot with bash shell scripting etc., nothing worked in the end except copying it into my c:\windows (or c:\windows\system32) folder, and I think it needs to be named unison.exe that way.

OR 2. explicitly pointed to with the servercmd variable, e.g.in the .PRF: servercmd=/cygdrive/d/PortableApps/Unison-2.27.47/exe/unison.exe

I chose the latter so I wouldn't have to worry about remembering to upgrade Unison in two locations later on.

Note that this "cygdrive = master virtual root" feature may work perfectly well from the ssh command line, both in a remote shell and from the client's CLI, but it does NOT work in specifying the root path for Unison. My "unison root" was on a different drive from my SSH server's executables, and I couldn't get it to work re-installing COPSSH to the D: drive - I really noodled around with this for hours, was on the verge on experimenting with NTFS "junction links" which would require converting the filesystem of my target drive, but while I was waiting for my backup to complete before going ahead, I hit upon - well, here's my batch file:

Note the drive letter syntax in the target URI; unisong.exe is my name for the gui version, and the weird IP address is because I'm doing all this within a Hamachi VPN/tunnel as well in order to punch through my employer's firewall. Now works like a charm, secure yet convenient. Wasn't able to get key-based authentication working, still have to put in my password every time, but that's NBD.

So that's it, I think I've hit the main gotcha's, but general advice is to start basic, following the tutorial in the docs - first get Unison working local-to-local, then on a LAN host-to-host in sockets mode, then setup SSH with COPSSH and Putty for testing. Take good notes and create self-documenting batch files as you go along, and of course backup your "live" data set before you start.

In fact, I reckon don't rely on this automated sync routine as your main backup process - have a completely separate one doing regular snapshots so you can roll back any mistakes, with Unison or elsewhere - I'm using Ghost 12 set to run in the background every couple of hours during the day.

Using Unison to sync files with a Linux SSH server operating on a non-standard port.

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 are similar to the section above (many thanks) but have been repeated here in their entirety for clarity. A copy of these instructions can be found at http://www.sbtechsolutions.biz/synchronization/unison.

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:

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:

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

Using WinMerge for resolving conflicts:

I have been using the cygwin port of Unison under Windows for years: just check out your preferred Unison version(s) with the cygwin setup tool and you are set to go!

I recently integrated this system with the excellent open source program WinMerge (http://winmerge.org/), using the following addition to my Unison profile (make sure to get the different types of quotes right!). Of course, you might want to use a slightly more narrow name pattern...

#Winmerge: /e:  Exit by single escape
#          /ub: Do not add paths to MRI
#          /dl, dr: Description, left, right
#          /wr  Right side: read only
#          Merge only works when first root is local!
merge     = Name * -> winmerge /ub /e /dl "Local" /dr "Remote" "`cygpath -w 'CURRENT1'`" "`cygpath -w 'CURRENT2'`"