WebDAV CGI - Documentation

List of contents:
Back to the WebDAV CGI home

Requirements

You do not need mod_dav for the Apache Web server. WebDAV CGI replaces mod_dav completely.

WebDAV CGI supports two authentication schemes:

Installation

Note: All steps are done with root rights.

Upgrade Note: Please take a look at the Upgrade section for further information.

  1. download WebDAV CGI (note: not necessary for Gentoo)
  2. install required CPAN modules (Debian/Ubuntu package name):
    • CGI (included in most Linux dists; older dists need that: libcgi-perl)
    • DBI (libdbi-perl) and a database driver, e.g. DBD::SQLite (libdbd-sqlite3-perl) - (since v0.3.0)
    • Date::Parse (libtimedate-perl) - (since v0.2.1)
    • OSSP::uuid (libossp-uuid-perl or from http://www.ossp.org/pkg/lib/uuid/) - (since v0.3.0) (since v0.8.0 replaced by UUID::Tiny)
    • UUID::Tiny (libuuid-tiny-perl) - (since 0.8.0)
    • XML::Simple (libxml-simple-perl)
    • Quota (libquota-perl) - (since v0.3.4)
    • Archive::Zip (libarchive-zip-perl) - (since v0.5.0)
    • Image::Magick (perlmagick) - (since v0.5.1) (since v0.5.3 replaced by Graphics::Magick)
    • Graphics::Magick (libgraphics-magick-perl or http://www.graphicsmagick.org/perl.html) - (since v0.5.3)
    • File::Spec::Link (libfile-copy-link-perl) - (since v0.5.2)
    • IO::Compress::Gzip (included in most Linux dists) - (since v0.7.0)
    • IO::Compress::Deflate (included in most Linux dists) - (since v0.7.0)
    • IO::Compress::Brotli - (since v1.1.2)
    • Module::Load (included in most Linux dists, older need libmodule-load-perl) - (since v0.8.0)
    • optional (for SMB backend): Filesys::SmbClient (libfilesys-smbclient-perl) - (since v0.8.0)
    • optional (for RCS backend): Rcs (librcs-perl) - (since v0.8.0)
    • JSON (libjson-perl) - (since v0.8.5)
    • DateTime - (since v0.8.5)
    • DateTime::Format::Human::Duration (libdatetime-format-human-duration-perl) - (since v0.8.5)
    • Image::ExifTool (libimage-exiftool-perl)- (since v1.0.1)
    • List::MoreUtils (liblist-moreutils-perl)- (since v1.1.0)
    • optional for SendByMail extension:MIME::Entity (libmime-tools-perl) - (since v0.9.1)
    • optional for LDAP address book of SendByMail extension:Net::LDAP (libnet-ldap-perl) - (since v0.9.1)
    • optional for Kerberos helpers in conjunction with mod_perl (AFS, SMB):Env::C - (since v1.0.0)
    • optional for AFS Kerberos helpers in conjunction with mod_perl:AFS::PAG - (since v1.0.1)
    You can do that with 'perl -MCPAN -e "install <ModuleName>"' or with 'apt-get install <PackageName>'. 
    ## Debian/Ubuntu quick install: 
apt install libdbi-perl libdbd-sqlite3-perl sqlite3 libtimedate-perl \
            libuuid-tiny-perl libxml-simple-perl libquota-perl \
            libarchive-zip-perl libgraphics-magick-perl libmodule-load-perl \
            libfile-copy-link-perl libjson-perl libdatetime-perl \
            libmime-tools-perl libnet-ldap-perl libimage-exiftool-perl \
            liblist-moreutils-perl libcgi-session-perl libwww-csrf-perl \
             libdatetime-format-human-duration-perl


cpan install IO::Compress::Brotli

## only for PostgreSQL users:
apt install libdbd-pg-perl

## only for MySQL users:
apt install libdbd-mysql-perl

## only for SMB backend users:
apt install libfilesys-smbclient-perl smbclient krb5-user

## only for RCS backend users:
apt install librcs-perl

## only for AFS users:
apt install openafs-client krb5-user openafs-krb5 libafs-pag-perl

## for mod_perl users with Kerberos (SMB, AFS) authentication:
cpan install Env::C
  3. install additional binaries/packages for a better WebDAV CGI experience:
    • Ghostscript - allows the web interface of WebDAV CGI to generate thumbnails for PDF/PS files (Debian/Ubuntu package: ghostscript)
    • smbclient (only for SMB backend users) - allows the web interface to show quota information (Debian/Ubuntu package: smbclient)
    • kinit (only for SMB and AFS backend users) - allowed you to omit mod_auth_kerberos (Debian/Ubuntu package: krb5-user)
    • libreoffice - allows file conversions
    ## Debian/Ubuntu quick install:
apt install  ghostscript

## only for SMB backend users:
apt install smbclient

## only for SMB and AFS backend users:
apt install krb5-user

## for ODFConverter extension:
apt install libreoffice


    ## Gentoo quick install:
emerge -va app-text/ghostscript-gpl

## only for SMB backend users:
emerge -va net-fs/cifs-utils

## only for SMB and AFS backend users:
emerge -va app-crypt/heimdal
  4. install locales 
    ## Debian/Ubuntu quick install:
rm -f /var/lib/locales/supported.d/webdavcgi
for l in de_DE en_US fr_FR it_IT hu_HU ; do
        fgrep $l /usr/share/i18n/SUPPORTED >> /etc/locale.gen
done
locale-gen
  5. change directory to your preferred installation path, e.g. cd /etc
  6. install WebDAV CGI:
    • unzip webdavcgi-latest.zip or tar jxf webdavcgi-latest.tar.gz2 (Gentoo: emerge -va www-apps/webdavcgi)
    • OR clone the Git repo (preferred): git clone https://github.com/DanRohde/webdavcgi.git
  7. change directory to the source base (e.g: cd webdavcgi*) and call bash install.sh to compile all wrappers and to fix file permissions
  8. configure webdav.pl
  9. configure your web server:
    • you can do that with rewrite rules (recommended)
    • or with a handler action (unsupported)
    Examples for Apache 2.x: (you need the Apache rewrite module: a2enmod rewrite) - and don't forget to take a look at the backend specific configuration: AFS, GFS, SMB/CIFS, DBB, or RCS 
    ### EXAMPLE 1: a complete (virtual) server root handled by WebDAV CGI:
ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/webdavwrapper
# ScriptAlias /logout /etc/webdavcgi/cgi-bin/logout
<Location /webdavcgi>
        AuthType Basic
        AuthName "WebDAV space"
        AuthUserFile /path-to-my-auth-file
        Require valid-user
</Location>
RewriteEngine On
# RewriteRule /logout - [L]
RewriteRule ^/ /webdavcgi [PT,E=WEBDAVCONF:/etc/webdav.conf,E=PERLLIB:/etc/webdavcgi/lib/perl,L]
    

    ### EXAMPLE 2: a virtual path /webdav
ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/webdavwrapper
# ScriptAlias /webdav/logout /etc/webdavcgi/cgi-bin/logout
<Location /webdavcgi>
        AuthType Basic
        AuthName "WebDAV space"
        AuthUserFile /path-to-my-auth-file
        Require valid-user
</Location>
# if you want to map this to a real path, do that:
# (and setup $VIRTUAL_BASE='/webdav/?' and $DOCUMENT_ROOT in your WebDAV CGI config)
RewriteEngine On
# RewriteRule ^/webdav/logout - [L]
RewriteRule ^/webdav /webdavcgi  [PT,E=WEBDAVCONF:/etc/webdav.conf,E=PERLLIB:/etc/webdavcgi/lib/perl,L]
    

    ### EXAMPLE 3: a .htaccess file to handle a complete folder with WebDAV CGI:
### Prerequisites: /webdavcgi is a script alias 
##       (ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/webdavwrapper) and
###      'AllowOverride AuthConfig FileInfo' is set for the current folder
RewriteEngine On
RewriteRule .* /webdavcgi [E=WEBDAVCONF:/etc/webdav.conf,E=PERLLIB:/etc/webdavcgi/lib/perl]

AuthType Basic
AuthName "A protected WebDAV folder"
AuthUserFile /path-to-my-auth-file
Require valid-user

Upgrade

Upgrading from 1.1.2 to 1.1.3

Upgrading from 1.1.1 to 1.1.2

Upgrading from 1.1.0 to 1.1.1

Upgrading from 1.0.0 to 1.1.0

Upgrading from 0.9.0 to 1.0.0

Upgrading from 0.8.6 to 0.9.0

Upgrading from 0.8.5 to 0.8.6

  1. The Simple View:

Upgrading from 0.8.4 to 0.8.5

  1. the SVN repository URL has changed: svn switch --relocate https://webdavcgi.svn.sourceforge.net/svnroot/webdavcgi/trunk http://svn.code.sf.net/p/webdavcgi/code/trunk
  2. the default view was changed from 'sidebar' to 'simple'
  3. new Perl modules are needed:
    • JSON (Ubuntu/Debian package: libjson-perl)
    • DateTime (Ubuntu/Debian package: libdatetime-perl
    • DateTime::Format::Human::Duration (CPAN)
  4. SMB backend: the new optional flag 'secure' was added to enable a URL check for allowed servers and shares

Upgrading from 0.8.3 to 0.8.4

  1. The new install.sh script does not copy or link webdav.pl and webdavwrapper to your cgi-bin directory. You can add/change ScriptAliases to use webdav.pl or a webdavwrapper from your installation src, e.g. 
    ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/webdavwrapper
RewriteRule ^/ /webdavcgi [PT,L,E=WEBDAVCONF:/etc/webdav.conf,E=PERLLIB:/etc/webdavcgi/lib/perl]
<Location /webdavcgi>
	AuthType Basic
	AuthUserFile /etc/apache2/webabusers
	AuthName "WebDAV space"
	Require valid-user
</Location>
  2. AFS backend:
    • Speedy support for AFS was added and a mod_auth_kerberos free installation is now possible:
      • a new setuid/setgid wrapper was added: helper/webdavwrapper-afs.c (mod_waklog isn't required if you use webdavwrapper-afs.c)
      • a PAG script was added: cgi-bin/afswrapper
      • visit AFS section for details
    • mod_waklog is no longer required for AFS
  3. SMB backend:
    • a wrapper for mod_auth_kerberos free installation was added
    • username/password/workgroup authentication support was added

Upgrading from 0.8.2 to 0.8.3

  1. changed @UNSELECTABLE_FOLDERS default to () (relevant for AFS backend users)
  2. changed helper/webdavwrapper-smb.c to fix a Kerberos ticket bug (relevant for SMB backend users)

Upgrading from 0.8.1 to 0.8.2

  1. see Speedy support section to improve the WebDAV CGI performance

Upgrading from 0.8.0 to 0.8.1

  1. %AUTOREFRESH was added for the new auto-refresh feature

Upgrading from 0.7.x to ≥0.8.0

  1. a new Perl module is needed: Module::Load (Ubuntu/Debian package: libmodule-load-perl)
  2. OSSP::uuid Perl module was replaced by UUID::Tiny (Ubuntu/Debian package: libuuid-tiny-perl)
  3. WebDAV CGI comes with some own modules so you need to set a additional Perl library path:
    • add E=PERLLIB:/etc/webdavcgi/lib/perl to your rewrite rule options in the Apache configuration
    • OR add SetEnv PERLLIB /etc/webdavcgi/lib/perl to your Apache configuration (don't forget to activate/install env module, e.g. a2enmod env; /etc/init.d/apache restart)
    • OR change shebang of webdav.pl to #!/usr/bin/perl -I/etc/webdavcgi/lib/perl
  4. $IGNOREFILEPERMISSIONS config variable was removed
  5. $BACKEND variable was added and is required (allowed values: 'FS', 'AFS', 'GFS', 'SMB', 'DBB')
  6. $SHOW_MIME and $SHOW_PERM were removed: use the new options @ALLOWED_TABLE_COLUMNS and @VISIBLE_TABLE_COLUMNS instead
  7. %MIMETYPES format was changed: only a single filename suffix is allowed as a key (instead of a space separated list of suffixes); please use $MIMEFILE instead
  8. @EXTENSIONS parameter was added: contains a list of extensions
  9. $ENABLE_SYSINFO was removed: add 'SysInfo' to the @EXTENSIONS list
  10. $ENABLE_PROPERTIES_VIEWER was removed: add 'PropertiesViewer' to the @EXTENSIONS list
  11. $ENABLE_SIDEBAR was removed: use @SUPPORTED_VIEWS instead
  12. $MAXLASTMODIFIEDSIZE was removed
  13. $MAXNAVPATHSIZE was added

Upgrading from ≤0.6.x to ≥0.7.x

  1. two new Perl modules are used by WebDAV CGI: IO::Compress::Gzip and IO::Compress::Deflate (both are integrated in most Linux dists)
  2. WebDAV CGI is no longer a single file distribution therefore:
    1. unpack the new installation package in your preferred installation path, e.g. cd /etc; unzip webdavcgi-0.7.?.zip
    2. link the path for easier upgrades, e.g. ln -s /etc/webdavcgi-0.7.? /etc/webdavcgi
    3. copy the webdav.pl script to your CGI directory and allow execution, e.g. 
      cp /etc/webdavcgi/cgi-bin/webdav.pl /usr/lib/cgi-bin 
chmod a+x /usr/lib/cgi-bin/webdav.pl
    4. add the $INSTALL_BASE variable to your existing /etc/webdav.conf, e.g. 
      echo "\$INSTALL_BASE='/etc/webdavcgi/';" >> /etc/webdav.conf
    5. check your config file and modules, e.g. 
      #> perl -c /etc/webdav.conf
webdav.conf syntax OK

#> perl -I/etc/webdavcgi/lib/perl -c /usr/lib/cgi-bin/webdav.pl
webdav.pl syntax OK

#> bash /etc/webdavcgi/checkenv
+++ Checking perl:
  perl /usr/bin/perl
++++ Checking required modules:
  CGI installed
  DBI installed
  POSIX installed
  File::Temp installed
  Date::Parse installed
  UUID::Tiny installed
  XML::Simple installed
  Quota installed
  Archive::Zip installed
  IO::Compress::Gzip installed
  IO::Compress::Deflate installed
  Digest::MD5 installed
  Module::Load installed
++++ Checking optional modules:
  DBD::SQLite installed
  DBD::mysql installed
  DBD::Pg installed
++++ Checking required modules for FS backend:
  File::Spec::Link installed
++++ Checking required modules for AFS backend:
  File::Spec::Link already checked
++++ Checking required modules for GFS backend:
  File::Spec::Link already checked
++++ Checking required modules for SMB backend:
  Filesys::SmbClient installed
++++ Checking required modules for RCS backend:
  Rcs installed
++++ Checking optional binaries:
  smbclient /usr/bin/smbclient
#### Summary:
All modules found.
All binaries found.
  3. WebDAV CGI has a new Web interface and some configuration defaults were changed and new options were added. See CHANGELOG in your installation path and take a look into webdav.pl for further information.

WebDAV CGI Setup

The WebDAV CGI can be easier upgraded if you use a configuration file instead of changing the setup section of webdav.pl.
  1. Create a /etc/webdav.conf with a minimal setup and don't forget to fix file permissions:
    chmod a+r /etc/webdav.conf: 
    ## the install base is needed to find webdav-ui.* and locale files 
## (don't forget the trailing slash):
$INSTALL_BASE = '/etc/webdavcgi/';

## the backend module (supported: FS, AFS, GFS, SMB, DBB, RCS, GIT):
$BACKEND = 'FS';

## this is an example if a user starts with home dir (http://mywebdavserver/ -> user home):
$VIRTUAL_BASE = '/';
$DOCUMENT_ROOT = '/home/'.$ENV{REMOTE_USER}.'/';
## if you use a complex home folder structure, try this:
# $DOCUMENT_ROOT=(getpwnam($ENV{REMOTE_USER}))[7].'/';


$DBI_SRC='dbi:SQLite:dbname=/tmp/webdav.'.$ENV{REMOTE_USER}.'.db';
$DBI_USER='';
$DBI_PASS=''; 
$CREATE_DB = !-e '/tmp/webdav.'.$ENV{REMOTE_USER}.'.db';
  2. Please take a look at backend specific configuration sections AFS, GFS, SMB/CIFS, DBB, RCS, GIT
  3. Set up your database
  4. If you need to change other options, take a look at etc/webdav.conf.complete
  5. Enable session or form-based authentication if needed.
  6. There are a lot of extensions to activate.
  7. Don't forget to check the config file syntax: perl -c /etc/webdav.conf
  8. configure your Apache web server

Hints

Apache and webdav.pl setup: Graphics::Magick does not compile:

Database Setup

Common Instructions

  1. Install the necessary Perl DBI driver (Debian/Ubuntu package: libdbd-...-perl)
  2. Create the database and the schema
  3. Configure WebDAV CGI ($DBI_SRC, $DBI_USER, $DBI_PASS)

SQLite 3

PostgreSQL

MySQL

UID/GID Wrapper

If you use the example wrapper (webdavwrapper.c, webdavwrapper-krb.c, webdavwrapper-afs.c) you should consider this: Attention: for AFS and/or Kerberos support you need webdavwrapper-afs.c or webdavwrapper-krb.c instead of webdavwrapper.c (see AFS Support section)

Folder Sharing / Group Access

There are two ways to share a folder between users of a group (not for AFS users - see AFS note below):
  1. Add all users to UNIX/Posix group (/etc/groups, a LDAP group, ...) - recommended:
    • create a group, e.g: groupadd GROUP
    • create a folder to share: mkdir SHAREDFOLDER
    • change the group: chgrp GROUP SHAREDFOLDER
    • set set-GID-flag to the folder and make it readable/executable/writeable for the group: chmod g+srwx SHAREDFOLDER
    • set the $UMASK parameter in your WebDAV CGI config file: $UMASK = 0002;
    Attention: You need a single database for all users to share WebDAV locks and properties. If you use a file based database like SQLite you have to use a singe file writable for all users.
  2. Use the UID/GID Wrapper to map all users to a common user:
    • create a common user, e.g.:adduser USER
    • create a folder to share: mkdir SHAREDFOLDER
    • change the owner: chown USER SHAREDFOLDER
    • set the WEBDAV_USER environment variable: add E=WEBDAV_USER:USER to your Apache rewrite rule option
AFS note: If you use AFS you have to use AFS groups and AFS ACLs to share folders instead of folder permissions because AFS ignores all Linux/UNIX permissions:
  1. Create a AFS group and add AFS users to the group.
  2. Set lookup, read, write, delete, insert, and lock rights for that group to the shared folder.
  3. Don't forget to set lookup rights for the AFS group to all upper folders.

Web interface

How to add a new translation

Since WebDAV CGI v1.1.2 there is a Localizer extension that helps you to translate all locale and online help files. Activate it by putting @DEV_EXTENSIONS or 'Localize' to your @EXTENSIONS setup (see extensions doc) in your webdav.conf. And you need write permissions for all locale and online help files, e.g. 

find /etc/webdavcgi/ -name locale -type d -exec chmod -R a+w {} \;
find /etc/webdavcgi/ -name help -type d -exec chmod -R a+w {} \;
This is an example to get access rights but it should only used if no other user has access to the installation. Alternatively, you can use access groups and putting the users to the group and give only the group write permissions, e.g. 
find /etc/webdavcgi/ -name locale -type d -exec chgrp -R mygroup {} \;
find /etc/webdavcgi/ -name help -type d -exec chgrp -R mygroup {} \;
find /etc/webdavcgi/ -name locale -type d -exec chmod -R g+w {} \;
find /etc/webdavcgi/ -name help -type d -exec chmod -R g+w {} \;
And to see your results you should delete temporary message files (rm /tmp/*msg) and put your language to the %SUPPORTED_LANGUAGES in your webdav.conf ($SUPPORTED_LANGUAGES{_my_locale_} = 'MyLanguage'; ) if necessary (or simply write ?lang=_my_locale_ behind the WebDAV CGI URL).

The old and simple way:

Copy the locale/webdav-ui_default.msg to locale/webdav-ui_<_my_locale_>.msg and translate all values (leave the keys unchanged; format: key "value").

The Simple view has a lot of extensions with locale files: /etc/webdavcgi/lib/perl/WebInterface/Extensions/*/locale/*.
And don't forget to sent me your translation. Thanx :-)

How to change CSS styles

There are many ways to do it:

How to add or change icons

Here are some examples to do that in the WebDAV CGI configuration file:

How to customize error messages/documents

Two HTTP status codes are supported for customized error documents: '404 Not Found' and '403 Forbidden'

You have to use '.html' or '.txt' extensions for your error documents to determine a correct MIME type.

  1. put your error documents to the $INSTALL_BASE/htdocs folder or wherever you want (should be readable by your users)
  2. add following options to your WebDAV CGI configuration file: 
    $ERROR_DOCS{'404 Not Found'} = "$INSTALL_BASE/htdocs/404.html";
$ERROR_DOCS{'403 Forbidden'} = "$INSTALL_BASE/htdocs/403.html";

Variable substitution in $HEADER, $SIGNATURE, $LANGSWITCH, and %ICONS

Following variables are substituted:
$CLOCKa clock with client time formatted with locale value for key 'vartimeformat'
$ENV{_VAR_}value of environment variable _VAR_
$LANGcurrent language code
$NOWcurrent date formatted with locale value for key 'varnowformat'
$PATH_TRANSLATEDlocale folder name corresponding to the request URI
$REQUEST_URIrequest URI without query string
$TIMEcurrent time formatted with locale value for key 'vartimeformat'
$TL{_KEY_}locale value for key _KEY_
$USERcurrent user id
$VBASEvirtual host base matching $VIRTUAL_BASE
$VHTDOCSvirtual htdocs path $VHTDOCS to the $INSTALL_BASE/htdocs

Performance

Security

HTTP Basic Authentication and Brute Force Attacks

The WebDAV protocol or most WebDAV clients supports only HTTP Basic authentication so you need it for WebDAV access.
  1. You can use the session.pl script of WebDAV CGI (see Session or form-based authentication) for your WebDAV access because the session authentication handler of WebDAV CGI has a pure brute force attack detection and prevention (BFAP). There are some options you can set in your webdav-session.conf to modify the behavoir of BFAP. The default setting allows only 3 login attempts within 10 seconds for a account: 
    $SESSION{bfap} = {
    # type of BFAP protection for counting login attempts  (0: disabled; 1: by user; 2: by user@IP; 3: by IP):
    # note: if you use NAT or a load balancer the REMOTE_ADDR environment variable is not useable so you should use value "2"
    type => 1,
    # number of allowed login failures before logon will be paused:
    failcount} => 3,
    # time range in seconds before the failcount will be reseted:
    failrange => 10,
    # delay in seconds to be paused after failcount was reached (only effective in session logon screen):
    delay => 10,
    # sleep for some seconds before login attempt (every (successful) logon will be delayed) (0 - disabled)
    sleep => 0,
    # sleep for random seconds before (successul) login attempt (0 - disabled; >0: range of seconds for random routine)
    randomsleep => 0,
    # sleep some seconds after failcount was reached:
    sleeponfail => 3,
};
  2. Or you can use a authentication module of your webserver. You should use
    • fail2ban
    • or mod_security (Apache only).

Temporary files and disk/memory space

WebDAV CGi creates a lot of temporary files: You should setup some monitoring and maintenance scripts to protect your server against running out of memory if temp is a RAM disk or a full (root) harddisk. It's possible to limit upload/download file sizes, to disable thumbnails, or to setup temporary folder directory.
© ZE CMS, Humboldt-Universität zu Berlin | Written 2010-2017 by Daniel Rohde