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

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 interface for a WebDAV repository using mod-auth-pgsql as its
authentication and authorization source. 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 Installation
============ ============

1
TODO
View file

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

View file

@ -5,10 +5,12 @@
$davconfig = array( $davconfig = array(
// Absolute path to template compile dir // 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/',
);
?> ?>

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>