davfs2/man/davfs2.conf.5

.TH @CONFIGFILE@ 5 2009\-04\-13 @PACKAGE_STRING@


.SH NAME

\fB@CONFIGFILE@\fR \- Configuration file for \fB@PROGRAM_NAME@\fR


.SH DESCRIPTION

There is a system wide configuration file \fI@SYS_CONF_DIR@/@CONFIGFILE@\fR
and user configuration files \fI~/.@PACKAGE@/@CONFIGFILE@\fR. When
\fB@PROGRAM_NAME@\fR is invoked by root, only the system wide configuration
file is read. When invoked by an ordinary user, the user configuration file
is read in addition. Settings from the user configuration file will take
precedence over the system wide configuration.

.PP
The configuration file consists of lines where each line contains a keyword
value pair. Keyword and value are seperated by spaces and/or tabs.

.PP
The file may contain sections that are for one specific mount point only.
Such a section starts with a line, that contains the full path of the mount
point enclosed in square brackets. The section ends at the start of the next
section or the end of file. Options that shall apply to all mounted file
system must come before the first sections. Options given in a mount specific
section will have precedence.


.SH EXAMPLE

kernel_fs coda
.br
proxy	foo.bar:8080
.br
use_locks 0
.br
.br
[/media/dav]
.br
use_locks 1
.br
.br
[/home/otto/mywebspace]
.br
gui_optimize 1

.PP
All mounted @PACKAGE@ file systems will use the coda kernel file system and the
proxy foo.bar. All @PACKAGE@ file systems expect /media/dav will disable the
use of the locks. /home/otto/mywebspace will use the gui_optimize option.

.SH GENERAL SYNTAX RULES

Lines that only contain spaces and tabs (empty lines) are ignored.

.PP
# indicates a comment. The rest of the line is ignored.

.PP
\(rs is the escape character.

.PP
\(dq" is used for quotation.

.PP
If a value contains one of the special characters space, tab, #, \(rs, or \(dq,
this character must be escaped by a preceding \(rs. Use \(cq\(rs\ \(cq instead
of \(cq\ \(cq, \(cq\(rs#\(cq instead of \(cq#\(cq, \(cq\(rs\(rs\(cq instead of
\(cq\(rs\(cq and \(cq\(rs\(dq\(cq instead of \(cq\(dq\(cq.

.PP
Values containing spaces, tabs or # may instead be enclosed in double quotes.
But \(dq and \(cq must be escaped even within double quotes. If the starting line
of a section is enclosed in double quotes, the square brakets must be within
the quotes (like \(dq[/home/otto/with space]\(dq).

.PP
Boolean option values (yes/no) must be given as numerical value.
0 for no, 1 for yes.


.SH AVAILABLE CONFIGURATION OPTIONS

.SH General Options

.TP
.B dav_user
When invoked by root the \fB@PROGRAM_NAME@\fR daemon will run as this user.
Value must be given as \fIname\fP, \fBnot\fR as numerical id.
.br
Default: @USER@
.br
\fBOnly allowed in the system wide configuration file.\fR

.TP
.B dav_group
The group of the running \fB@PROGRAM_NAME@\fR daemon. Ordinary users must
be member of this group in order to mount a @PACKAGE@ file system.
Value must be given as \fIname\fP, \fBnot\fR as numerical id.
.br
Default: @GROUP@
.br
\fBOnly allowed in the system wide configuration file.\fR

.TP
.B ignore_home
An ordinary user is not allowed to mount within the home directory of another
user. But sometimes system users (like \fInobody\fP) get assigned home
directories (like /), that include common mount points. This option allows to
give a comma seperated list of system users that will be excluded from this
check.
.br
\fBOnly allowed in the system wide configuration file.\fR

.TP
.B kernel_fs
Which kernel file system to use, to integrate into the virtual file system.
Possible values are \fIfuse\fP and \fIcoda\fP.
.br
Default: fuse

.TP
.B buf_size
Size in KiByte of the buffer used to communicate with the kernel file system.
Only usefull with \fIfuse\fP, where read and write operations may profit
from a larger buffer.
.br
Default: 16


.SH WebDAV Related Options

.TP
.B use_proxy
Whether to use a proxy to connect to the WebDAV server. 0 = no, 1 = yes.
If no proxy is defined in the configration file or the environment variables
\fBhttps_proxy\fR, \fBhttp_proxy\fR and \fBall_proxy\fR, this option has no
effect. 
.br
Default: 1
.br
\fBOnly allowed in the system wide configuration file.\fR

.TP
.B proxy
Name of the proxy. The name must be the fully qualified domain name
(no scheme). If the proxy port differs from the default of 8080, it
must be appended, seperated by a colon. Examples: \fIfoo.bar:1704\fP or
\fIfoo.bar\fP
.br
\fBOnly allowed in the system wide configuration file.\fR

.TP
.B servercert
Name of a certificate file in PEM format. The name of the file may be
given as absolute path or as file name only. In the latter case the
directories \fI~/.@PACKAGE@/@CERTS_DIR@\fP and
\fI@SYS_CONF_DIR@/@CERTS_DIR@\fP will be searched.
.br
This option is intended for self-signed server certificates. Self-signed
means issuer and subject are the same. Common name (CN) must be the
domain name of the server.
.br
In case the server certificate is not self-singed, this file must contain
the certificate of the certificate authority (CA) that signed the server
certificate, not the the server certificate itself. If an hirarchy of
CA's is involved (the CA that signed the server certificate is not the
root CA), the file must contain all the certificates from the chain of
CAs involved, beginning with the CA that signed the server certificate,
up to the self-signed certificate of the root CA. (The option name
\fBservertcert\fR is a misnomer in this case. Sorry.) You can create the
file by concatenating all the CA-certificates involved.
.br
\fBNote:\fR Even if the certificate is trusted, that does not mean it
is accepted. There is the additional constraint, that the certificate
presented by the server must belong to the server. The CN in the
server certificate must be the domain name of the server. There is
currently no way to automatically accept certificates that don't
belong to the server.

.TP
.B clientcert
Name of a certificate in PKCS#12 format that will be used to authenticate
with the server. The name of the file may be given as absolute path or as
file name only. In the latter case the directories
\fI~/.@PACKAGE@/@CERTS_DIR@/@CLICERTS_DIR@\fP and
\fI@SYS_CONF_DIR@/@CERTS_DIR@/@CLICERTS_DIR@\fP will be searched.

.TP
.B secrets
Name of a file that holds the credentials for servers and the proxy, and
passwords to decrypt the client certificate. The name must be an absolute
path. The file must be read and writable by the owner only (mode 600).
.br
Default: ~/.@PACKAGE@/@SECRETSFILE@
.br
\fBOnly allowed in the user configuration file.\fR The system wide
secrets file is allways \fI@SYS_CONF_DIR@/@SECRETSFILE@\fP.

.TP
.B ask_auth
Ask the user interactively for credentials and passwords if not found in the
secretsfile. 0 = no, 1 = yes.
.br
Default: 1

.TP
.B use_locks
Whether to lock files on the server when they are opened for writing.
0 = no, 1 = yes.
.br
Default: 1

.TP
.B lock_owner
A string send to the server to identify the owner of a lock. If a WebDAV
resource is used at the same time by different clients using the same
credentials, different values for lock_owner should be choosen.
.br
Default: the username from the credentials

.TP
.B lock_timeout
How long in seconds locks should be valid, before the server removes them.
The server may ignore this and set its own timeout value.
.br
Default: 1800

.TP
.B lock_refresh
That many seconds before the lock times out, \fB@PROGRAM_NAME@\fR will try to
refresh the lock. The value should be substantially greater than
\fBdelay_upload\fR.
.br
Default: 60

.TP
.B use_expect100
To avoid  uploading big files that will be refused by the server,
\fB@PROGRAM_NAME@\fR uses the header \fIexpect: 100\-continue\fP to get the o.k.
from the server before uploading. Not all servers understand this.
0 = no, 1 = yes.
.br
Default: 0

.TP
.B if_match_bug
Some servers do not handle If-Match and If-None-Match-headers correctly.
This otion tells \fB@PROGRAM_NAME@\fR to use HEAD instead of thes headers.
0 = no, 1 = yes.
.br
Default: 0

.TP
.B drop_weak_etags
Popular servers send a weak etag whenever they are not able to calculate
a strong one. This weak etag will never be valid, but after one second it
is silently turned into a strong, valid etag. With this flag set to 1,
\fB@PROGRAM_NAME@\fR will never use this weak etags. If the flas is 0,
the weakness indicator will be removed and the etag is assumed to be
strong. There is some danger of the Lost-Update-Problem with
this. But it is minimized when using locks.
.br
You should turn this on, when you can't use locks and there is the
danger of concurrent access to the same resource. In this case the
etag is not used at all and the resource cannot be cached.
.br
0 = no, 1 = yes.
.br
Default: 0

.TP
.B allow_cookie
Some servers will only work when they are allowed to set a cookie and this
cookie is returned in subsequent requests. This option adds very simple
cookie support. It supports just one cookie which should usually be
a session ID.
0 = no, 1 = yes.
.br
Default: 0

.TP
.B precheck
If option \fBif_match_bug\fR is set: use HEAD-requests to check for existence
or modification of a file to avoid unintended overwriting what somebody
else changed. Has no effect if option \fBif_match_bug\fR is 0. You should only
set it 0, if there is no concurrent access to the server.
0 = no, 1 = yes.
.br
Default: 1

.TP
.B ignore_dav_header
Some servers send wrong information about their capabilities in the DAV-header.
In this case the header should be ignored.
.br
Default: 0

.TP
.B server_charset
When extracting file names from the path component of the URL,
\fB@PROGRAM_NAME@\fR will assume they are encoded using this character set
and translate file names to the local character set. This is \fBnot\fR
about encoding of file contents and \fBnot\fR about HTTP escaping rules.
.br
There is no means in HTTP to know the character encoding of the path
component. There may be even different encodings within the same path, as
the encoding of file names is often defined by the clients that created them.
Nowadays it is best to use only UTF\-8 encoding and to do no conversion. If
you are not sure that all clients understand UTF\-8, restrict file names to
pure us\-ascii. Never use characters in file names, that may have a special
function on some operating systems (like /, : and \(rs).
.br
Default: no character set conversion

.TP
.B connect_timeout
When creating a TCP connection to the server \fB@PROGRAM_NAME@\fR will
wait that many seconds for an answer before assuming an error. If a value
of '0' is used then no explicit timeout handling is set and the connect call
will only timeout as dictated by the TCP stack.
.br
This parameter only takes effect if the version of neon in use
(neon version > 0.26) and the OS support non-blocking I/O.
.br
Default: 10

.TP
.B read_timeout
How long in seconds \fB@PROGRAM_NAME@\fR will wait for an answer from the
server before assuming an error.
.br
Default: 30

.TP
.B retry
When \fB@PROGRAM_NAME@\fR can not reach the server it will try again after
\fBretry\fR seconds. For subsequent retries the interval will be increased
up to \fBmax_retry\fR seconds.
.br
Default: 30

.TP
.B max_retry
Maximum value of the retry interval.
.br
Default: 300

.TP
.B add_header
Your server might expect special headers to do what you want. Different from
other options, this one takes two values: the name of the header and its value.
Example:
.br
add_header Translate F
.br
\fB@PROGRAM_NAME@\fR will add header "Translate: F" on all requests.
.br
This option is cumulative. You can enter more than one add_header option
and all of them will be added. Also add_header options from
@SYS_CONF_DIR@/@CONFIGFILE@ and ~/.@PACKAGE@/@CONFIGFILE@ are merged.


.SH Cache Related Options

.TP
.B backup_dir
Each mounted @PACKAGE@ file system has a directory to store backups of files
that could not be stored back to the server. This sets the name of this
directory. You should regularly check this directory.
.br
Default: lost+found

.TP
.B cache_dir
The directory where \fB@PROGRAM_NAME@\fR will store cached files. For every
mount point a subdirectory will be created.
.br
In the systemwide configuration file this will set the system wide cache,
used by root. In a users configuration file it will set the cache used by
this user.
.br
Defaults: @SYS_CACHE_DIR@ and ~/.@PACKAGE@/cache

.TP
.B cache_size
The amount of disk space in MiByte that may be used. \fB@PROGRAM_NAME@\fR
will always take enough space to cache open files, ignoring this value if
necessary.
.br
Default: 50

.TP
.B table_size
\fB@PROGRAM_NAME@\fR maintains a hash table with an entry for each known file
or directory. This gives the number of entries in this table. For large
file systems (more than some hundreds of files) increasing this number may
speed up file operations. The value should be a power of 2.
.br
Default: 1024

.TP
.B dir_refresh
After \fB@PROGRAM_NAME@\fR has got information about files in a directory it
considers it valid for this time in seconds. Note: This does not affect
opening of files and reading a directory by an application.
.br
Default: 60

.TP
.B file_refresh
When a file or directory is opened by an application, \fB@PROGRAM_NAME@\fR
will first check the server for a newer version. But some applications do
open calls on the same file in short sequence. To avoid unecessary traffic
\fB@PROGRAM_NAME@\fR will wait that many seconds before it send a new request
for the same information.
.br
Default: 1

.TP
.B delay_upload
When a file that has been changed is closed, \fB@PROGRAM_NAME@\fR will wait
that many seconds before it will upload it to the server. This will avoid
uploading of temporary files that will be removed immediately after closing.
If you need the files to appear on the server immediately after closing,
set this option to 0.
.br
Default: 10

.TP
.B gui_optimize
When a file is opened, \fB@PROGRAM_NAME@\fR will have to check the server
whether there is a newer version. Graphical User Interfaces tend to open
just any file, slowing down things dramatically for large directories.
With this option \fB@PROGRAM_NAME@\fR will try to get this information
from all files in a directory with one PROPFIND request. 0 = no, 1 = yes.
.br
Default: 0


.SH Debugging Options

.TP
.B debug
Send debug messages to the syslog daemon. The value tells what kind of
information shall be logged. The messages are send with facility LOG_DAEMON
and priority LOG_DEBUG. It depends from the configuration of the syslog daemon
where the messages will go (propably /var/log/messages, /var/log/syslog or
/var/log/daemon.log). Whether HTTP related debug messages are available
depends on your neon library.
.br
Unlike other options, this option is cumulative. If there are several debug
entries with different values, all of them will be applied. Also debug options
from @SYS_CONF_DIR@/@CONFIGFILE@ and ~/.@PACKAGE@/@CONFIGFILE@ are merged.
.br
\fBNote:\fR Debug messages let the log-files grow quickly. Never use this
option in normal operation of mount.davfs.
.br
Default: no debugging messages
.RS
.TP
.B Recognized values:
.TP
.B config
Command line and configuration options.
.TP
.B kernel
Upcalls from the kernel file system.
.TP
.B cache
Cache operations like adding and removing nodes.
.TP
.B http
HTTP headers.
.TP
.B xml
Parsing of the XML-body of WebDAV-requests.
.TP
.B httpauth
Negotiation of authentication.
.TP
.B locks
Information about locks.
.TP
.B ssl
TLS/SSL related stuff like certificates.
.TP
.B httpbody
Complete body of HTTP-responses.
.TP
.B secrets
Also print confidential information, which is usually omitted or obscured.
.TP
.B most
Includes config, kernel, cache and http.
.RE


.SH AUTHORS

This man page was written by by Werner Baumann
<werner.baumann@onlinehome.de>.


.SH DAVFS2 HOME

@PACKAGE_BUGREPORT@


.SH SEE ALSO

.BR @PROGRAM_NAME@ (8),
.BR u@PROGRAM_NAME@ (8),
.BR mount (8),
.BR umount (8),
.BR fstab (5)