DAVFS2 0.2.4 README
===================

    1 INTRODUCTION
        1.1 WHAT DAVFS2 IS INTENDED FOR
        1.2 WHAT DAVFS2 IS NOT INTENDED FOR
    2 SECURITY CONSIDERATIONS
    3 INSTALLATION
        3.1 PREREQUISITE
        3.2 INSTALLATION FROM CVS SOURCES
        3.3 INSTALLATION FROM SOURCE PACKAGE
        3.4 INSTALLATION FROM BINARY PACKAGE
    4 MOUNTING
    5 TLS / SSL
    6 PARTICIPATION
    7 KNOWN ISSUES
    
    
1 INTRODUCTION
==============

DAVFS2 is a Linux file system driver that allows you to mount a WebDAV
resource into your unix file system tree. So - and that is what makes
DAVFS2 different - applications can use it without knowing about WebDAV.
You may edit WebDAV resources using standard applications that interact
with the filesystem as usual.

DAVFS2 supports SSL and proxy. But client certificates are not yet supported.

1.1 WHAT DAVFS2 IS INTENDED FOR
-------------------------------

- If you have documents you want to access from different locations, store
  them on a WebDAV server accessible via internet. Mount them with DAVFS2
  from wherever you want.
  
- Use a WebDAV server as workspace for a geographically distributed work group.

- A web site may be made accessible to the developers via WebDAV. So they
  can mount with DAVFS2 and edit the site in place.

1.2 WHAT DAVFS2 IS NOT INTENDED FOR
-----------------------------------

DAVFA2 is not intended as a replacement for distributed file systems like
nfs, coda, cifs and similar.

When DAVFS2 mounts a resource it authenticates with the server using the
username and passward it got from the mounting user. All requests to the
server are done on behalve of this WebDAV user (or principal, as a WebDav
server likes to call its esteemed users). DAVFS2 does not handle different
principals within one mount. But this would be required for a distributed
file system.


2 SECURITY CONSIDERATIONS
=========================

To allow non-root users mounting of WebDAV resources, mount.davfs is run
setuid. To prevent unexperienced (or even malicious) users from intruducing
dangerous content into system directories or other users home directory,
the administrator must have control over user mounts.

- Non-root users can only mount using the normal mount program. There must
  also be an entry in /etc/fstab. This can only be done by root.

- To mount a WebDAV resource users must be member of group 'users'. The
  administrator may use groupmembership to allow or disallow mounting
  of WebDAV resources.

mount.davfs starts with effective user-id 'root' to be able to mount. After
mounting it changes its id permanently to that of the mounting user. This
will reduce the risks that are allways present when a daemon is connected
to the internet. So avoid mounting WebDAV resources as root.


3 INSTALLATION
==============

3.1 PREREQUISITE
----------------

DAVFS2 uses the neon libraries for communication with the server.
libneon (>= 2.4) must be installed. Your distribution will most likely
provide a package (e.g. Debian: libneon24).
If you want to compile DAVFS2 you also need the neon header files
(e.g. Debian: libneon24-dev).
You also need an XML-parser. But this should be handled by the neon
packes.
If your distribution don't come with libneon you can get it from
http://www.webdav.org/neon/

libneon uses OpenSSL for TLS/SSL connections. So OpenSSL has to be
installed on your system too.

Your kernel needs coda file system. Depending on your kernel you might
have to load module 'coda' or configure your system to load it at startup.

3.2 INSTALLATION FROM CVS SOURCES
---------------------------------

- Get the sources from CVS (reading this you may just have done):
    $ cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/dav login
    Just hit Enter when asked for your password.
    $ cvs -d:pserver:anonymous@cvs.sf.net:/cvsroot/dav checkout davfs2
    The sources should now be in a directory named "davfs2".

- Change into the directory 'davfs2'.

- Run the 'autogen.sh' script. This will create the configure script (et al).
    $ ./autogen.sh

- Proceed with Installation from Source Package.

3.3 INSTALLATION FROM SOURCE PACKAGE
------------------------------------

- Get the source package (if you don't have the sources allready) from
  http://sourceforge.net/projects/dav/ and untar.
    $ tar -xzf davfs2-0.2.7.tar.gz

- Change in the directory 'davfs2-0.2.7' or whatever we named it.
    $ cd davfs-0.2.7

- Run the configure script (from within directory 'davfs2').
    $ ./configure [options]
    This will test your system and finally create the appropriate Makefile.
    You may add some options, but hopefully will not have to.
    
    Options:
    --------
    
    --with-debug
        mount.davfs will write a lot of debug message into some log-file
        (e.g. Debian: /var/log/debug) and slow down. So you should only
        use for debuggng (sic!). But this debug messages are much liked,
        when they come in bug reports.
        
    --with-kernel-src=<path-to-kernel-source>
        e.g. --with-kernel-src=/usr/src/kernel-source-XXX
        Compiling against kernel-headers is a higly appreciated source of
        confusion, with different kernels and kernel-headers spread widely
        over your file system. So first try without and hope your distribution
        has located the matching headers at the matching location. But if you
        compiled your custom kernel you may need this.
        
    --with-group=<groupname>
        Users must belong to group <groupname> to be able to mount a
        davfs2 file system. <groupname> defaults to 'users'. But you may change
        this in order to have better control of who is allowed to mount.

    --prefix=<prefix>
        Defines the directory where davfs2 will be installed. It defaults to
        '/usr/local'. If your sources came with your distribution it may
        be '/usr'.
        
- Run make (from within directory 'davfs2').
    $ make
    This will compile the program.

- Gain root permissions and run make install (from within directory 'davfs2').
    # make install
    This will copy all the files in the appropriate directories.
    Note: 'mount.davfs' will be setuid!

- Get rid of the root permissions.

'mount.davfs' is usually invoked by 'mount' which will expect its helper
applications in '/sbin'. make install will create a symbolic link to
the mount.davfs binary in /sbin. If the install script failed, you will
have to do it yourself:
    e.g. if your binary is in '/usr/local/sbin' (default):
    # cd /sbin
    # ln -s /usr/local/sbin/mount.davfs mount.davfs


3.4 INSTALLATION FROM BINARY PACKAGE
------------------------------------

Now you have optained and unpacked the binary package of DAVFS2 and changed
into directory 'davfs2-0.2.7-bin-i386'. You will find the following files:

- mount.davfs (the executable binary)
- README (this file)
- mount.davfs.8.gz (the man page)
- davfs2.conf (a template file to configure the proxy)
- secrets (a template file to store credentials)

As this programm is not part of your distribution, most of the files will have
to go somewhere beneath /usr/local. After you have installed all the necessary
files you may delete the directory 'davfs2-0.2.7-bin-i386'.

The binary:
-----------
mount.davfs must be copied into '/usr/local/sbin'. Maybe you will have to
create this directory first. The file must be owned by root, group root, and it
must have the setuid-bit set. As mount.davfs will be invoked by the mount
program, which expects it to bin in /sbin, you will also have to create a
symbolic link in /sbin.
    # cp mount.davfs /usr/local/sbin/
    # chown root.root /usr/local/sbin/mount.davfs
    # chmod 4755 /usr/local/sbin/mount.davfs
    # ln -s /usr/local/sbin/mount.davfs /sbin/mount.davfs

The manpage:
------------
The manpage 'mount.davfs.8.gz' has to go into '/usr/local/share/man/man8/'.
Maybe you will have to create this directory first.
Owner and mode: root.root 644.
    # cp mount.davfs.8.gz /usr/local/share/man/man8/

Directory for PID file:
-----------------------
Every running mount.davfs programm will maintain a PID file in
'/var/run/mount.davfs'. You will have to create this directory. As
'mount.davfs' runs with the ID of the mounting user, this directory must be
writable for group 'users' and it must have the sticky bit set.
Owner: root.users.
    # mkdir /var/run/mount.davfs
    # chown root.users /var/run/mount.davfs
    # chmod 1774 /var/run/mount.davfs
    
README, davfs2.conf and secrets:
--------------------------------
You may copy this files to '/usr/local/share/davfs2', after you have created
this directory, for further use.

System wide configuration:
--------------------------
If all users have to use the same proxy you should copy 'davfs2.conf' into
'/usr/local/etc/davfs2' and edit it accarding your proxy settings.

If all users may use the same credentials for the proxy or some WebDAV server
(this will usually not be the case) you may copy the 'secrets' file into
'/usr/local/etc/davfs2' too and edit it. Make shure it is owned by root, group
root, and has file mode 600. mount.davfs will not accept it otherwise, for
security reasons.

Per user configuration:
-----------------------
Every user should create a hidden directory '.davfs2' in his home directory
and copy 'davfs2.conf' and 'secrets' into this directory and edit them. See
MOUNTING, the manpage and the comments in the files for further information
on this.


4 MOUNTING
==========

- Read our fine manual, now that we have got one.

- Create a hidden directory '.davfs2' in your home directory

- Copy file 'secrets.template' from '/usr/local/share/davfs2' (or
  '/usr/share/davfs2' into directory '~/.davfs2'.

- Change its name to 'secrets' and file mode to 600.

- Edit a line in 'secrets' like
  https://foo.bar/myfolder     myname    mypassword

- Ask root to make an entry in '/etc/fstab' like
  https://foo.bar/myfolder   /home/me/dav   davfs   user,noauto   0   0

- Now mount
    $ mount /home/me/dav

- To unmount
    $ umount /home/me/dav
    Note: It may take up to 15 seconds until the daemon terminates.


5 TLS / SSL
===========

The key question when using TLS/SSL is whether you can trust in the certificate
the server presents. There is no gain in security when you use strong
encryption for your communication with an attacker.

DAVFS uses OpenSSL (via the Neon library) for TLS. OpenSSL comes with the
certificates of a great deal of the well known Certifacte Authorities. You may
find them in /etc/ssl/certs (but this may be distribution dependent). If a
WebDAV server presents a certificate that is issued by one of these Certificate
Authorities it can verifiy and accept it without user intervention.

If the server certificate is not issued by one of these well known Certificate
Authorities mount.davfs will present subject, issuer and fingerprint of the
certificate to you and ask whether to accept or not. You should only accept if
you really can verify the fingerprint. This usually means you have got the 
fingerprint from the administrator of this server.

For testing purposes, private use and servers that are intended for use by a
limited group of users, it is common practice to use "self signed certificates".
In this case make shure you distribute the fingerprint (on paper) among the
the users so that they don't feel the need to accept a certificate allthough
they can't really verify it.

At the moment it is not possible to store these certificates permanently, but
you will be prompted every time you connect. This feature is intended for one
of the next releases.

If you are used to OpenSSL you may also create your private Certificate
Authoritiy and distribute its certificate amongst the users for storage in
the system wide certificate store. But this is not a trivial matter and you
should know what you are doing (also think of certificate revocation!).


6 PARTICIPATION
===============

  DAVFS is an Open Source project, and we welcome your participation.
  Please join developer mailing list
      dav-linuxfs@lists.sf.net
  For cvs commit info, join
      dav-checkins@lists.sf.net


7 KNOWN ISSUES
==============

- Some WebDAV servers don't allow to move files within a directory. But
  some programs (e.g. gedit) trust on this.

- Many applications create temporary files, some create many temporary
  files. As this files will be created on the server, this may slow
  down this applications. You may try to configure these applications
  to use local directories for temporary files.

- davfs2 does not manipulate file properties on the server. It leaves this
  to the server. But it tries to retrieve important information from the
  server. But this may sometimes produce curious results for newly created
  files.

- davfs2 can not calculate the free disk space on the server. But some
  applications (e.g. nautilus) insist on this. So davfs can't help but lie.
