# HG changeset patch
# User Paul Boddie <paul@boddie.org.uk>
# Date 1442098238 -7200
# Node ID 8c43fba1f9b1d85a1307bf596dbad93e18b3e0c8
# Parent  5be5353060e15d0338dc567a7823a2bf8567acd1
Updated the documentation and scripts with information on local SMTP mode,
parameterising the scripts and adding help texts.

diff -r 5be5353060e1 -r 8c43fba1f9b1 README.txt
--- a/README.txt	Sat Sep 12 20:16:38 2015 +0200
+++ b/README.txt	Sun Sep 13 00:50:38 2015 +0200
@@ -17,6 +17,17 @@
 System User and Filesystem Access
 ---------------------------------
 
+The data handled by imip-agent needs to be accessible to other software,
+notably mail handling software and Web server software. Two approaches are
+described here: LMTP delivery and local SMTP delivery.
+
+LMTP Delivery
+-------------
+
+Here, imip-agent's programs run in a way that permits LMTP delivery (requiring
+suitable local privileges to communicate with the mail storage solution)
+whilst allowing the Web server to read data written by those programs.
+
 A system group needs to be created for LMTP delivery and for certain users to
 share resources:
 
@@ -41,10 +52,32 @@
 and published data so that new files and directories have the appropriate
 group associated with them.
 
+It should be possible to omit all arguments to the init.sh script, but it is
+also worth reading the help message:
+
+  tools/init.sh --help
+
 Fixing ownership can be done using the tools/fix.sh script, in case some form
 of modification has altered the ownership or membership of the created files
 and directories.
 
+Local SMTP Delivery
+-------------------
+
+Here, imip-agent's programs run in a way that permits local SMTP delivery
+(which merely needs the ability to connect to a local network service) whilst
+allowing the Web server to read data written by those programs.
+
+A system user needs to be created and to belong to certain groups in order to
+deliver messages to mail stores and to publish resources on the Web:
+
+  useradd -d /var/lib/imip-agent -m -U -G www-data -r imip-agent
+
+Again, the tools/init.sh script will initialise directories for stored and
+published data. For example:
+
+  tools/init.sh imip-agent www-data
+
 Installing the Software
 -----------------------
 
diff -r 5be5353060e1 -r 8c43fba1f9b1 conf/postfix/master.cf.items
--- a/conf/postfix/master.cf.items	Sat Sep 12 20:16:38 2015 +0200
+++ b/conf/postfix/master.cf.items	Sun Sep 13 00:50:38 2015 +0200
@@ -1,3 +1,4 @@
+# Replace lmtp with www-data if operating in local SMTP mode.
 imip_resources  unix  -      n       n       -       -       pipe
   flags=FR user=imip-agent:lmtp argv=/var/lib/imip-agent/imip_resource.py
   -o ${original_recipient}
diff -r 5be5353060e1 -r 8c43fba1f9b1 tools/fix.sh
--- a/tools/fix.sh	Sat Sep 12 20:16:38 2015 +0200
+++ b/tools/fix.sh	Sun Sep 13 00:50:38 2015 +0200
@@ -1,9 +1,28 @@
 #!/bin/sh
 
-USER=imip-agent
-GROUP=lmtp
-INSTALL_DIR=/var/lib/imip-agent
-WEB_INSTALL_DIR=/var/www/imip-agent
+PROGNAME=`basename $0`
+
+DEFAULT_USER=imip-agent
+DEFAULT_GROUP=lmtp
+DEFAULT_INSTALL_DIR=/var/lib/imip-agent
+DEFAULT_WEB_INSTALL_DIR=/var/www/imip-agent
+
+if [ "$1" = "--help" ]; then
+    cat 1>&2 <<EOF
+Usage: $PROGNAME [ <user> [ <group> [ <stored data directory> [ <published data directory> ] ] ] ]
+
+Fix permissions for the stored and published data directories, using the given
+user and group (or, respectively, $DEFAULT_USER and $DEFAULT_GROUP if omitted),
+and operating on the given stored data and published data directories (or,
+respectively, $DEFAULT_INSTALL_DIR and $DEFAULT_WEB_INSTALL_DIR if omitted).
+EOF
+    exit 1
+fi
+
+USER=${1:-$DEFAULT_USER}
+GROUP=${2:-$DEFAULT_GROUP}
+INSTALL_DIR=${3:-$DEFAULT_INSTALL_DIR}
+WEB_INSTALL_DIR=${4:-$DEFAULT_WEB_INSTALL_DIR}
 
 chown -R "$USER" "$INSTALL_DIR"
 chgrp -R "$GROUP" "$INSTALL_DIR"
diff -r 5be5353060e1 -r 8c43fba1f9b1 tools/init.sh
--- a/tools/init.sh	Sat Sep 12 20:16:38 2015 +0200
+++ b/tools/init.sh	Sun Sep 13 00:50:38 2015 +0200
@@ -1,9 +1,37 @@
 #!/bin/sh
 
-USER=imip-agent
-GROUP=lmtp
-INSTALL_DIR=/var/lib/imip-agent
-WEB_INSTALL_DIR=/var/www/imip-agent
+PROGNAME=`basename $0`
+
+DEFAULT_USER=imip-agent
+DEFAULT_GROUP=lmtp
+DEFAULT_INSTALL_DIR=/var/lib/imip-agent
+DEFAULT_WEB_INSTALL_DIR=/var/www/imip-agent
+
+if [ "$1" = "--help" ]; then
+    cat 1>&2 <<EOF
+Usage: $PROGNAME [ <user> [ <group> [ <stored data directory> [ <published data directory> ] ] ] ]
+
+Initialise stored and published data directories with permissions set to the
+given user and group (or, respectively, $DEFAULT_USER and $DEFAULT_GROUP if omitted),
+and with the given stored data and published data directories (or, respectively,
+$DEFAULT_INSTALL_DIR and $DEFAULT_WEB_INSTALL_DIR if omitted).
+
+Within the stored data directory, the following directories are created:
+
+  * $DEFAULT_INSTALL_DIR/store
+  * $DEFAULT_INSTALL_DIR/preferences
+
+Within the published data directory, the following directory is created:
+
+  * $DEFAULT_WEB_INSTALL_DIR/static
+EOF
+    exit 1
+fi
+
+USER=${1:-$DEFAULT_USER}
+GROUP=${2:-$DEFAULT_GROUP}
+INSTALL_DIR=${3:-$DEFAULT_INSTALL_DIR}
+WEB_INSTALL_DIR=${4:-$DEFAULT_WEB_INSTALL_DIR}
 
 for DIR in "$INSTALL_DIR"/store "$INSTALL_DIR"/preferences "$WEB_INSTALL_DIR"/static ; do
     mkdir -p "$DIR"