/[davfs2]/davfs2/README
ViewVC logotype

Contents of /davfs2/README

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.6 - (show annotations) (download)
Fri Apr 15 20:09:23 2016 UTC (7 years, 10 months ago) by wbaumann
Branch: MAIN
CVS Tags: HEAD
Changes since 1.5: +11 -3 lines
Add information about required local cahe

1 2016-04-15
2 ----------
3
4 # Copyright (C) 2006, 2007, 2008, 2009, 2010, 2014, 2016 Werner Baumann
5
6 # Copying and distribution of this file, with or without modification, are
7 # permitted in any medium without royalty.
8
9
10 DAVFS2 X.X.X README
11 ===================
12
13 1 INTRODUCTION
14 1.1 WHAT DAVFS2 IS INTENDED FOR
15 1.2 WHAT DAVFS2 IS NOT INTENDED FOR
16 2 SECURITY CONSIDERATIONS
17 3 MOUNTING
18 4 TLS / SSL
19 5 CACHE
20 6 TROUBLE SHOOTING
21 7 KNOWN ISSUES
22 8 CONTACT
23
24
25 1 INTRODUCTION
26 ==============
27
28 davfs2 is a Linux file system driver that allows you to mount a WebDAV
29 resource into your Unix file system tree. So - and that is what makes
30 davfs2 different - applications can use it without knowing about WebDAV.
31 You may edit WebDAV resources using standard applications that interact
32 with the file system as usual.
33
34 davfs2 supports SSL and proxy, HTTP authentication (basic and digest)
35 and client certificates.
36
37 1.1 WHAT DAVFS2 IS INTENDED FOR
38 -------------------------------
39
40 - If you have documents you want to access from different locations, store
41 them on a WebDAV server accessible via Internet. Mount them with davfs2
42 from wherever you want.
43
44 - Use a WebDAV server as workspace for a geographically distributed work group.
45
46 - A web site may be made accessible to the developers via WebDAV. So they
47 can mount with davfs2 and edit in place.
48
49 1.2 WHAT DAVFS2 IS NOT INTENDED FOR
50 -----------------------------------
51
52 davfs2 is not intended as a replacement for distributed file systems like
53 nfs, coda, cifs and similar.
54
55 When davfs2 mounts a resource, it authenticates with the server using the
56 user-name and password it got from the mounting user. All requests to the
57 server are done on behalf of this WebDAV user. davfs2 does not handle different
58 WebDAV users within one mount. But this would be required for a distributed
59 file system.
60
61 davfs2 is not a generic WebDAV client. davfs2 maps a WebDAV resource to a file
62 system. But as the file system interface and the WebDAV protocol are quite
63 different, this is not possible without losses. As a file system davfs2 cannot
64 use all the possibilities of WebDAV, and most WebDAV servers do not provide all
65 the information a file system usually requires.
66
67 A specialised application with built-in WebDAV capabilities should be able to
68 make better use of the WebDAV protocol. Whether it really does, depends on the
69 implementation. But if a free WebDAV enabled application is available, you
70 might try it first.
71
72 davfs2 can't (always) replace lodal disk space. Due to the nature of WebDAV
73 davfs2 can't directly redirect reading and writing to the WebDAV server. davfs2
74 always needs local copies of all open files. So if you have not enough sidk
75 space to hold these local copies, davfs2 will not help.
76
77
78 2 SECURITY CONSIDERATIONS
79 =========================
80
81 To allow non-root users mounting of WebDAV resources, mount.davfs is run
82 setuid root. To prevent inexperienced (or even malicious) users from introducing
83 dangerous content into system directories or other users home directory,
84 the administrator must have control over user mounts.
85
86 - Non-root users can only mount using the normal mount program. There must
87 also be an entry in /etc/fstab. This can only be done by root.
88
89 - To mount a WebDAV resource users must be member of dav_group (default is
90 group 'davfs2'). The administrator may use group membership to allow or
91 disallow mounting of WebDAV resources.
92
93 mount.davfs starts with effective user-id 'root' to be able to mount. After
94 mounting it changes its id permanently to that of the mounting user. When
95 the mounting user is root, the mount.davfs daemon will run as user 'davfs2'.
96
97
98 3 MOUNTING
99 ==========
100
101 davfs2 comes with three manuals: mount.davfs, umount.davfs and davfs2.conf.
102
103 When a normal user mounts a davfs2 file system for the first time, there
104 is not yet a user configuration file and a secrets file. So you will be asked
105 for the credentials. mount.davfs will create a hidden directory .davfs2 in
106 the users home directory, that holds configuration files, the cache and
107 certificates. You will want to edit this files afterwards.
108
109 If you update from an older version, these files already exist and davfs2
110 will not touch them. To allow mount.davfs installation of newer versions,
111 you might rename davfs2.conf and secrets and merge your changes into the
112 new versions.
113
114 GUIs like Gnome and KDE provide means to mount file systems listed in
115 fstab. But at the moment there is no means to ask the user for credentials
116 etc. You must configure your davfs2 mounts, using davfs2.conf and secrets,
117 to allow mounting without user interaction for this to work.
118
119 davfs2 needs a network connection to mount and also to unmount cleanly. So
120 automatic mounting at boot time and unmounting at shut down may not work
121 reliably. By default davfs2 mounts with option '_netdev' to inform the
122 operating system about this and allow correct handling. Whether this really
123 works depends on the details of the start-up and shut-down process and will
124 be different on different systems. So please test before you rely on this.
125
126
127 4 TLS / SSL
128 ===========
129
130 The key question when using TLS/SSL is whether you can trust in the certificate
131 the server presents. There is no gain in security when you use strong
132 encryption for your communication with an attacker. There are also different
133 opinions on whether you can really trust in certificates issued by the well
134 known certificate 'authorities'.
135
136 Nevertheless davfs2 insists on verification of server certificates. There
137 are three ways to do this:
138
139 - davfs2 will use the CA-certificates of your system to verify the server
140 certificate. The server's certificate must be valid and host-name of the
141 server must match the subject-alt-name or the common name of the certificate.
142
143 - You may store a top-level CA-certificate in the certs directory and set
144 option trust_ca_cert in the davfs2.conf directory. This CA-certificate will
145 be used instead of the CA-certificates provided by your system. he server's
146 certificate must be valid and host-name of the server must match the
147 subject-alt-name or the common name of the certificate.
148 This is useful when the service provider uses a private CA or the server
149 certificate is self-signed.
150
151 - You may store the certificate of the server and set option trust_server_cert
152 in the davfs2.conf file. In this case the certificate of the server must
153 exactly match this certificate, but it does not matter whether it is valid,
154 outdated or does not match the server's host-name.
155
156 When you use option trust_ca_cert or trust_server_cert it is your responsibility
157 to get the certificate in a reliable way and care for certificate revocation.
158 If you can do this it is more secure then relying of well known certificate
159 authorities (considering recent events).
160
161 If a certificate can not be verified, mount.davfs will print information about
162 the certificate and ask the user. This will only be done before mount.davfs
163 changes into daemon mode.
164
165
166 5 CACHE
167 =======
168
169 davfs2 will store a local copy of all open files in its cache. So make sure
170 there is enough local disk space available in the cache directory.
171
172 There are two reasons for caching:
173
174 - The coda kernel file system expects a local copy of the file to act on.
175
176 - Many applications, especially those with graphical user interfaces, think
177 of file system calls as cheap and quick, which is not true when using a slow
178 connection to the Internet. Some graphical interfaces for file handling even
179 open every file in every directory they list, forcing davfs2 to download them
180 from the server.
181
182 To avoid excessive network traffic, davfs2 now saves all downloaded files in a
183 cache directory and will hold the files, even when the file system is
184 unmounted. When the same file system is mounted again, it will reuse this
185 cached files.
186
187 To avoid inconsistencies, davfs2 will do a conditional GET whenever a file is
188 opened (it will ask the server if there is a newer version, and download only
189 if there is).
190
191 Many application use temporary files that will be deleted just after they have
192 been closed. So whenever a file is newly created or changed, davfs2 will wait
193 until it is closed and then wait another short period (configurable, default
194 is 10 seconds) before it will upload the changed version to server. This saves
195 a lot of unnecessary traffic, but the strategy still has to be enhanced. If
196 there are many files to be uploaded (e.g. after copying a directory)
197 mount.davfs may block quite some time, as it has to upload all the files.
198
199
200 6 TROUBLESHOOTING
201 =================
202
203 In case davfs2 does not behave as you expect, there is some very useful free
204 software, to search for the reason:
205
206 - Use any browser, telnet and 'openssl s_client' to test whether you can
207 connect to the server at all.
208
209 - Cadaver is a WebDAV-client with an FTP-like interface. Besides the usual
210 FTP-commands it allows you to display and manipulate WebDAV-properties, e.g.
211 you can remove stale locks. (http://www.webdav.org/cadaver/)
212
213 - You may set option 'debug most" in the davfs2.conf file. This will print a
214 lot of debug messages in one of your log files.
215
216 - Wireshark will log and analyse the traffic between davfs2 and the server.
217 (http://www.wireshark.org/)
218
219 - If you have access to the server's log files, they contain valuable
220 information.
221
222 When sending a bug report, please include
223
224 - the exact version of davfs2 and the source where you got it from.
225
226 - a complete description of the bug and the actions that lead to the buggy
227 behaviour (please note: I usually do not know the acronyms of your favourite
228 applications, operating system and server. In many cases I never used them).
229 The exact commands you issued on the command line and the messages you got
230 from davfs2 are necessary to understand what's going on.
231 Please always send the original error and debug messages in full. Don't
232 replace them by your interpretation.
233
234 - if possible, output from the above mentioned tools.
235
236
237 7 KNOWN ISSUES
238 ==============
239
240 - If the server does not support RFC 4331 (most servers don't), davfs2 cannot
241 calculate the free disk space on the server. But some applications
242 (e.g. nautilus) insist on this. So davfs can't help but lie. I tried to
243 make the numbers look funny, so you will notice they are faked.
244
245
246 8 CONTACT
247 =========
248
249 davfs2 is an Free Software project hostet at
250 http://savannah.nongnu.org/projects/davfs2 or
251 https://savannah.nongnu.org/projects/davfs2
252
253 You can submit a bug-report or support-request at
254 http://savannah.nongnu.org/support/?func=additem&group=davfs2 or
255 https://savannah.nongnu.org/support/?func=additem&group=davfs2
256

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26