From 8f1c952074c4f6538362caac80e4961ce81c3cc4 Mon Sep 17 00:00:00 2001 From: Jan Dittberner Date: Fri, 23 Nov 2007 20:53:20 +0000 Subject: [PATCH] Updated documentation to match the current implementation. fixes #3 --- INSTALL | 296 ++++++++++++++++---------------------- README | 17 --- TODO | 1 - config/config.inc.php | 14 +- config/dbsettings.inc.php | 36 ----- setup/davadmin.vhost | 42 ++++++ setup/schema.sql | 25 ---- setup/webdavadmin.vhost | 43 ------ 8 files changed, 173 insertions(+), 301 deletions(-) delete mode 100644 config/dbsettings.inc.php create mode 100644 setup/davadmin.vhost delete mode 100644 setup/schema.sql delete mode 100644 setup/webdavadmin.vhost diff --git a/INSTALL b/INSTALL index 30a1da5..00d7c6e 100644 --- a/INSTALL +++ b/INSTALL @@ -1,211 +1,161 @@ -======================================= - WebDAVAdmin installation instructions -======================================= -:Author: Jan Dittberner -:Contact: jan@dittberner.info -:Version: 0.1 -:Revision: $Revision$ -:Date: $Date$ -:Copyright: Copyright (C) 2007 Jan Dittberner += Installation of DAVAdmin = -.. 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/ - tar xjf webdavadmin-0.1.tar.bz2 +Download the release file from the [wiki:Downloads downloads page]. - ``~/tmp/`` is just an example to be able to reference it in these - installation instructions +Extract the release file in a directory -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 - Debian GNU/Linux 4.0 Etch execute:: +== Apache Setup == - 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:: +{{{ + + 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 + + Dav on + AllowOverride AuthConfig Indexes + Order Allow,Deny + allow from all + - 1) create a user for WebDAVAdmin:: + + 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 + - 2) create a database:: + + AuthType Digest + AuthName "WebDAV on davhost.example.com" + AuthDigestDomain /dav/ + + AuthDigestProvider file + AuthUserFile /var/www/auth/dav.htdigest + AuthGroupFile /var/www/auth/dav.groups + - 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 + +}}} - 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 - - mod_dav_fs - - mod_auth_pgsql - - libphp5 +The tool asks you for the password for the user admin and a confirmation of the password. - by the means of your operating system vendor. For Debian GNU/Linux 4.0 - Etch this means [1]_:: +==== Using ACLs ==== +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 - sudo a2enmod php5 - sudo a2enmod auth_pgsql - sudo a2enmod dav - sudo a2enmod dav_fs + * grant write access to the WebDAV root: +{{{ +setfacl -d -m u:www-data:rwx /var/www/html/dav +setfacl -m u:www-data:rwx /var/www/html/dav +}}} -.. [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 - authentication, this VirtualHost configuration could look like:: +==== Without using ACLs ==== +If you cannot use ACLs you have two options: - - ServerName davhost.yourdomain.net + * making the directories and files world writable +{{{ +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 - DocumentRoot /var/www + * changing the owner of the files to the apache user +{{{ +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 +}}} - - Options Indexes - Order allow,deny - allow from all +== DAVAdmin configuration == - 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 - AuthName "WebDAVAdmin example" - AuthBasicAuthoritative Off - AuthUserFile /etc/apache2/auth/davhost.yourdomain.net.passwd +{{{ + '/var/www/templates_c', + 'digest.file' => '/var/www/auth/dav.htdigest', + 'group.file' => '/var/www/auth/dav.groups', + 'namemap.file' => '/var/www/auth/dav.namemap', + 'dav.dir' => '/var/www/html/dav', + 'dav.realm' => 'WebDAV on davhost.example.com', + 'dav.uri' => 'http://davhost.example.com/dav/', + ); +?> +}}} - require group davroot - +== Restart apache == - ErrorLog /var/log/apache2/davhost.yourdomain.net_error.log - CustomLog /var/log/apache2/davhost.yourdomain.net_access.log combined - +To make the setup active you need to restart your apache webserver. On a Debian system with {{{sudo}}} use: +{{{ +sudo invoke-rc.d apache2 restart +}}} - The directory specified for ``DavLockDb`` must be writable for the - 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:: - - - -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:: - - - - 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). - +For other systems please read the manuals on how to restart the apache webserver. \ No newline at end of file diff --git a/README b/README index 5458dac..fe2b5be 100644 --- a/README +++ b/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 ============ diff --git a/TODO b/TODO index b62ef0b..c456d05 100644 --- a/TODO +++ b/TODO @@ -3,4 +3,3 @@ TODO - create an installer - setup admin user during installation -- better integration into existing databases diff --git a/config/config.inc.php b/config/config.inc.php index 06c0f07..d0ae601 100644 --- a/config/config.inc.php +++ b/config/config.inc.php @@ -5,10 +5,12 @@ $davconfig = array( // Absolute path to template compile dir - 'compile_dir' => '/home/www/dav/templates_c', - 'digest.file' => '/home/www/dav/auth/dav.htdigest', - 'group.file' => '/home/www/dav/auth/dav.groups', - 'namemap.file' => '/home/www/dav/auth/dav.namemap', - 'dav.dir' => '/home/www/dav/html/dav', - ); + 'compile_dir' => '/var/www/templates_c', + 'digest.file' => '/var/www/auth/dav.htdigest', + 'group.file' => '/var/www/auth/dav.groups', + 'namemap.file' => '/var/www/auth/dav.namemap', + 'dav.dir' => '/var/www/html/dav', + 'dav.realm' => 'WebDAV on davhost.example.com', + 'dav.uri' => 'http://davhost.example.com/dav/', +); ?> diff --git a/config/dbsettings.inc.php b/config/dbsettings.inc.php deleted file mode 100644 index f47f67e..0000000 --- a/config/dbsettings.inc.php +++ /dev/null @@ -1,36 +0,0 @@ - - * @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@"; -?> \ No newline at end of file diff --git a/setup/davadmin.vhost b/setup/davadmin.vhost new file mode 100644 index 0000000..a4dcab0 --- /dev/null +++ b/setup/davadmin.vhost @@ -0,0 +1,42 @@ + + 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 + + Dav on + AllowOverride AuthConfig Indexes + Order Allow,Deny + allow from all + + + + 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 + + + + AuthType Digest + AuthName "WebDAV on davhost.example.com" + AuthDigestDomain /dav/ + + AuthDigestProvider file + AuthUserFile /var/www/auth/dav.htdigest + AuthGroupFile /var/www/auth/dav.groups + + + ErrorLog /var/log/apache2/davhost.example.com_error.log + LogLevel warn + CustomLog /var/log/apache2/davhost.example.com_access.log combined + \ No newline at end of file diff --git a/setup/schema.sql b/setup/schema.sql deleted file mode 100644 index ae45b04..0000000 --- a/setup/schema.sql +++ /dev/null @@ -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'); diff --git a/setup/webdavadmin.vhost b/setup/webdavadmin.vhost deleted file mode 100644 index ea11ae0..0000000 --- a/setup/webdavadmin.vhost +++ /dev/null @@ -1,43 +0,0 @@ - - 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 - - Dav on - AllowOverride AuthConfig Indexes - Order Allow,Deny - allow from all - - - - 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 - - - - 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 - - - ErrorLog /var/log/apache2/davhost.localhost_error.log - LogLevel warn - CustomLog /var/log/apache2/davhost.localhost_access.log combined - -