Updated documentation to match the current implementation.

fixes #3

INSTALL

@@ -1,211 +1,161 @@
-=======================================
+= Installation of DAVAdmin =
- WebDAVAdmin installation instructions
-=======================================
-:Author: Jan Dittberner
-:Contact: jan@dittberner.info
-:Version: 0.1
-:Revision: $Revision$
-:Date: $Date$
-:Copyright: Copyright (C) 2007 Jan Dittberner
 
-.. contents::
+To install DAVAdmin you need:
 
-Unpack WebDAVAdmin
+ * an Apache 2.2 webserver http://httpd.apache.org/
-==================
+   * mod_auth_digest
+   * mod_dav
+   * mod_env
+   * mod_auth_file
+   * mod_authz_groupfile
+ * administration privileges for the webserver or a cooperative ISP
+ * shell access to create administration users for you DAVAdmin installation
+ * for site installation you need write access to a globally available directory on the webserver host (i.e. /usr/local)
 
-1. unpack the WebDAVAdmin distribution file somewhere::
+== DAVAdmin installation ==
 
-     cd ~/tmp/
+Download the release file from the [wiki:Downloads downloads page].
-     tar xjf webdavadmin-0.1.tar.bz2
 
-   ``~/tmp/`` is just an example to be able to reference it in these
+Extract the release file in a directory
-   installation instructions
 
-Setup PostgreSQL and your database
+{{{
-==================================
+cd /usr/local
+tar xzf davadmin-0.1.tar.gz
+}}}
 
-1. Install PostgreSQL by the means of your operating system. For
+== Apache Setup ==
-   Debian GNU/Linux 4.0 Etch execute::
 
-     sudo aptitude install postgresql-8.1
+The following apache configuration file snippet shows the configuration of a !VirtualHost to use WebDAV for a directory {{{dav}}} inside the !VirtualHost's document root:
 
-2. Switch to user postgres::
+{{{
+<VirtualHost 127.0.0.1:80>
+  ServerAdmin jan@davhost.example.com
+  ServerName dav.localhost
 
-     sudo su - postgres
+  DavLockDb /var/run/apache2/davlock/davhost.example.com
+  DocumentRoot /var/www/html
+  Alias /davadmin /usr/local/davadmin-0.1/admin
 
-   and
+  php_admin_value allow_call_time_pass_reference 1
+  <Directory /var/www/html/dav>
+    Dav on
+    AllowOverride AuthConfig Indexes
+    Order Allow,Deny
+    allow from all
+  </Directory>
 
-   1) create a user for WebDAVAdmin::
+  <Location /davadmin>
+    AuthType Digest
+    AuthName "WebDAV Administration"
+    AuthDigestDomain /davadmin http://davhost.example.com/davadmin
 
-        createuser -SDRP myuser
+    SetEnv DavAdminConfDir /var/www/conf
 
-      when prompted type the password for the database user twice
+    AuthDigestProvider file
+    AuthUserFile /var/www/auth/davadmin.htdigest
+    require valid-user
+  </Location>
 
-   2) create a database::
+  <Location /dav/>
+    AuthType Digest
+    AuthName "WebDAV on davhost.example.com"
+    AuthDigestDomain /dav/ 
+    
+    AuthDigestProvider file
+    AuthUserFile /var/www/auth/dav.htdigest
+    AuthGroupFile /var/www/auth/dav.groups
+  </Location>
 
-        createdb --owner=myuser --encoding=UTF-8 mydb
+  ErrorLog /var/log/apache2/davhost.example.com_error.log
+  LogLevel warn
+  CustomLog /var/log/apache2/davhost.example.com_access.log combined
+</VirtualHost>
+}}}
 
-   3) exit the postgres shell
+The snippet is included in the release file as {{{davadmin.vhost}}} inside the directory {{{setup}}}. You will want to change the IP address, directory names, realm names ({{{AuthName}}} directive), and other settings relevant for your site.
 
-   You may skip theese steps if you want to use an existing database
+All following instructions refer to the information used in the above configuration snippet. You need to make sure that you have write access to the used files or have a friendly administrator at hand who performs the tasks for you.
 
-3. Import the schema for WebDAVAdmin::
+=== Creating necessary files and directories ===
 
-     psql -h localhost -U myuser mydb < ~/tmp/webdavadmin-0.1/setup/schema.sql
+{{{
+mkdir -p /var/www/auth
+mkdir -p /var/www/html/dav
+mkdir -p /var/www/conf
+touch /var/www/auth/dav.htdigest
+touch /var/www/auth/dav.groups
+touch /var/www/auth/dav.namemap
+}}}
 
-   when prompted type the password for your database user.
+=== Granting neccessary write access to the apache user ===
+In the following lines we assume your apache user is {{{www-data}}} ([http://www.debian.org/ Debian's] default). Consult your operating system manual to find out what is the correct username for your system.
 
-Setup Apache
+== Creation of DAVAdmin users ==
-============
+To add DAVAdmin users you need to create the authentication file using Apache's {{{htdigest}}} tool.
 
-1. Install, enable and configure apache and the apache modules
+{{{
+htdigest -c /var/www/auth/davadmin.htdigest "WebDAV Administration" admin
+}}}
 
-   - mod_dav
+The tool asks you for the password for the user admin and a confirmation of the password.
-   - mod_dav_fs
-   - mod_auth_pgsql
-   - libphp5
 
-   by the means of your operating system vendor. For Debian GNU/Linux 4.0
+==== Using ACLs ====
-   Etch this means [1]_::
+If you have an ACL enabled file system you may use the following instructions to grant the necessary rights.
 
-     sudo aptitude install apache2-mpm-prefork libapache2-mod-php5 libapache2-mod-auth-pgsql
+ * grant write access to the WebDAV root:
-     sudo a2enmod php5
+{{{
-     sudo a2enmod auth_pgsql
+setfacl -d -m u:www-data:rwx /var/www/html/dav
-     sudo a2enmod dav
+setfacl -m u:www-data:rwx /var/www/html/dav
-     sudo a2enmod dav_fs
+}}}
 
-.. [1] if you don't want to use ``sudo`` you may also switch to root.
+ * grant write access to the authentication and authorization files
+{{{
+setfacl -m u:www-data:rw- /var/www/auth/dav.htdigest /var/www/auth/dav.groups /var/www/auth/dav.namemap
+}}}
 
-2. Configure a VirtualHost to use WebDAV and PostgreSQL
+==== Without using ACLs ====
-   authentication, this VirtualHost configuration could look like::
+If you cannot use ACLs you have two options:
 
-     <VirtualHost *:80>
+ * making the directories and files world writable
-       ServerName davhost.yourdomain.net
+{{{
+chmod 0777 /var/www/html/dav
+chmod 0666 /var/www/auth/dav.htdigest /var/www/auth/dav.groups /var/www/auth/dav.namemap
+}}}
 
-       DavLockDb /var/run/apache2/davlock/davhost.yourdomain.net
+ * changing the owner of the files to the apache user
-       DocumentRoot /var/www
+{{{
+chown www-data /var/www/html/dav
+chown www-data /var/www/auth/dav.htdigest /var/www/auth/dav.groups /var/www/auth/dav.namemap
+}}}
 
-       <Directory /var/www/dav>
+== DAVAdmin configuration ==
-         Options Indexes
-         Order allow,deny
-         allow from all
 
-         Dav on
+DAVAdmin is configured via a file {{{config.inc.php}}} in the directory defined via the {{{SetEnv DavAdminConfDir}}} directive in the apache configuration. For the above setup the configuration file has the following content:
 
-         # Authentication/Authorization
+{{{
-         AuthType Basic
+<?php
-         AuthName "WebDAVAdmin example"
+/*
-         AuthBasicAuthoritative Off
+ * DavAdmin configuration file.
-         AuthUserFile /etc/apache2/auth/davhost.yourdomain.net.passwd
+ */
 
-         Auth_PG_host localhost
+$davconfig = array(
-         Auth_PG_port 5432
+    'compile_dir' => '/var/www/templates_c',
-         Auth_PG_user myuser
+    'digest.file' => '/var/www/auth/dav.htdigest',
-         Auth_PG_pwd secret
+    'group.file' => '/var/www/auth/dav.groups',
-         Auth_PG_database mydb
+    'namemap.file' => '/var/www/auth/dav.namemap',
-         Auth_PG_pwd_table dav_password
+    'dav.dir' => '/var/www/html/dav',
-         Auth_PG_uid_field username
+    'dav.realm' => 'WebDAV on davhost.example.com',
-         Auth_PG_pwd_field password
+    'dav.uri' => 'http://davhost.example.com/dav/',
-         Auth_PG_grp_table dav_group
+    );
-         Auth_PG_grp_user_field username
+?>
-         Auth_PG_grp_group_field groupname
+}}}
-         Auth_PG_hash_type MD5
-         #Auth_PG_log_table dav_log
-         #Auth_PG_log_uname_field username
-         #Auth_PG_log_date_field reqdate
-         #Auth_PG_log_uri_field uri
-         #Auth_PG_log_addrs_field ipaddr
-         Auth_PG_authoritative on
 
-         require group davroot
+== Restart apache ==
-       </Directory>
 
-       ErrorLog /var/log/apache2/davhost.yourdomain.net_error.log
+To make the setup active you need to restart your apache webserver. On a Debian system with {{{sudo}}} use:
-       CustomLog /var/log/apache2/davhost.yourdomain.net_access.log combined
-     </VirtualHost>
 
+{{{
+sudo invoke-rc.d apache2 restart
+}}}
 
-   The directory specified for ``DavLockDb`` must be writable for the
+For other systems please read the manuals on how to restart the apache webserver.
-   user your apache processes run as. The ``AuthUserFile`` is
-   specified as a fallback if your PostgreSQL database is not
-   available.
-
-Install required php modules and classes
-========================================
-
-WebDAVAdmin needs Smarty and a PostgreSQL PDO driver for PHP5. To
-install these requirements perform the following step::
-
-  sudo aptitude install smarty php5-pgsql
-
-on operating systems other then Debian GNU/Linux consult your system
-documentation.
-
-Copy WebDAVAdmin files
-======================
-
-2. create a new document root directory or a subdirectory inside an
-   existing one
-
-3. create a subdirectory which you'll later use for WebDAVAdmin::
-
-     mkdir /var/www/dav
-
-4. copy the admin subdirectory of the unpacked webdavadmin distribution
-   file to the directory just created::
-
-     cp -R webdavadmin-0.1/admin /var/www/dav/
-
-5. set the filesystem permissions of the dav directory to allow the
-   user apache is running as to write to the directory
-
-Configure WebDAVAdmin
-=====================
-
-The WebDAVAdmin distribution contains a directory ``config`` with
-configuration templates that you need to customize for your
-environment.
-
-1. ``dbsettings.inc.php``
-
-   This file contains the settings for your database connection. The
-   file should be placed outside the document root for security
-   reasons. A customized version of this file may look like::
-
-     <?php
-     /** Data source name. */
-     $dsn = "pgsql:host=localhost port=5432 dbname=mydb";
-     /** Database user. */
-     $dbuser = "myuser";
-     /** Database password. */
-     $dbpass = "secret";
-     ?>
-
-2. ``config.inc.php``
-
-   This file contains the absolute path to your WebDAVAdmin
-   installation and to your ``dbsettings.inc.php``. A customized
-   version of this file could be::
-
-     <?php
-     /** DAV area root directory. */
-     define(DAV_ROOT, '/var/www/dav');
-
-     /** Include the database settings. */
-     include_once('/etc/webdavadmin/dbsettings.inc.php');
-     ?>
-
-   After adapting the contents to your environment put this file into
-   your WebDAVAdmin directory. For example::
-
-     cp config.inc.php /var/www/dav/admin/
-
-Be sure to make the subdirectory templates_c of your WebDAVAdmin
-directory writable for your apache user [2]_.
-
-.. [2] you could use chown, chmod and/or ACLs to perform this task
-
-Now you should be able to use your installation of WebDAVAdmin by
-opening the URL http://davhost.yourdomain.net/dav/admin/ (if you just
-followed this instructions).
-

README

@@ -17,23 +17,6 @@ The goal of this software is to provide an easy to use administration
 interface for a WebDAV repository using mod-auth-pgsql as its
 authentication and authorization source.
 
-Requirements
-============
-
-To use this software you need an Apache webserver configured with the
-dav module and mod-auth-pgsql, PHP 5 with PostgreSQL PDO driver, the
-Smarty_ template engine and a PostgreSQL database. The software has
-been developed using the versions contained in Debian GNU/Linux 4.0
-Etch.
-
-- Apache 2.2.3
-- PostgreSQL 8.1.8
-- mod-auth-pgsql 2.0.3
-- PHP 5.2.0
-- Smarty 2.6.14
-
-.. _Smarty: http://smarty.php.net/
-
 Installation
 ============
 

TODO

@@ -3,4 +3,3 @@ TODO
 
 - create an installer
 - setup admin user during installation
-- better integration into existing databases

config/config.inc.php

@@ -5,10 +5,12 @@
 
 $davconfig = array(
     // Absolute path to template compile dir
-    'compile_dir' => '/home/www/dav/templates_c',
+    'compile_dir' => '/var/www/templates_c',
-    'digest.file' => '/home/www/dav/auth/dav.htdigest',
+    'digest.file' => '/var/www/auth/dav.htdigest',
-    'group.file' => '/home/www/dav/auth/dav.groups',
+    'group.file' => '/var/www/auth/dav.groups',
-    'namemap.file' => '/home/www/dav/auth/dav.namemap',
+    'namemap.file' => '/var/www/auth/dav.namemap',
-    'dav.dir' => '/home/www/dav/html/dav',
+    'dav.dir' => '/var/www/html/dav',
-    );
+    'dav.realm' => 'WebDAV on davhost.example.com',
+    'dav.uri' => 'http://davhost.example.com/dav/',
+);
 ?>

config/dbsettings.inc.php

@@ -1,36 +0,0 @@
-<?php
-/**
- * Database settings.
- *
- * @author Jan Dittberner <jan@dittberner.info>
- * @version $Id$
- * @license GPL
- * @package WebDAVAdmin
- *
- * Copyright (c) 2007 Jan Dittberner
- *
- * This file is part of WebDAV administration.
- *
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License as
- * published by the Free Software Foundation; either version 2 of the
- * License, or (at your option) any later version.
- *
- * This program is distributed in the hope that it will be useful, but
- * WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
- * General Public License for more details.
- *
- * You should have received a copy of the GNU General Public License
- * along with this program; if not, write to the Free Software
- * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
- * 02110-1301 USA.
- */
-
-/** Data source name. */
-$dsn = "pgsql:host=localhost port=5432 dbname=@dbname@";
-/** Database user. */
-$dbuser = "@dbuser@";
-/** Database password. */
-$dbpass = "@dbpass@";
-?>

setup/davadmin.vhost

@@ -0,0 +1,42 @@
+<VirtualHost 127.0.0.1:80>
+  ServerAdmin jan@davhost.example.com
+  ServerName davhost.example.com
+
+  DavLockDb /var/run/apache2/davlock/davhost.example.com
+  DocumentRoot /var/www/html
+  Alias /davadmin /usr/local/davadmin-0.1/admin
+
+  php_admin_value allow_call_time_pass_reference 1
+  <Directory /var/www/html/dav>
+    Dav on
+    AllowOverride AuthConfig Indexes
+    Order Allow,Deny
+    allow from all
+  </Directory>
+
+  <Location /davadmin>
+    AuthType Digest
+    AuthName "WebDAV Administration"
+    AuthDigestDomain /davadmin http://davhost.example.com/davadmin
+
+    SetEnv DavAdminConfDir /var/www/conf
+
+    AuthDigestProvider file
+    AuthUserFile /var/www/auth/davadmin.htdigest
+    require valid-user
+  </Location>
+
+  <Location /dav/>
+    AuthType Digest
+    AuthName "WebDAV on davhost.example.com"
+    AuthDigestDomain /dav/ 
+    
+    AuthDigestProvider file
+    AuthUserFile /var/www/auth/dav.htdigest
+    AuthGroupFile /var/www/auth/dav.groups
+  </Location>
+
+  ErrorLog /var/log/apache2/davhost.example.com_error.log
+  LogLevel warn
+  CustomLog /var/log/apache2/davhost.example.com_access.log combined
+</VirtualHost>

setup/schema.sql

@@ -1,25 +0,0 @@
-CREATE TABLE dav_password (
-  uid SERIAL PRIMARY KEY,
-  username VARCHAR(16) NOT NULL UNIQUE,
-  password VARCHAR(34) NOT NULL,
-  firstname VARCHAR(64),
-  lastname VARCHAR(64)
-);
-
-CREATE TABLE dav_group (
-  gid SERIAL PRIMARY KEY,
-  username VARCHAR(16) NOT NULL REFERENCES dav_password(username),
-  groupname VARCHAR(32) NOT NULL,
-  UNIQUE(username, groupname)
-);
-
-CREATE TABLE dav_log (
-  logid SERIAL PRIMARY KEY,
-  username VARCHAR(16),
-  reqdate VARCHAR(20),
-  uri TEXT,
-  ipaddr VARCHAR(16)
-);
-
-INSERT INTO dav_password (username, password) VALUES ('admin', md5('secret'));
-INSERT INTO dav_group (username, groupname) VALUES ('admin', 'davadmin');

setup/webdavadmin.vhost

@@ -1,43 +0,0 @@
-<VirtualHost 127.0.0.1:80>
-  ServerAdmin jan@dittberner.info
-  ServerName dav.localhost
-
-  DavLockDb /var/run/apache2/davlock/davhost.localhost
-  DocumentRoot /home/www/dav/html
-  Alias /davadmin /home/jan/work/projects/davadmin/trunk/admin
-
-  php_admin_value allow_call_time_pass_reference 1
-  <Directory /home/www/dav/html/dav>
-    Dav on
-    AllowOverride AuthConfig Indexes
-    Order Allow,Deny
-    allow from all
-  </Directory>
-
-  <Location /davadmin>
-    AuthType Digest
-    AuthName "WebDAV Administration"
-    AuthDigestDomain /davadmin http://dav.localhost/davadmin
-
-    SetEnv DavAdminConfDir /home/www/dav/conf
-
-    AuthDigestProvider file
-    AuthUserFile /home/www/dav/auth/davadmin.htdigest
-    require valid-user
-  </Location>
-
-  <Location /dav/>
-    AuthType Digest
-    AuthName "WebDAV on dav.localhost"
-    AuthDigestDomain /dav/ 
-    
-    AuthDigestProvider file
-    AuthUserFile /home/www/dav/auth/dav.htdigest
-    AuthGroupFile /home/www/dav/auth/dav.groups
-  </Location>
-
-  ErrorLog /var/log/apache2/davhost.localhost_error.log
-  LogLevel warn
-  CustomLog /var/log/apache2/davhost.localhost_access.log combined
-</VirtualHost>
-