!!You may edit this page!!
====== Using Unison with DokuWiki ======
[[http://www.cis.upenn.edu/~bcpierce/unison/|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 Cygwin((You can think of Cygwin as a "way to add the fun parts of Linux to Windows". Such as BASH scripting and SSH.)) 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
- "''My Documents\Projects\RobMeerman.co.uk''", which I linked to my home directory with the "''ln -s''" command.
- "''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:
* **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
==== 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:
* **-type f/d** Means only list **f**iles or **d**irectories, 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.
==== 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:
* 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.((You could probably setup your own PHP script that you invoke via some URL which does it for you...))
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).
===== 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)''//
{{unix:winxp_dir_properties.gif}}
{{unix:winxp_dir_advanced_security.gif}}
{{unix:winxp_dir_advanced_securitywarn.gif}}
{{unix:winxp_dir_settingperms.gif}}
===== 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.