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 - (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 libdatetime-format-human-duration \
                
    
    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:
    perl -MCPAN -e "install Env::C"
    
    
  3. install additional binaries/packages for a better WebDAV CGI experience:
    • Speedy - increases the performance of WebDAV CGI (Debian/Ubuntu package: speedy-cgi-perl)
    • 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-get install speedy-cgi-perl ghostscript
    
    ## only for SMB backend users:
    apt-get install smbclient
    
    ## only for SMB and AFS backend users:
    apt-get install krb5-user
    
    ## for ODFConverter extension:
    apt-get install libreoffice
    
    
    ## Gentoo quick install:
    emerge -va dev-perl/SpeedyCGI
    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. change directory to your preferred installation path, e.g. cd /etc
  5. install WebDAV CGI:
    • unzip webdavcgi-latest.zip or tar jxf webdavcgi-latest.tar.gz2 (Gentoo: emerge -va www-apps/webdavcgi)
    • or checkout from subversion: svn checkout svn://svn.code.sf.net/p/webdavcgi/code/trunk webdavcgi
  6. change directory to the source base (e.g: cd webdavcgi*) and call bash install.sh to compile all wrappers and to fix file permissions
  7. configure webdav.pl
  8. 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.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

Speedy Support

Speedy or PersistentPerl allows you to increase the request/response speed of WebDAV CGI. WebDAV CGI is up to 7 times faster with Speedy than without.
Setup:
  1. Install Speedy (Debian/Ubuntu: apt-get install speedy-cgi-perl)
  2. Change the shebang of webdav.pl:
    OLD: #!/usr/bin/perl
    NEW: #!/usr/bin/speedy -- -r50 -M10 -t3600
    
    The -r50 limits the requests per Speedy process. This is necessary because Perl runs out of memory (you can set it higher but watch your Apache error log). The -M10 limits the count of Speedy processes (see man speedy). If you do not use a setuid/setgid wrapper (e.g. if you use the SMB backend) you should remove the -M10 or set it higher because all your clients using the same Speedy processes and you need one Speedy process per request. The -t3600 sets the timeout for a idle Speedy process to one hour.
  3. Only for the SMB backend:
    1. Add E=TICKET_LIFETIME:28800 to your RewriteRule:
      RewriteRule ^/ /webdavcgi [PT,L,E=WEBDAVCONF:/etc/webdav.conf, \
                                      E=PERLLIB:/etc/webdavcgi/lib/perl, \
                                      E=TICKET_LIFETIME:21600]
      

      The ticket (renewal) lifetime depends on your domain controller setup (Kerberos policy of your domain group policy). You can check it (Debian/Ubuntu: apt-get install krb5-user):
      kinit mydomainaccount@MY.EXAMPLE.DOMAIN.ORG
      klist
      
    2. Change the Apache script aliases:
      OLD: ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/webdav.pl
      NEW (with mod_auth_kerberos): ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/webdavwrapper-smb 
      NEW (without mod_auth_kerberos): ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/smbwrapper
      
          
    3. Known issue: every request creates a new service ticket therefore the file size of ticket cache file grows for every request; Solution: reduce the TICKET_LIFETIME to reduce the temporary file space consumption
  4. That's all and don't forget to check the notes below.
Notes:
© ZE CMS, Humboldt-Universität zu Berlin | Written 2010-2017 by Daniel Rohde