Synchronising laptop and desktop files using Unison

From NewbieDOC


Chris Lale
chrislale users DOT berlios DOT de

Go to NewbieDOC index

Revision History


Revision 0.0 30th September 2006 Revised by Chris Lale
Pre-release.

Revision 1.0 5th October 2006 Revised by Chris Lale
Initial release.

Revision 1.1 26th November 2007 Revised by Chris Lale
Reformatted for newbiedoc package.


Image:Newbiedoc-32.png Stable document
You can comment on this document by clicking on the discussion tab.

You can edit the live version of this document: Synchronising laptop and desktop files using Unison


Abstract

If you have a home network, you can edit files on one computer and use Unison to update another computer. This is very useful if you do work on a laptop away from the network for part of the time. Unison will suggest which files on each computer should be updated with files from the other one. If there is a conflict in a file that it cannot resolve, it will suggest not synchronising that file until you have resolved the problem manually. Unison does not rely on Samba or NFS, but uses Ssh to transfer files between the computers. There is a commandline version of Unison and a GUI version using GTK. This article describes the GTK version provided in Debian Etch. The article uses the example of a laptop computer and a desktop computer on a home network, but Unison can be used for any two computers on a network, or even two computers with ethernet interfaces joined by a crossover cable.


Contents


1 Install Debian packages

You probably have the Openssh client installed on both computers already. If not, you must install the openssh-client package on the computer(s) you wish to run Unison from locally. You must install the openssh-server package on the computer(s) you want Unison to contact remotely. For example, if you wish to run Unison from a laptop computer to synchronise with files on a desktop computer, install an ssh server on the desktop. You may find it convenient to install both openssh-server and openssh-client on each computer so that you can run Unison from either machine (providing that both are running and on the network). You will also need one of the ssh-askpass packages if you are going to run Unison from a desktop menu rather than a terminal window. You will need the alacarte package if you wish to add Unison to the Gnome desktop Applications menu.

Install these packages using Synaptic, Aptitude or Apt-get:

openssh-client, openssh-server, unison-2.9.1-gtk

If you wish to add an entry for Unison to the Gnome desktop Aplications menu, install these packages:

alacarte, ssh-askpass or ssh-askpass-gnome

2 Prepare both computers

2.1 Network interface IP addresses

You need to know the IP addresses linked to the network interfaces of each of your computers. If you have no network at all, you can safely use a private network such as 192.168.1.0. In this case you can then give your computers the network addresses 192.168.1.2 and 192.168.1.3.

If you are using a broadband DSL/ADSL modem/router to connect to the internet, your computers may get their IP addresses from a built-in DHCP server. You need to reconfigure your modem/router to give your laptop and desktop machines static IP addresses. For example, if your network is 192.168.1.0 and your modem/router is at IP address 192.168.1.1, you could allocate your desktop to 192.168.1.2 and your laptop to 192.168.1.3.

Make sure that you configure the /etc/network/interfaces file on each computer to match. In this example the /etc/network/interfaces file for the desktop computer with an ethernet interface may look like this:

auto eth0

iface eth0 inet static
	address 192.168.1.2
	netmask 255.255.255.0
	network 192.168.1.0
	broadcast 192.168.1.255
	gateway 192.168.1.1

The /etc/network/interfaces file for a laptop computer with a wireless adapter may look like this:

auto wlan0
allow-hotplug wlan0

iface eth0 inet static
	address 192.168.1.3
	netmask 255.255.255.0
	network 192.168.1.0
	broadcast 192.168.1.255
	gateway 192.168.1.1
 
Note
Note: 
Check that you can ping each computer from the other using the commands ping 192.168.1.2 and ping 192.168.1.3 .
 

2.2 Link hostnames to IP addresses

It is easier to use the hostnames of your computers rather than their IP addresses. The hostname is set at boot using the name stored in the file /etc/hostname. The domain name, in the file /etc/resolv.conf.You can find out what the hostnames are using the command hostname. For example, if your laptop computer has the hostname laptop and you are using the domain name home for your home private network:

$ hostname
laptop

If you wish to change the hostname, you must do two things:

  1. set the new hostname using the hostname newname command as user root,
  2. edit the /etc/hostname file so that it contains the newname; this makes the change permanent.

You can can tell your computer about the names you have given to other IP addresses on your private network. Just add the information to each computer's /etc/hosts file. For example, this file on laptop tells the laptop computer that the computer with IP address 192.168.1.2 is called desktop and belongs in the domain home:

127.0.0.1 localhost laptop

192.168.1.2 desktop.home desktop

# The following lines are desirable for IPv6 capable hosts
[...]


Make sure that /etc/hosts for desktop contains

127.0.0.1 localhost desktop

192.168.1.3 laptop.home laptop

3 Set up Ssh

At least one of the computers must have an ssh server installed. If you run Unison from laptop, you will need an ssh server on desktop. If you run Unison from desktop, you will need an ssh server on laptop. Configure and test the ssh connection for each computer. The example that follow assumes that the desktop is the local computer (the one that you are working on), and the laptop is the remote computer.

3.1 Set up the ssh connection to the laptop from the desktop

Run ssh from a user account on the desktop and connect to a user on the laptop. In this example, both users have the same username - "chris". This is not essential, but it is probably what you want. From the desktop

$ ssh chris@laptop
	
The authenticity of host 'laptop (192.168.1.3)' can't be established.
RSA key fingerprint is 53:b4:ad:c8:51:17:99:4b:c9:08:ac:c1:b6:05:71:9b.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'desktop,192.168.1.3' (RSA) to the list of known hosts.
chris@laptop's password:

Enter the password for user chris on the laptop. If you are successful, you will see the prompt for chris@laptop.

[...]
	
chris@laptop:~$

Close the ssh connection to return to the prompt for chris@desktop.

$ exit
logout
Connection to laptop closed.
chris@desktop:~$

3.2 Check that Unison will run via ssh

From desktop

$ ssh laptop unison-2.9.1-gtk -version
$ chris@laptop's password:

Enter the password for chris@laptop.

unison version 2.9.1

Close the ssh connection to return to the prompt for chris@desktop.

$ exit
logout
Connection to laptop closed.
chris@desktop:~$

3.3 Set up an ssh key

A key is a convenient alternative to a password. At the moment, you will have to supply the user's password every time that you connect with ssh. If you set up a key, you can arrange that it is supplied automatically after first use during a session.

If you do not already have an ssh key, create one using ssh-keygen. You will need to supply a pass phrase. Choose something that you will remember - a short line from your favourite song perhaps? From desktop

$ ssh-keygen -t dsa
	
Generating public/private dsa key pair.
Enter file in which to save the key (/home/chris/.ssh/id_dsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /home/chris/.ssh/id_dsa.
Your public key has been saved in /home/chris/.ssh/id_dsa.pub.
The key fingerprint is:
93:58:20:56:72:d7:bd:14:86:9f:42:aa:82:3d:f8:e5 chris@desktop

There is now a pair of keys - a private key and a public key. Never give anyone else your private key. You can give the public key (with a .pub extension to anyone that needs it. You must give chris@desktop's public key to chris@laptop. Copy key to chris@laptop using the secure copy command scp. From desktop

$ scp ~/.ssh/id_dsa.pub chris@laptop:.ssh/authorized_keys
chris@laptop's password:
id_dsa.pub		100%  600  0.6KB/s  00:00

3.4 ssh into desktop using the key

Check that the key works. From the desktop

$ ssh chris@laptop
Enter passphrase for key '/home/chris/.ssh/id_dsa':
Linux desktop 2.6.17-2-686 #1 SMP Wed Sep 13 16:34:10 UTC 2006 i686

[...]

$ exit

3.5 Cache your identity

Repeatedly supplying the passphrase is as bad (or worse than) repeatedly supplying the password. You can get around this by using the ssh-add command. Do this once and that key will be supplied automatically until you end the session by logging out.

$ ssh-add
Enter passphrase for key '/home/chris/.ssh/id_dsa':
Identity added: /home/chris/.ssh/id_dsa (home/chris/.ssh/id_dsa)

3.6 test by ssh-ing into the laptop with your stored identity

This time you should get straight in without being asked for your passphrase.

$ ssh chris@laptop
Linux desktop 2.6.17-2-686 #1 SMP Wed Sep 13 16:34:10 UTC 2006 i686

[...]
	
$ exit

3.7 Set up ssh for the other computer

Repeat the process in this section to set up an ssh server for the other computer. Just swap "laptop" and "desktop" in the example above.

4 Test-run unison-2.9.1-gtk

To run Unison from the desktop PC, you must have an ssh server running on the laptop. If you run Unison from a terminal window, you will be asked for your passphrase in the terminal window. If you run Unison from a menu (see above), you must have one of the "askpass" packages installed. This will enable a dialogue window to pop up and ask for your passphrase at the appropriate moment.

4.1 Create test directories and files

Login as a normal user on the desktop computer. Use the file browser or the mkdir and touch commands to create a directories (folders) and empty files with this structure:

     a.tmp/
     |
     |__ d/
     |   |__ f
     |
     |__ a
     |__ b        

The commands that will do this are:

mkdir a.tmp
touch a.tmp/a a.tmp/b
mkdir a.tmp/d
touch a.tmp/d/f

Login to the laptop computer and do the same thing, only this time call the first directory b.tmp.

     b.tmp/
     |
     |__ d/
     |   |__ f
     |
     |__ a
     |__ b        

Delete file a in a.tmp. Edit the other files so that they have the following contents:

file a.tmp b.tmp
a (delete file)
b Hello Hello
c 1066
d/h Hi there Hello there

The commands that will do this on the desktop are:

rm a.tmp/a
echo Hello > a.tmp/b
echo "Hi there" > a.tmp/d/h

The commands that will do this on the laptop are:

echo Hello > b.tmp/b
echo 1066 > b.tmp/c
echo "Hello there" > b.tmp/d/h

In order to be synchronised, file a should be deleted from b.tmp, file b does not need synchronising and file c on a.tmp should be updated with the contents of a.tmp/c. Also, the two versions of file h are in conflict - they have the same filename but different contents.

4.2 Run Unison from a terminal window

Make sure that the laptop and desktop are both running. Login to the desktop as the normal user whose files you wish to synchronise. Open a terminal window and enter the command for Unison.

$ unison-2.9.1-gtk

In the dialogue for "Profiles", select the "default" profile and click on OK.

Image:dir.png

Now choose the two "roots". These are the directories that you wish to synchronise. In the first dialogue for "Root selection", type in the name of the directory on the local machine (desktop) in the "Dir:" box. Click on OK.

Image:directory.png

In the second dialogue for "Root selection", type in the name of the directory on the remote machine (laptop) in the "Directory:" box. Select the "SSH" radio button. Type the hostname of the remote coputer (laptop) into the "Host:" box. Type the username of the user on the remote coputer (laptop) into the "User:" box. Click on Continue.

Supply your passphrase. If you are running Unison from a terminal window, the message requesting the passphrase will be in the terminal window. Enter the passphrase in the terminal window.

You may see a message about contacting the server. You have just created a profile and you are running it for the first time. The first time that you run a profile you will see a warning about there being no archive files. Just click on OK.

Image:main.png

The main window appears. In the example you can see three different actions:

  • A red question mark indicates a conflict that Unison cannot resolve without your help. In this example there are two new files with the same name and different contents. Click on the Diff button and you can see the difference between the two files - one contains "Hi there" and the other contains "Hello there".
  • A green right arrow indicates that a change in the local file must be used to update the remote file. In this example the local (desktop) file has been deleted and Unison wants to delete the remote (laptop) file.
  • A green left arrow shows that a change on the remote system will be propagated to the local system.

You can override the proposed actions by highlighting the action and clicking on the left arrow and right arrow buttons. The proposed override is shown as a blue arrow.

If you are happy with the changes, click on go. Only the green and blue actions will take place. Click on the Quit button to close Unison.

5 Add Unison to the Gnome menu (optional)

Use the Alacarte Menu Editor to add Unison to the Gnome desktop Applications menu. Run Alacarte and select a suitable sub-menu from the left-hand pane. You can create a completely new sub-menu using

  • File -> New Menu

if you wish. Choose New Entry from the File menu, type "Unison" in the "Name:" box and "/usr/bin/unison-gtk" in the "Command:" box. Click OK.

  • File -> New Entry
    • Name: Unison
    • Command: unison-gtk
    • OK

Make sure that you have installed either the ssh-askpass or the ssh-askpass-gnome package, or one of the alternatives, so that you can supply your passphrase to Unison.

6 Managing profiles

Your Unison profiles are stored in the hidden directory .unison in your home directory. The profile files are plain text and have the file extension .prf. For example, the default profile is ~/.unison/default.prf. You can delete any profiles you do not wish to use. If you delete all your profiles, Unison will create a new default profile the next time you run it.


7 Appendix A: Licence

Copyright (c) 2006-2007 Chris Lale. chrislale AT users DOT berlios DOT de.

GNU FDL Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License."

Go to NewbieDOC index

Content is available under GNU Free Documentation License 1.2, unless otherwise stated.