
DAVFS2 1.0.0 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 CACHE
    7 PARTICIPATION
    8 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 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. DAVFS2 does not handle different
WebDAV users 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).
If your distribution don't come with libneon you can get it from
http://www.webdav.org/neon/

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.sourceforge.net:/cvsroot/dav login
    Just hit Enter when asked for your password.
    $ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/dav checkout -r select-coda-version -P 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-1.0.0.tar.gz

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

- 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:
    --------
    
    --enable-debug
    --enable-debug=secrets
        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.
        The second form also writes your username and password into the
        log files. This is rarely useful.
        
    --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'.
        
    ./configure --help will show all available options.
        
- 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 directory.
    Note: 'mount.davfs' will be setuid!

- Get rid of the root permissions.


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

Now you have optained and unpacked the binary package of DAVFS2 and changed
into directory 'davfs2-1.0.0-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 configuration file)
- 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-1.0.0-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/

documentation:
--------------
Create directory '/usr/local/share/davfs2'and copy into this directory:
- BUGS
- ChangeLog
- COPYING
- davfs2.conf.template
- FAQ
- GPL
- NEWS
- README
- secrets.template
- THANKS
- TODO

System wide configuration:
--------------------------
Create a directory /etc/davfs2 and copy davfs2.conf and secrets into this
directory. They are intended for system wide configuration and you may
edit them according to your needs. 

Per user configuration:
-----------------------
When invoked the first time by an user, mount.davfs will create an hidden
directory .davfs2 in the users home directory and populate it with default
configuration files. While there is no need to edit davfs2.conf in most cases,
it is recommended to use the secrets file for credentials.


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

- Read our fine manual.

- 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 some time before the daemon terminates, because there
      maybe files that have to be stored back to the server.

Note: It is not necessary to create ~/.davfs2 and it's content manually.
  mount.davfs will create it when invoked the first time. As there is no
  secrets file at this time, you will be asked for username and password.


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

There are two reasons for chaching:
- HTTP and WebDAV is intended to transfer complete files and the coda kernel
  module expects a local copy to act on
- Many applications, especially thos with graphical user interfaces, think
  of file system calls as cheap an quick, which is not true when using a slow
  conection to the internet. Some graphical interfaces for file handling even
  open every file in every directory they list, forcing davfs2 to download them
  from the server.

To avoid excessive network traffic davfs2 now saves all downloaded files in a
cache directory and will hold this files, even when the file system is
unmounted. When the same file system is mounted again, it will reuse this
cached files.

To avoid inconsistencies, davfs2 will do a conditional GET whenever a file is
opened (it will ask the server if there is a newer version, and download only
if there is).

Many application use temporary files that will be deleted just after they have
been closed. So whenever a file is newly created or changed, davfs2 will wait
until it is closed and then wait another 10 seconds before it will upload the
changed version to server. This saves a lot of uneccessary traffic, but the
strategy still has to be enhanced. If there are many files to be uploaded (e.g.
after copiing a directory) mount.davfs may block quite some time, as it will
upload alll the files in one block, and only respond to file system calls, when it
is ready.


7 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


8 KNOWN ISSUES
==============

- mount.davfs will accept certificates of servers only if there is a
  matching CA-certificate in the systems certificate store. If not it will
  present the fingerprint and ask you. You should only accept the crtificate
  if you know the fingerprint. If you use a server with self signed certificate
  you may copy it into the systems certificate store. But you will need some
  more information about certificates and the TLS/SSL implementation on your
  system to do this in a secure way.

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