WebDAV CGI - Documentation: Backends

Content of this topic:

AFS Support
GFS Support
SMB/CIFS Support
DBB database backend
GIT backend
RCS backend
Read-only backend RO
Amazon S3 browser backend S3B

AFS Support

WebDAV CGI can be used as a Web frontend for AFS and as a WebDAV-AFS bridge. It's a complete replacement for filedrawers.

Please choose your installation variant:

without mod_perl (maybe with Speedy CGI) and without mod_auth_kerberos (recommended)
without mod_perl (maybe with Speedy CGI) and with mod_auth_kerberos and mod_waklog
with mod_perl with or without mod_auth_kerberos/mod_waklog (recommended if Speedy CGI is not available)

... without mod_auth_kerberos (recommended)

Requirements:

OpenAFS client installed on your server (Debian/Ubuntu package: openafs-client) and configured with a default realm: /etc/krb5.conf: default_realm = MY.DOMAIN.NAME (kinit <uid_without_domain> ; aklog should work)
Kerberos client tool kinit (Debian/Ubuntu package: krb5-user)
All users should be visible for the system and have the same password for AFS and your authentication facility like LDAP, RADIUS,... to authenticate your users with kinit and to allow setuid/setgid: getent passwd <uid> should work
The AUTHHEADER environment variable with the HTTP Authorization header value has to be passed to the wrapper: see RewriteRule of the Apache config example.
The TICKET_LIFETIME environment variable value should be a little bit smaller than your Kerberos ticket lifetime.
cgi-bin/webdavwrapper-afs (call bash install.sh from your installation directory to compile helper/webdavwrapper-afs.c)
Replace the pagsh with a bourne shell in the afswrapper script to improve performance and avoid trouble with PAG limits:
sed -i -e 's@^#!/usr/bin/pagsh@#!/bin/sh@' cgi-bin/afswrapper

Apache example:

<Location /webdavcgi>
	AuthName "WebAFS"
	AuthType Basic
	Require valid-user
</Location>

ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/webdavwrapper-afs
# ScriptAlias /logout /etc/webdavcgi/cgi-bin/logout
RewriteEngine on
# RewriteRule ^/logout - [L]
RewriteRule ^/ /webdavcgi \
	[PT,L,E=WEBDAVCONF:/etc/webdav.conf,E=PERLLIB:/etc/webdavcgi/lib/perl,E=AUTHHEADER:%{HTTP:Authorization},E=TICKET_LIFETIME:82800]

/etc/webdav.conf example: see next section

... with mod_auth_kerberos

Requirements:

mod_auth_kerberos installed (Debian/Ubuntu package: libapache2-mod-auth-kerb)
a keytab file for your server (service name: HTTP/<YOUR SERVER NAME>@<YOUR DOMAIN>, e.g. HTTP/webafs.cms.hu-berlin.de@CMS.HU-BERLIN.DE)
OpenAFS client installed on your server (Debian/Ubuntu package: openafs-client) and configured (kinit ...; aklog should work)
The TICKET_LIFETIME environment variable value should be a little bit smaller than your Kerberos ticket lifetime.
cgi-bin/webdavwrapper-afs (call bash install.sh from your installation directory to compile helper/webdavwrapper-afs.c)

Apache example:

KrbMethodNegotiate off
KrbMethodK5Passwd on
KrbSaveCredentials on
Krb5Keytab /etc/webafs.keytab

<Location /webdavcgi>
	AuthName "WebAFS"
	AuthType Kerberos
	Require valid-user
</Location>

ScriptAlias /webdavcgi /etc/webdavcgi/webdavwrapper-afs
RewriteEngine on
RewriteRule  ^/ /webdavcgi \
		[PT,L,E=WEBDAVCONF:/etc/webdav.conf,E=PERLLIB:/etc/webdavcgi/lib/perl,E=TICKET_LIFETIME:82800]

/etc/webdav.conf example:

$INSTALL_BASE = '/etc/webdavcgi/';

$BACKEND = 'AFS';

$DOCUMENT_ROOT = '/afs/';
$VIRTUAL_BASE='/';

$DBI_SRC='dbi:SQLite:dbname=/tmp/webdav.'.$ENV{REMOTE_USER}.'.db';
$DBI_USER='';
$DBI_PASS=''; 
$CREATE_DB = !-e '/tmp/webdav.'.$ENV{REMOTE_USER}.'.db';

$BACKEND_CONFIG{AFS}{quota}='/usr/bin/fs listquota $FS';

$BACKEND_CONFIG{AFS}{fsvlink}= { '/afs/' => { home => '/afs/.cms.hu-berlin.de/user/'.substr($ENV{REMOTE_USER},0,1).'/'.$ENV{REMOTE_USER}}}; 

@EXTENSIONS = (@DEFAULT_EXTENSIONS,@EXTRA_EXTENSIONS,@AFS_EXTENSIONS);
$EXTENSION_CONFIG{AFSACLManager} = { allow_afsaclchanges =>1 };
$EXTENSION_CONFIG{AFSGroupManager} = { disallow_groupchanges=>0 };

$ALLOW_SEARCH = 0;
$ALLOW_CHANGEPERM = 0;


$MIMEFILE='/etc/mime.types';

GFS Support

The GFS backend replaces only the quota command. Requirements:

a mounted GFS filesystem
gfs_quota command executable by a user

/etc/webdav.conf example:

$INSTALL_BASE = '/etc/webdavcgi/';

$BACKEND='GFS';

$DOCUMENT_ROOT = '/mygfsmountpoint/';
$VIRTUAL_BASE = '/';
 
$DBI_SRC='dbi:SQLite:dbname=/tmp/webdav.'.$ENV{REMOTE_USER}.'.db';
$DBI_USER='';
$DBI_PASS=''; 
$CREATE_DB = !-e '/tmp/webdav.'.$ENV{REMOTE_USER}.'.db';

$BACKEND_CONFIG{GFS}{quota}='/usr/sbin/gfs_quota -f';

SMB/CIFS Support

The SMB backend supports Kerberos and username/password/workgroup authenticated file share access.

Please choose your installation variant:

with mod_perl and with Kerberos authentication (recommended)
with mod_auth_kerberos and Kerberos authentication
without mod_auth_kerberos but with Kerberos authentication
with username/password/workgroup authentication

... with mod_auth_kerberos

Requirements:

maybe a Active Directory integrated Windows or Samba file server
mod_auth_kerberos installed (Debian/Ubuntu: libapache2-mod-auth-kerb)
a keytab file for the kerberos module:
1. create a Windows/ADS user account with a good password (e.g. exampleuser)
2. disable password change requirements (policies) for your Windows/ADS user account
3. create a keytab file as a domain admin on your domain controller:
```
C:>ktpass -princ HTTP/my_www_server_name@MY.EXAMPLE.DOMAIN.ORG -mapuser exampleuser@MY.EXAMPLE.DOMAIN.ORG -pass MySeCreTexampleuserPassw0rd -out keytab.HTTP
```
4. copy the keytab file keytab.HTTP to a Web server path, e.g. /etc/keytab.HTTP
Filesys::SmbClient perl module installed (Debian/Ubuntu package: libfilesys-smbclient-perl)
optional the /usr/bin/smbclient binary for quota information (Debian/Ubuntu package: smbclient)
You must not use a setuid/setgid wrapper because mod_auth_kerberos creates a ticket cache file and the WebDAV CGI script needs read rights for the Kerberos ticket cache.
You need a wrapper if you use Speedy (see Speed Support section) because the SMB backend needs a fresh Kerberos ticket.
enough temporary file space for thumbnails and ZIP upload/download

Apache example:

ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/webdav.pl

KrbVerifyKDC off
KrbMethodNegotiate on
KrbMethodK5Passwd on
KrbAuthoritative on
KrbServiceName HTTP
Krb5Keytab /etc/keytab.HTTP
# required:
KrbSaveCredentials on
KrbAuthRealms MY.EXAMPLE.DOMAIN.ORG MYSECOND.EXAMPLE.DOMAIN.ORG

AuthType Kerberos
AuthName "MY.EXAMPLE.DOMAIN.ORG Account"
Require valid-user

RewriteEngine on
RewriteRule  ^/ /webdavcgi [PT,L,E=WEBDAVCONF:/etc/webdav.conf,E=PERLLIB:/etc/webdavcgi/lib/perl]

/etc/webdav.conf example: see next section

... without mod_auth_kerberos but with Kerberos authentication

Requirements:

a Active Directory integrated Windows or Samba file server
a Apache authentication provider like auth_n_file, mod_authnz_ldap, ... with the same users and synchronized passwords
a Kerberos configuration file (/etc/krb5.conf) with a default_realm
Filesys::SmbClient perl module installed (Debian/Ubuntu package: libfilesys-smbclient-perl)
optional the /usr/bin/smbclient binary for quota information (Debian/Ubuntu package: smbclient)
Kerberos client tool kinit (Debian/Ubuntu package: krb5-user)
the cgi-bin/smbwrapper script (Speedy compatible): the TICKET_LIFETIME (in seconds) should be a little bit smaller than your Kerberos ticket lifetime
enough temporary file space for thumbnails and ZIP upload/download

Kerberos configuration example: /etc/krb5.conf:

[libdefaults]
        dns_lookup_realm = true
        dns_lookup_kds = true
        default_realm = MY.EXAMPLE.DOMAIN.ORG
        clockskew = 900
        forwardable = true
        proxiable = true
        allow_weak_crypto = yes
[domain_realms]
	my.example.domain.org = MY.EXAMPLE.DOMAIN.ORG
	.my.example.domain.org = MY.EXAMPLE.DOMAIN.ORG

Apache example:

ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/webdav.pl

AuthType Basic
AuthName "MY.EXAMPLE.DOMAIN.ORG Account"
Require valid-user

RewriteEngine on
RewriteRule ^/ /webdavcgi \
		[PT,L,E=WEBDAVCONF:/etc/webdav.conf,E=PERLLIB:/etc/webdavcgi/lib/perl,E=AUTHHEADER:%{HTTP:Authorization},E=TICKET_LIFETIME:21600]

/etc/webdav.conf example:

$INSTALL_BASE = '/etc/webdavcgi/';

require Helper::Krb5AuthHelper;
Helper::Krb5AuthHelper->new();

$DOCUMENT_ROOT = '/';
$VIRTUAL_BASE = '/';

$BACKEND='SMB';

$DBI_SRC='dbi:SQLite:dbname=/tmp/webdav.'.$ENV{REMOTE_USER}.'.db';
$DBI_USER='';
$DBI_PASS=''; 
$CREATE_DB = !-e '/tmp/webdav.'.$ENV{REMOTE_USER}.'.db';

$SHOW_QUOTA = -x '/usr/bin/smbclient';
$ALLOW_CHANGEPERM = 0;
$ALLOW_SYMLINK = 0;

#### SMB backend setup:
### required entries: defaultdomain, domains, fileserver
### optional entries: sharefilter, usersharefilter, shares, sharealiases
$BACKEND_CONFIG{SMB} = {
  defaultdomain => 'MY.EXAMPLE.DOMAIN.ORG',	#required

  ## allow only configured server names and shares (default: 0)
  secure => 1, # optional

  ## a global share filter (filter out admin shares with trailing $):
  sharefilter => [ qr/\$$/, ],  #optional

  usersharefilter => {  #optional
    ## admin has no matching filter so he can see all shares (overwrites sharefilter):
    myadminexample => [ qr/__NEVER_MATCH/, ],
  }, 

  sharesep => '~', #optional - servername-share separator symbol (default: '~')
  ## don't use a separator symbol like '$', '-', '_', '#', '%', '?', '&', '/', '\', or letters/numbers
  ## good alternative separators are '!', ':', '=', '\'', '"', '`', '+', '*', or '@'

  ## enables/disables quota support for all domains and shares:
  quota => 1, # optional

  domains => { #required
    'MY.EXAMPLE.DOMAIN.ORG' => {	#required (multiple domain entries allowed for forrests)
      ## a domain based filter (overwrites sharefilter and userfilter above):
      sharefilter => [ qr/\$$/, ],	#optional
      usersharefilter => {		#optional
        ## a domain based user filter (overwrites all sharefilter and global filter):
        myadminexample => [ qr/__NEVER_MATCH/, ], 
      }, 
      fileserver => {			#required
        'mywindowsfileserver1.my.example.domain.org' => {	#required

          ## a fileserver based share filter (overwrites all domain based filter):
          sharefilter => [ qr/\$/, ],	#optional

          usersharefilter => {		#optional
            ## overwrites all sharefilter and domain based filter
            myadminexample => [ qr/__NEVER_MATCH/ ] 
          }, 

          ## disables all filter and (slow) automatic share detection:
          shares => [ 'MyFirstShare', 'MySecondShare', 'MyThirdShare/start/here' ],	#optional
          
          ## enables/disables quota support for given shares:
          quota => { 'MyFirstShare' => 0 }, # optional

	  ## defines a initial directory for a share (don't forget the initial '/'):
	  initdir => { 			#optional
	  	'MyFirstShare' => '/starthere', 
		'MySecondShare'=> '/start/here' 
	  },

          sharealiases => {		#optional
            ## shows 'H: (Home)' instead of 
            ## 'mywindowsfileserver1.my.example.domain.org~MyFirstShare' in the Web interface
            'MyFirstShare' => 'H: (Home)/',
            ## shows 'S: (Scratch)' instead of 
            ## 'mywindowsfileserver1.my.example.domain.org~MySecondShare' in the Web interface
            'MySecondShare' => 'S: (Scratch)/',
	    'MyThirdShare/start/here' => 'T: Temp (/start/here/)',
          },
        },
      },
    },
  },
};

... with username/password/workgroup authentication

Requirements:

a Windows or Samba file server
a Apache authentication provider like auth_n_file, mod_authnz_ldap, ... with the same users and synchronized passwords
optional the /usr/bin/smbclient binary for quota information (Debian/Ubuntu package: smbclient)
the cgi-bin/smbwrapper script (Speedy compatible)
enough temporary file space for thumbnails and ZIP upload/download

Apache example:

ScriptAlias /webdavcgi /etc/webdavcgi/cgi-bin/smbwrapper

AuthType Basic
AuthName "Workgroup Account"
Require valid-user

RewriteEngine on
RewriteRule ^/ /webdavcgi \
		[PT,L,E=WEBDAVCONF:/etc/webdav.conf,E=PERLLIB:/etc/webdavcgi/lib/perl,E=AUTHHEADER:%{HTTP:Authorization},E=SMBWORKGROUP:Workgroup]

/etc/webdav.conf example: see previous section

DBB database backend

The DBB backend module is an example module. It shows the possibility to put all your data to your own backend and not only to file systems.

Features:

puts all data to a single database table (binaries too)
the required database table will be created by the backend

Requirements:

a database driver (DBD perl module; by default SQLite; Ubuntu/Debian package: libdbd-sqlite3-perl)

/etc/webdav.conf example:

$INSTALL_BASE='/etc/webdavcgi/';
$VIRTUAL_BASE = '/';
$DOCUMENT_ROOT='/';


$DBI_SRC='dbi:SQLite:dbname=/tmp/webdav.'.$ENV{REMOTE_USER}.'.db';
$DBI_USER='';
$DBI_PASS=''; 
$CREATE_DB = !-e '/tmp/webdav.'.$ENV{REMOTE_USER}.'.db';

$THUMBNAIL_CACHEDIR="/tmp";

$ALLOW_CHANGEPERM = 0;
$ALLOW_SYMLINK = 0;

$BACKEND = 'DBB';

$BACKEND_CONFIG{DBB} = {
	dsn => 'dbi:SQLite:dbname=/tmp/webdavcgi-dbdbackend-'.$ENV{REMOTE_USER}.'.db',
	username => '',
	password => '',
};

GIT backend

The GIT backend is a showcase for a revision controlled backend. It is derived from the FS backend and so it works only with local file systems.

Requirements:

a git binary (Debian/Ubuntu package: git)

How it works:

It initializes the document root with git init and adds existing files if necessary.
The git directory .git is hidden for all users.

/etc/webdav.conf example:

...
$BACKEND = 'GIT';

$BACKEND_CONFIG{GIT} = {
	## path to git command  (default: /usr/bin/git):
	gitcmd => '/usr/bin/git',

	
	## path to a lockfile (default: /tmp/webdav-git.lock) 
	## it have to be writable by all users using the git repo:
	lockfile => '/tmp/webdav-git.lock',
};
...

RCS backend

The RCS backend is a showcase for a revision controlled backend. It needs another backend like FS, or SMB to work because it's a simple backend wrapper.

How it works:

only files are under revision control
the backend creates a revision file with RCS for any uploaded file
a revision file is stored in the rcsdirname folder (e.g. .rcs/test.txt,v) relative to the folder of a file
the RCS backend creates a virtual folder structure (rcsdirname/virtualrcsdir) with revision files, rcs log entries, and revision comparision (diff)
revisions, logs, and diffs are located under rcsdirname/virtualrcsdir/filename/ (e.g. .rcs/RCS/test.txt/)

Known issues:

if you copy or move files over existing files the overwritten files and revisions are lost
if you delete a folder all containing revisions and files are deleted and lost

Requirements:

Rcs Perl module (Debian/Ubuntu package: librcs-perl)
rcs binaries (Debian/Ubuntu package: rcs)
another backend like FS, GFS, AFS, DBB, or SMB and don't forget to configure the other backend
a little bit temporary space for all RCS operations (ci, co, rcsdiff, rlog, zip download)

/etc/webdav.conf example:

...
$BACKEND = 'RCS';

$BACKEND_CONFIG{RCS} = {
        ## backend used for versioning:
        backend=>'FS',                  # required 

        ## relative path in a directory for revision files 
	## (slashes are not allowed):
        rcsdirname=>'.rcs',             # required

        ## RCS binary path:
        bindir=>'/usr/bin',             # required

        ## a relative virtual path in 'rcsdirname' to access 
	## all revisions, logs and diffs of a file 
	## (slashes are not allowed):
        virtualrcsdir=>'REVISIONS',     # required

	## limits the number of revisions for a file:
	## note: maxrevisions includes the current revision that means:
	## you have to set maxrevisions to 4 if you need access to 3 old revisions
	# maxrevision=>31,              # optional

        ## ignore suffixes (check is case insensitive):
        # ignoresuffixes => [ 'jpg', 'gif', 'png', ],  # optional

        ## allowed suffixes (check is case insensitive):
        # allowedsuffixes => [ 'txt', 'html' ],        # optional

        ## ignore filenames (check is case insensitive):
        # ignorefilenames=> [ '.*~'],   # optional

};
...

Read-only backend RO

The RO backend is a backend wrapper for all other backends and allows only read access to files and folders.

webdav.conf example:

...
$BACKEND='RO';
$BACKEND_CONFIG{RO}{backend} = 'FS';
...

Amazon S3 browser backend S3B

The S3B backend is a simple Amazon S3 browser. It is tested only with Ceph Rados S3 gateway and supports:

buckets: create, delete
files: upload, download, rename, delete, copy, move

Requirements:

the Amazon::S3 perl module (Debian/Ubuntu: perl -MCPAN -e 'install Amazon::S3'
a access id and secret key for S3 (compatible) storage like Ceph Rados gateway

/etc/webdav.conf example:

...
$BACKEND='S3B';
$BACKEND_CONFIG{S3B} = {
        access_id => '[myaccessid]',   # required
        secret_key => '[mysecretkey]', # required
        host => '[myradosservername]', # optional, default: s3.amazonaws.com
        bucketprefix => '[myaccessid][separator like "-"]', # optional, default: undefined (useful for a Ceph Rados gateway with a required access id in a bucket name)
        secure => 1, # optional, 1: https, 0: http, default: 0
        retry => 1,  # optional, default: 0 
        timeout=>2,  # optional, default: 0
};
...