User Tools

Site Tools


unix:unison

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

unix:unison [2007/04/27 00:23] (current)
Line 1: Line 1:
 + !!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''​
 +<code bash>
 +#​!/​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
 +</​code>​
 +
 +==== 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''​
 +<​code>​
 +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)
 +</​code>​
 +
 +===== 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 ====
 +<code bash>
 +find data -print0 | xargs -0 chown -v meermanr:​apache
 +</​code>​
 +
 +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 ====
 +<code bash>
 +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
 +</​code>​
 +
 +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.
unix/unison.txt · Last modified: 2007/04/27 00:23 (external edit)