davadmin/INSTALL

= Installation of DAVAdmin =

To install DAVAdmin you need:

 * 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)

== DAVAdmin installation ==

Download the release file from the [wiki:Downloads downloads page].

Extract the release file in a directory

{{{
cd /usr/local
tar xzf davadmin-0.2.tar.gz
}}}

== Apache Setup ==

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:

{{{
<VirtualHost 127.0.0.1:80>
  ServerAdmin jan@davhost.example.com
  ServerName dav.localhost

  DavLockDb /var/run/apache2/davlock/davhost.example.com
  DocumentRoot /var/www/html
  Alias /davadmin /usr/local/davadmin-0.2/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

    AuthType Digest
    AuthName "WebDAV on davhost.example.com"
    AuthDigestDomain /dav/ 
    
    AuthDigestProvider file
    AuthUserFile /var/www/auth/dav.htdigest
    AuthGroupFile /var/www/auth/dav.groups

    require valid-user
  </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>

  ErrorLog /var/log/apache2/davhost.example.com_error.log
  LogLevel warn
  CustomLog /var/log/apache2/davhost.example.com_access.log combined
</VirtualHost>
}}}

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.

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.

=== Creating necessary files and directories ===

{{{
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
}}}

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

== Creation of DAVAdmin users ==
To add DAVAdmin users you need to create the authentication file using Apache's {{{htdigest}}} tool.

{{{
htdigest -c /var/www/auth/davadmin.htdigest "WebDAV Administration" admin
}}}

The tool asks you for the password for the user admin and a confirmation of the password.

==== Using ACLs ====
If you have an ACL enabled file system you may use the following instructions to grant the necessary rights.

 * 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
}}}

 * 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
}}}

==== Without using ACLs ====
If you cannot use ACLs you have two options:

 * 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
}}}

 * 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
}}}

== DAVAdmin configuration ==

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:

{{{
<?php
/*
 * DavAdmin configuration file.
 */

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

== Restart apache ==

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

For other systems please read the manuals on how to restart the apache webserver.