Synchronise your files with Unison
TUTORIal
Installing Unison
Most Linux distributions have Unison as a package ready for installation so that you do not have to compile it. At the time of writing, the current stable version of Unison is 2.40.102.
Note that every machine that is part of the synchronisation process must have a copy of the command-line version of Unison installed.
Additionally, this copy of Unison should be located inside one of the directories of the default PATH shell variable. Assuming you’re on a Debian-based system, simply type:
sudo apt-get install unison
To find the version of Unison you are using, just type the following command:
unison -version
Synchronising files on the same computer
Although Unison was initially developed with synchronising files located on different machines in mind, you can synchronise files located on the same computer using one of the following two methods:
• Using localhost as the remote machine name.
• Using only local directory paths for both root = lines.
Your advisor prefers the second way as it does not require the SSH server be up and running.
The Unison profile file is called localFiles.prf
04
Synchronising files with another computerGiven a profile name called articles.prf that is located inside the ~/.unison directory, you can tell Unison to use it by executing the following command:
$ unison articles
The remote machine declaration starts with root = ssh://.
There are rare occasions – usually when the user changed a file on both computers before synchronising – where Unison will not be able to determine whether a file or directory has changed on the local or the remote server. In such situations, Unison kindly asks for your help so that it will not mistakenly proceed using the wrong version.
02
Unison profile filesUnison can run from the command line without using any configuration files (profiles), but using a profile greatly simplifies its use –
having a profile file does not prevent you from adding extra command-line options (although this article will not deal much with such options).
In the rare event that you have troubles working with Unison, you may run it using the ‘-debug all’
command-line option so that you can better trace and resolve errors.
and is located inside the ~/.unison directory. The following two lines to work on the same machine, as they do not include a remote machine:
root = /Users/mtsouk root = /tmp
Synchronise your files with Unison
Tutorial
05
Running Unison using a simple profile fileSome basic things you need to know about Unison profiles are:
• The default backup level is 2, which controls how many previous versions of each file are kept not including the current version of the file. So the default backup level keeps two backup copies of a file. The parameter for setting the backup level is called maxbackups.
• You can tell Unison not to keep file backups by not adding any backup options inside a Unison profile file.
• Unison profile files support Unicode characters.
• The logfile option tells Unison to keep a log file called unison.log inside the .unison directory.
• Sometimes, network problems prohibit file synchronisation, but Unison’s error messages are denoting the problem:
$ unison articles Contacting server...
Connection closed by 109.xxx.yyy.zzz Fatal error: Lost connection with the server
07
The .unison directoryMost of the Unison housekeeping happens inside the .unison directory which resides in the user’s home directory.
Unison keeps the following data there:
• Its profile files including the default profile called default.prf.
• Its backup files, if you decided to have central backups.
• The status file for each used profile.
• The Unison log file, should you tell it to keep one.
You can put it anywhere you want but it is very convenient for it to reside there.
• Unison creates lock files there, during synchronisations, which it deletes when finished.
Note: It is not recommended to synchronise the whole .unison directory. Synchronising just the profiles is okay.
08
A more advanced Unison profile fileThe contents of the advanced.prf file are as follows:
root = /Users/mtsouk
root = ssh://linode//home/mtsouk times = true
batch = true
# Log file
logfile = /Users/mtsouk/.unison/
unison.log
# Paths to synchronize path = code/C
# Backup files backup = Name *
backuplocation = central maxbackups = 3
ignore = Name {Thumbs.db}
ignore = Name {.DS_Store}
ignore = Path {Samples.lnk}
06
Explaining the profile fileLines starting with a # denote comments and are not processed any further.
Exactly two lines must start with root =. They declare the machines (one is always the local
computer) that are going to participate in the syncing process as well as the directories that are considered the root directories for each machine.
After those important declarations, the actual directories that are going to be synced are listed.
In this example we have just one directory (one path = line). Its full path is /Users/mtsouk/docs/
article/working for the local machine and /home/
mtsouk/docs/article/working for the machine called linode (an IP alias inside /etc/hosts). You can have as many path entries as you want. All files are synced except the ones that match the ignore option. You can also have as many ignore = lines as you want and can use regular expressions in them. The backup option tells Unison to keep backups of all files.
Unison hints and tips
The first two or three times you use a new profile, double-check if everything works as expected.
• You do not need to use every parameter that Unison supports, just the ones that will do your job!
• You can troubleshoot Unison using the -debug all command-line option. It will generate lots of output useful for debugging.
• The more you use Unison, the more you will understand its practicality.
• You should be very careful with your backup options, especially maxbackups, as it can take up too much space on your computer.
• You can use Unison to securely exchange files between computers.
• If a Windows machine is involved in the synchronisation process, be careful with file and directory permissions.
• For non-critical data files you may run Unison once a day, but for critical data you should run it more often.
• Unison cannot replace regular backups!
• When you are making a new profile, either start simple or use an existing one as a starting template. Add the extra functionality and features while making sure that you always have a working profile.
Use the Unison command-line tool to sync files between computers
Synchronise your files with Unison
TUTORIal
09
Explaining the advanced profile file• The times = true line tells Unison to synchronise modification times.
• The maxbackups = 3 line tells Unison to keep the current file version plus three backups of it.
• The backup = Name * line tells Unison to back up every file.
• The backuplocation = central, which is the default option, tells Unison to keep all backups in a central location. If neither the backupdir preference nor the environment variable UNISONBACKUPDIR are set, the .unison/backup directory is used as the backup location. If set to local, then all backups will be kept in the same directory as the original files.
• The batch = true option is a little tricky and you should be careful with it as Unison will ask no questions at all and non-conflicting changes will be propagated whereas conflicts will be skipped. Nevertheless, it is an essential option if you want to use Unison as a cron job.
• The ignore = Name {.DS_Store} line tells Unison to not synchronise files that end with
.DS_Store.
11
Two common Unisontroubleshooting techniques There are times when things do not work as expected. Unison offers you many options that can help you both find and solve problems.
The first option to try is the -testserver option that just connects to the remote server and then exits without synchronising any files.
The second thing to do is run the following command:
$ ssh remote.machine.domain 'echo
$PATH'
The aforementioned command let you see whether the PATH is the same as when you log in using ssh remote.machine.domain. If the problem is with the PATH, check if the option PermitUserEnvironment in /etc/ssh/
sshd_config is set to ‘no’ and change it to ‘yes’.
10
Using SSH without please do remember the passphrase! Two new files are going to be created: ~/.ssh/id_rsa and~/.ssh/id_rsa.pub.
2. You may need to create a directory called .ssh on the remote server if it does not already exist.
3. Copy the contents of the ~/.ssh/id_rsa.pub file from your local server into the file
~/.ssh/authorized_keys found on the remote server. One way of doing it is by executing the following command:
$ cat ~/.ssh/id_rsa.pub | ssh linode 'cat >> .ssh/authorized_keys'
The next time you try to log into the remote Linux server using SSH, you will be asked for the passphrase of step 1 for the last time.
From now on, you can log into the remote Linux server by just typing ssh linode:
$ ssh linode
Last login: Wed Jul 31 18:46:23 2013 from ppp-94-64-21-97.home.otenet.gr mtsouk@li140-253:~$
The first time you log into the remote server without typing your password, the following informative message will be on the screen:
Identity added: /Users/mtsouk/.ssh/
id_rsa (/Users/mtsouk/.ssh/id_rsa)