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.

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 Cygwin¹⁾ 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

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)

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.

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:

• find is a command which produces a list of paths, optionally filtered by certain criteria
• data means consider only paths in ./data
• -print0 means print null characters instead of spaces/newlines, effectively allowing these properties in file names.
• xargs is a command which takes a list and passes each one as an argument to the program specified. It's a convenient way to do foreach-loops and the like
• -0 (zero) tells it to use nulls to split its input into list elements
• chown Change Owner
• -v Verbose (i.e. give feedback)
• meermanr:apache set user to meermanr, and group to apache

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:

• -type f/d Means only list files or directories, respectively.
• chmod Changes access permissions of a file or directory
• -v Verbose, show what it's doing
• ug=rw,o=r Users & Group should have Read/Write permissions only, and others should only have Read
• ug=rwXs,o=rX Users & Groups should have Read/Write/eXecute/Sticky permissions, while others should only have Read/eXecute.
  • In unix, a directory's eXecute permission dictates whether it can be traversed. If eXecute permission is not granted you cannot enter a directory, even if you have Read permission (which grants you the ability to obtain a list of what is contained within that directory). (“X” (capital) only applies to directories, while “x” (lowercase) can apply to either files or directories)
  • Sticky is not described in POSIX, but as best I can tell if a directory has the sticky bit set for the group, files created in that directory will inherit the directory's group. In this case it means that instead of new files having an owner of “meermanr:meermanr” they will have the directory's: “meermanr:apache”.

==

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

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:

• File you upload to your user account will belong to you. This means that Apache cannot edit them, so all pages have a “Show Page Source” button where you expect “Edit this Page” button.
• Files created by the server do not belong to you, nor do you have write permission via any other means. This means you cannot delete or modify the files directly — you have to use DokuWiki to do that. To change the owner to yourself, you need root access, or at least a way of getting Apache to do it.²⁾

Side affects on your home (WinXP) PC:

• Very occasionally you get problems just like the above. But it seems you can prevent this happening by explicitly removing all non-inherited permissions on and within your local copy of the site (see the screen-shots below for how to do this).

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)

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.