
DAVFS2 1.1.0 README
===================

    0 UPDATING FROM PREVIOUS VERSION
    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
    

0 UPDATING FROM PREVIOUS VERSION
================================

In davfs2 1.2.0 the organization of the permanent cache has changed
compared to the 1.0.x releases. There are also new templates for the
configuration and secrets file. In order to get a clean installation
and to avoid *loss of data* you should take some precautions *before*
you install the new version:

- Inspect the backup direcotries (dav-local-backup) of all davfs2 file
  systems you ever mounted and save all the files you may need some day.

- If you made changes to the system wide configuration and secrets files,
  backup this files, so you can copy your changes into the new files
  after installation.

- The same holds for the configuration and secrets files in the users
  home directories (~/.davfs2/).

- Remove the system wide cache directory (/var/cache/davfs2).

- Remove the .davfs2 directories in the users home directories.

After installation you may edit the system wide configuration and
secrets file. The system wide cache directory will be created by mount.davfs
when needed.

The .davfs2 direcotries in the users home directories will be created when
a users starts mount.davfs for the first time. The configuration and 
secrets file may then be edited according the users needs.

Don't forgett to remove your backups of the old configuration and *secrets*
files.

    
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 dav_group (default is
  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. When
the mounting user is root, but the mount option uid is given, mount.davfs
will run with this uid. This will reduce the risks that are allways present
when a daemon is connected to the internet. So avoid mounting WebDAV resources
as root without setting mount option uid.


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

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

DAVFS2 uses the neon libraries for communication with the server.
libneon (2.4, 2.5 or 2.6) must be installed. Your distribution will most
likely provide a package.
If you want to compile DAVFS2 you also need the neon header files.
If your distribution don't come with libneon you can get it from
http://www.webdav.org/neon/

Your kernel must include either the coda file system or the fuse file system
or both. They may be loadable modules. Almost all Linux 2.4 and 2.6 kernels
support at least on of them.

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

- Get the sources from CVS (reading this you may just have done):
    $ cvs -d:pserver:anonymous@dav.cvs.sourceforge.net:/cvsroot/dav login
    Just hit Enter when asked for your password.
    $ cvs -z3 -d:pserver:anonymous@dav.cvs.sourceforge.net:/cvsroot/dav checkout -r v1 -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.x.x.tar.gz

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

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

    --with-neon=<directory>
        Directory where to find the neon library and the neon headers.
        Default is to first try /usr/local and then /usr. If you just have
        neon liebraries in /usr/lib and headers in /usr/include, you don't
        need this.
    ./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.X.X-bin-i386'. You will find the following files:

- mount.davfs (the executable binary)
- README (this file) and other documentation
- 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/doc/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.

Libraries
---------
This program requires the GNU version of libc6 at runtime.
The neon and ssl libraries are included in the binary.

CA-cerificates for TLS/SSL
--------------------------
The ssl library included in the binary expects CA-certificates to be in
directory /usr/lib/ssl/certs. This may be a symbolic link. Most distributions
store the certificates in /etc/ssl/certs and some (e.g. Suse) come without
this symbolic link. If davfs2 has problems to verify server certificates,
although you know they are valid, you will have to create a symbolic link
'/usr/lib/ssl/certs', that points to the real repository of CA-certificates.


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

- Read our fine manual.

- root should have added you to group 'users' (or whatever 'dav_group'
  is configured in /etc/davfs2.conf).

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

- Copy file 'secrets.template' from '/usr/local/share/doc/davfs2' (or
  '/usr/share/doc/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 or gnutls (via the Neon library) for TLS. These
programs come 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. (Allthough this only says: the server has got a
certificate of a well known Certificate Authority. I can't help with the
question whether to trust this well known Certificate Authorities and their
customers.)

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 or gnutls 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!).

I you are using the binary package, sometimes the included ssl library will
not find the CA-certificates. Please see 3.4 INSTALLATION FROM BINARY PACKAGE
for a possible solution.


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


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

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

- mount.davfs needs internationalization und support for national languages.
