Updated documentation to match the current implementation.

fixes #3
This commit is contained in:
Jan Dittberner 2007-11-23 20:53:20 +00:00
parent 90dbac0f20
commit 8f1c952074
8 changed files with 173 additions and 301 deletions

296
INSTALL
View file

@ -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::
{{{
<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
- 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:
<VirtualHost *:80>
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
}}}
<Directory /var/www/dav>
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
{{{
<?php
/*
* DavAdmin configuration file.
*/
Auth_PG_host localhost
Auth_PG_port 5432
Auth_PG_user myuser
Auth_PG_pwd secret
Auth_PG_database mydb
Auth_PG_pwd_table dav_password
Auth_PG_uid_field username
Auth_PG_pwd_field password
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
$davconfig = array(
'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/',
);
?>
}}}
require group davroot
</Directory>
== Restart apache ==
ErrorLog /var/log/apache2/davhost.yourdomain.net_error.log
CustomLog /var/log/apache2/davhost.yourdomain.net_access.log combined
</VirtualHost>
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::
<?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).
For other systems please read the manuals on how to restart the apache webserver.

17
README
View file

@ -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
============

1
TODO
View file

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

View file

@ -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/',
);
?>

View file

@ -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@";
?>

42
setup/davadmin.vhost Normal file
View file

@ -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>

View file

@ -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');

View file

@ -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>