2007-04-26
----------

DAVFS2 1.2.1 README
===================

    1 INTRODUCTION
        1.1 WHAT DAVFS2 IS INTENDED FOR
        1.2 WHAT DAVFS2 IS NOT INTENDED FOR
    2 SECURITY CONSIDERATIONS
    3 MOUNTING
    4 TLS / SSL
    5 CACHE
    6 TROUBLE SHOOTING
    7 KNOWN ISSUES
    8 PARTICIPATION
    

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, HTTP authentication (basic and digest)
and client certificates.

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

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

dafs2 is not a generic WebDAV client. davfs2 maps a WebDAV resource to a file
system. But as the file system interface and the WebDAV protocol are quite
different, this is not possible without losses. As a file system davfs2 can not
use all the possibilities of WebDAV, and most WebDAV servers do not provide all
the information a file system usually requires.

A specialised application with built-in WebDAV capabilities should be able to
make better use of the WebDAV protocol. Whether it really does, depends on the
implementation. But if a free WebDAV enabled application is available, you
might try it first.


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 dav_group (default is
  group 'davfs2'). 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. When
the mounting user is root, the mount.davfs daemon will run as user 'davfs2'.


3 MOUNTING
==========

davfs2 comes with three manuals: mount.davfs, umount.davfs and davfs2.conf.

When a normal user mounts a davfs2 file system for the first time, there
is not yet a user configuration file and a secrets file. So you will be asked
for the credentials. mount.davfs will create a hidden directory .davfs2 in
the users home directory, that holds configuration files, the cache and
certificates. You will want to edit this files  afterwords.

If you update from an older version, this files allready exist and davfs2
will not touch them. To allow mount.davfs installation of newer versions,
you might rename davfs2.conf and secrets and merge your changes into the
new versions.

GUIs like Gnome and KDE provide means to mount file systems listed in
fstab. But at the moment there is no means to ask the user for credentials
etc. You must configure your davfs2 mounts, using davfs2.conf and secrets,
to allow mounting without user interaction for this to work.

davfs2 needs a network connection to mount and also to unmount cleanly. So
automatic mounting at boot time and unmounting at shut down may not work
reliably. By default davfs2 mounts with option '_netdev' to inform the
operating system about this and allow correct handling. Whether this really
works depends on the details of the startup and shut down process and will
be different on different systems. So please test before you rely on this.


4 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. There are also different
opinions on whether you can really trust in certificates issued by the well
known certificate 'authorities'.

Nevertheless davfs2 insists on verification of server certificates. There
are three ways to do this:

- davfs2 will use the CA-certificates of your system to verify the server
  certificate.

- You may store the server certificate in the certs directory and add a
  configuration option to davfs2.conf. You will have to verify this certificate
  by your own, as davfs2 will trust this certificate without further
  verification. This should be usefull with selfmade server certificates.

- If a crtificate can still not be verified, mount.davfs will print information
  about the certificate and ask the user. This will only be done, before
  mount.davfs changes into daemon mode.


5 CACHE
=======

There are two reasons for chaching:

- The coda kernel file system expects a local copy of the file to act on.

- Many applications, especially those with graphical user interfaces, think
  of file system calls as cheap and 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 short period (configurable, default
is 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 has to upload all the files.


6 TROUBLE SHOOTING
==================

In case davfs2 does not behave as you expect, there is some very useful free
software, to search for the reason:

- Use any browser, telnet and 'openssl s_client' to test whether you can
  connect to the server at all.

- Cadaver is a WebDAV-client with an FTP-like interface. Besides the usual
  FTP-commands it allows you to display and manipulate WebDAV-properties, e.g.
  you can remove stale locks. (http://www.webdav.org/cadaver/)

- Wireshark (former Ethereal) will log and analyze the traffic between davfs2
  and the server. (http://www.wireshark.org/)

- If you have access to the servers log files, they contain valuable
  information.

- Finally davfs2 may be configured with option '--enable-debug', to write a
  lot of messages into the log files. But this is the most laborious way.

When sending a bug report, please include

- the exact version of davfs2 and the source where you got it from.

- a complete description of the bug and the actions that lead to the buggy
  behaviour (please not: I usually do not know th acronyms of your favorite
  applications, operating system and server. In many cases I never used them).
  The exact commands you issued on the command line and the messages you got
  from davfs2 are necessary to understand what's going on.

- if possible, output from the above mentioned tools.


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

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

- Some servers require the use of special headers or cookies. mount.davfs
  currently can not handle this. But this may as well be considered a
  server bug (RFC 2518 does not require any of this).


8 PARTICIPATION
===============

davfs2 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
