Unison

Introduction
This document describes how to install and run the Unison file synchronisation software on Linkstation LS2(MIPS) with OpenLink firmware or using apt-get with FreeLink firmware. Note that this also is fully functional with Freelink on the Arm devices through apt-get.

From the Unison website: Unison is a file-synchronization tool for Unix and Windows (and now the Linkstation ;-). It allows two replicas of a collection of files and directories to be stored on different hosts (or different disks on the same host), modified separately, and then brought up to date by propagating the changes in each replica to the other.

It offers bi-directional sync unlike the mirroring capability of tools like rsync. All in all it's a great tool for linkstation users!

Background
There are a number of ways to use Unison but the way described here (and recommended on unison website) is to run the unison application as a server on the linkstation. Data is then transferred using the client application over SSH.

Requirements
You will need:
 * Linkstation LS2(MIPS)
 * MIPSel development tools
 * Openlink 0.52 firmware
 * OCAML compiler source (I used 3.10.1)
 * Unison binaries (I used 2.27.57)

This procedure works on the TeraStation Live with stock firmware, you'll just need to install the compilation tools

Install Openlink
This is the first step as documented elsewhere on this site. You need to enable dropbear access for SSH.

Install development tools
Again, this is documented elsewhere. It provides the critical binaries such as gcc and make for the linkstation.

On a TeraStation you can follow these instructions. One small detail if you use these you need to type gmake instead of make in the compilation procedures described next.

Unpack and build the OCAML compiler
Unison is written in OCAML. To build unison you must first compile the OCAML toolchain. Latest source code is available as a tar from here: http://caml.inria.fr/


 * Copy tar to a temp directory on linkstation hda (main file storage area)
 * Unpack the tar
 * Get root access to linkstation through SSH or telnet. Type "./configure -prefix"
 * Type "make world" - this makes the byte code compiler. It might be possible to install the full native compiler but I didn't get this working
 * Type "make install"
 * Type "make clean" - this cleans up all the rubbish made during install
 * Should all be installed now! Type "ocaml -version" to check everything has built. "The Objective Caml toplevel, version 3.10.1" should appear.
 * Should all be installed now! Type "ocaml -version" to check everything has built. "The Objective Caml toplevel, version 3.10.1" should appear.

You may get an error while compiling the ocamtools, specifically: Unbound Value “name_of_insrtuctions” : Error 2

This has to do with an error in the make file in the tools directory to generate the opnames.ml file. A sed command is giving an error during make so the file is not generated appropriately and it stays empty. For simplicity you can download the correct version of the opnames.ml, and place it in you ocaml-3.09.3/tools directory, then rerun “gmake world”.

I could not compile OCAML 3.10.2 on the TeraStation Live, so I used the OCAML 3.09.3 and it all worked fine, after the opnames.ml fix.

Make the Unison tool

 * Grab the Unison source code from http://www.cis.upenn.edu/~bcpierce/unison
 * It's important to use the same version on client and server. I run ubuntu which has Unison 2.13.16 available in the package manager. However I couldn't get this version running on linkstation. I eventually installed version 2.27.57 on the linkstation and my ubuntu PC.
 * Unpack the tar into a temp directory on the linkstation.
 * Again using SSH or telnet, get shell access to linkstation and type "make UISTYLE=text NATIVE=false". This builds the text version (rather than GTK) and uses the OCAML bytecode compiler rather than the native compiler.
 * There will be a warning at the end of the build about "etags" (?) I think this can be safely ignored.
 * Copy the "unison" executable into the "/usr/bin" directory on the linkstation
 * To test the build now type "unison - version." It should respond with "unison version 2.27.57"
 * Great! The real hard work is over.

These instructions work for the TeraStation Live as well. Here's a link the pre-built binary of unison 2.27.57 compiled on a TS Live.

FreeLink
Use apt-get to install unison apt-get install unison

Testing Unison
Looking for changes Warning: No archive files were found for these roots. This can happen either because this is the first time you have synchronized these roots, or because you have upgraded Unison to a new version with a different archive format.
 * You should now install the Unison tool to your PC if you haven't done so already. Windows, Mac and various Linux binaries are available - just make sure you use the same version as on the linkstation or it won't work.
 * From your PC, you're now going to test the communication with the linkstation. Make a directory a.tmp and populate it with a couple of small files. Create a new empty directory on the linkstation. We'll use unison to copy the new files to it!
 * Open up a terminal window and type "unison -testserver /mnt/local/a.tmp ssh://root@192.168.1.8//mnt/hda/share/a.tmp". The "-testserver" option means nothing is copied, it's just testing the ability to connect to the server. "/mnt/local/a.tmp" is the absolute path to my new local directory. "ssh://root@192.168.1.8//mnt/hda/share/tmp.a" describes the directory on the linkstation. Replace with your linkstation name/IP as appropriate.
 * If this is successful it should respond with [no output] Try this command again but remove the -testserver switch. The files should be synced to the linkstation.
 * The utility is verbose, and explains if its identified a new backup destination.

Update detection may take a while on this run if the replicas are large.

Unison will assume that the 'last synchronized state' of both replicas was completely empty. This means that any files that are different will be reported as conflicts, and any files that exist only on one replica will be judged as new and propagated to the other replica. If the two replicas are identical, then no changes will be reported. Press return to continue.[ ]

It will then display the files to be copied and show the direction of the sync.

Reconciling changes

local         LSPro dir     >            /  [f]

Commands: or f or  follow unison's recommendation (if any) I                    ignore this path permanently E                    permanently ignore files with this extension N                    permanently ignore paths ending with this name m                    merge the versions d                    show differences x                    show details l                    list all suggested changes p or b               go back to previous item g                    proceed immediately to propagating changes q                    exit unison without propagating any changes /                    skip > or. propagate from from local to LSPro < or,               propagate from from LSPro to local
 * f stands for follow Unisons recommendation. these are the options available by pressing ?

Proceed with propagating updates? [] y Propagating updates
 * Once you have agreed or modified any of the actions, it runs the sync.

The graphical versions are also useful, and offer the ability to do Profiles, but be sure to use the same versions on each of the machines running Unison.

Next Steps
I've only just got this working myself but it seems pretty good. There are command line options to automate the sync, so I'm thinking of setting up a regular cron on my ubuntu PC to sync my local data with linkstation as a backup. As I tend to work directly with the files on the linkstation when I'm using my laptop a one-way sync isn't much good but I think unison could be.

Another potentially great use would be to have two linkstations running unison. They could automatically sync to each other. Because it uses SSH these two devices could be in separate locations and communicate over the internet.