Table of Contents

!!You may edit this page!!

Using Unison with DokuWiki

Unison is a file-synchronization tool for Unix and Windows. It allows two or more file repositories, to be kept synchronised by detecting and then propagating changes between the repositories, no matter if they are different directories on the same disk, or on completely different filesystems on different machines.

I encountered several problems when I first tried to syncronise my laptop ↔ desktop ↔ webserver with this site.

Running Unison

I don't intend to explain how to install and use Unison itself, but I think it'd put this page in context if I were to outline how I use it.

At home I use WinXP with Cygwin1) and have the following script setup to synchronise my local copy of this website:

Script: syncrobmeerman.co.uk

#!/usr/bin/bash
echo "Synchronising with RobMeerman.co.uk"
unison /home/meermanr/My\ Documents/Projects/RobMeerman.co.uk ssh://meermanr@robmeerman.co.uk/public_html \
  -fastcheck yes \
  -ignore 'Path downloads' \
  -ignore 'Path data/cache' \
  -ignore 'Path data/locks' \
  -ignore 'Path gallery' \
  -ignore 'Path stats' \
  $*  # Include invocation arguments

Notes on script

The two directories I wish to syncronise are

  1. My Documents\Projects\RobMeerman.co.uk”, which I linked to my home directory with the “ln -s” command.
  2. robmeerman.co.uk:public_html/”, which I access the webserver via SSH

I don't bother to syncronise the cache directory, and I pass arguments from the command-line that invoked this script to unison itself via the $* variable. I frequently use the -batch argument to sync without user intervention (it skips all conflicts and syncs without confirmation).

A typical run outputs something like this:

Invoked with: ./syncrobmeerman.co.uk -batch

Contacting server...
Looking for changes
  conf/acl.auth.php
  data/attic/_dummy
  data/attic/ai/chrispres.1108079478.txt.gz
  ...

  Waiting for changes from server
Reconciling changes
Propagating updates


UNISON started propagating changes at 16:43:13 on 12 Jan 2006

local          robm
         <---- new file   data/attic/fitz/progress.1135826010.txt.gz
local        : absent
robm         : new file           modified on 2006-01-09 at 10:04:37  size 3140      read-write
         <---- new file   data/attic/fitz/progress.1136793877.txt.gz
local        : absent
robm         : new file           modified on 2006-01-09 at 10:05:28  size 3164      read-write
         <---- new file   data/attic/unix/unison.1133789685.txt.gz
local        : absent
...

[BGN] Copying data/attic/fitz/progress.1135826010.txt.gz
  from //robm//home/meermanr/public_html
  to /cygdrive/c/Documents and Settings/meermanr/My Documents/Projects/RobMeerman.co.uk
[BGN] Copying data/attic/fitz/progress.1136793877.txt.gz
  from //robm//home/meermanr/public_html
  to /cygdrive/c/Documents and Settings/meermanr/My Documents/Projects/RobMeerman.co.uk
[BGN] Copying data/attic/unix/unison.1133789685.txt.gz
  from //robm//home/meermanr/public_html
  to /cygdrive/c/Documents and Settings/meermanr/My Documents/Projects/RobMeerman.co.uk
...

[END] Copying data/locks/d22cfe28bbe1dedb32d46860c3197f62
[END] Copying data/locks/eaf0c14731cd0d83937362e440e1c5e9
[END] Copying data/attic/fitz/progress.1136793877.txt.gz
...
UNISON finished propagating changes at 16:43:23 on 12 Jan 2006

Saving synchronizer state
Synchronization complete  (15 items transferred, 0 skipped, 0 failures)

File Permissons

If you follow the installation instructions for DokuWiki, then you would have changed the owner of the data directory and it's subdirectories to httpd:httpd (or apache:apache in my case). The problem with this is that you want to run Unison under your own user account (meermanr in my case), but if the files are owned by the webserver group you cannot edit them, so you won't be able to propagate changes to this repository.

My solution to this is to change the owner of the files to me (meermanr) and then grant the group (which is apache or httpd) write permissions, hence allowing both myself and the webserver to modify these files.

Changing the Owner

find data -print0 | xargs -0 chown -v meermanr:apache

This will change the owner of all file & directories under ./data to be changed to meermanr:apache.

Break down of this command:

Changing the Permissions

find data -type f -print0 | xargs -0 chmod -v ug=rw,o=r
find data -type d -print0 | xargs -0 chmod -v ug=rwXs,o=rX

Similar to the previous section, this one updated the read/write/execute permissions:

==

I have actually scheduled both these scripts to run every hour on my server, which seems to work nicely.

Side affects of wrong permissions

I haven't actually mentioned why you need to fix permissions. The truth is you may not depending on how you use DokuWiki.

Side affects on the (Linux) webserver:

Side affects on your home (WinXP) PC:

What about Windows?

My desktop and laptop run WinXP Pro, and have relatively few problems with permissions, but now and again something does go wrong, so I find my website folder in explorer, go to Properties → Security → Advanced and then tick “Replace permission entries on all child objects with entries shown here that apply to child objects” and his “OK”. This replaces all the permissions of the files and folders and tends to sort out most of my problems.

WinXP Home users probably do not have to worry about this, as they do not possess the security tab for files/directories, and presumably are unable to use anything but the default permissions.

:!: Note: If you have WinXP Pro but don't see a “security” tab in the properties dialog, you probably have “Simple File Sharing” enabled. Disable it thusly in any explorer window: Tools > Folder Options > View > (scroll to very bottom) > [ ] Use simple file sharing (Recommended)

Summary

Now when my linux webserver creates new files, or I propagate changes to the server with unison, they are created with owner “meermanr:apache” and permissions of rw-rw-r– and rwsrwsr-x for file/directories respectively.

1)
You can think of Cygwin as a “way to add the fun parts of Linux to Windows”. Such as BASH scripting and SSH.
2)
You could probably setup your own PHP script that you invoke via some URL which does it for you…