Configuration#
This document describes the configuration options of a WsgiDAV server.
The WsgiDAVApp
object is configured by passing
a Python dict
with distinct options, that define
Server options (hostname, port, SSL cert, …)
List of share-name / WebDAV provider mappings
Optional list of users for authentication
Optional custom DAV providers (i.e. other than
FilesystemProvider
)Optional custom lock manager, property manager and domain controller
Advanced debugging options
(and more)
This section shows the available options and defaults:
1# -*- coding: utf-8 -*-
2# (c) 2009-2023 Martin Wendt and contributors; see WsgiDAV https://github.com/mar10/wsgidav
3# Original PyFileServer (c) 2005 Ho Chun Wei.
4# Licensed under the MIT license:
5# http://www.opensource.org/licenses/mit-license.php
6r"""
7::
8
9 _ __ _ ___ ___ _ __
10 | | /| / /__ ___ (_) _ \/ _ | | / /
11 | |/ |/ (_-</ _ `/ / // / __ | |/ /
12 |__/|__/___/\_, /_/____/_/ |_|___/
13 /___/
14
15Default confguration.
16"""
17# from wsgidav.mw.debug_filter import WsgiDavDebugFilter
18from wsgidav.dir_browser import WsgiDavDirBrowser
19from wsgidav.error_printer import ErrorPrinter
20from wsgidav.http_authenticator import HTTPAuthenticator
21from wsgidav.mw.cors import Cors
22from wsgidav.request_resolver import RequestResolver
23
24__docformat__ = "reStructuredText"
25
26# Use these settings, if config file does not define them (or is totally missing)
27DEFAULT_VERBOSE = 3
28DEFAULT_LOGGER_DATE_FORMAT = "%H:%M:%S"
29DEFAULT_LOGGER_FORMAT = "%(asctime)s.%(msecs)03d - %(levelname)-8s: %(message)s"
30
31DEFAULT_CONFIG = {
32 "server": "cheroot",
33 "server_args": {},
34 "host": "localhost",
35 "port": 8080,
36 "mount_path": None, # Application root, e.g. <mount_path>/<share_name>/<res_path>
37 "provider_mapping": {},
38 "fs_dav_provider": {
39 "shadow_map": {},
40 "follow_symlinks": False,
41 },
42 "add_header_MS_Author_Via": True,
43 "hotfixes": {
44 "emulate_win32_lastmod": False, # True: support Win32LastModifiedTime
45 "re_encode_path_info": True, # (See issue #73)
46 "unquote_path_info": False, # (See issue #8, #228)
47 # "accept_put_without_content_length": True, # (See issue #10, #282)
48 # "treat_root_options_as_asterisk": False, # Hotfix for WinXP / Vista: accept 'OPTIONS /' for a 'OPTIONS *'
49 # "win_accept_anonymous_options": False,
50 # "winxp_accept_root_share_login": False,
51 },
52 "property_manager": None, # True: use property_manager.PropertyManager
53 "mutable_live_props": [],
54 "lock_storage": True, # True: use LockManager(lock_storage.LockStorageDict)
55 "middleware_stack": [
56 # WsgiDavDebugFilter,
57 Cors,
58 ErrorPrinter,
59 HTTPAuthenticator,
60 WsgiDavDirBrowser, # configured under dir_browser option (see below)
61 RequestResolver, # this must be the last middleware item
62 ],
63 # HTTP Authentication Options
64 "http_authenticator": {
65 # None: dc.simple_dc.SimpleDomainController(user_mapping)
66 "domain_controller": None,
67 "accept_basic": True, # Allow basic authentication, True or False
68 "accept_digest": True, # Allow digest authentication, True or False
69 "default_to_digest": True, # True (default digest) or False (default basic)
70 # Name of a header field that will be accepted as authorized user
71 "trusted_auth_header": None,
72 },
73 #: Used by SimpleDomainController only
74 "simple_dc": {"user_mapping": {}}, # NO anonymous access by default
75 #: Verbose Output
76 #: 0 - no output
77 #: 1 - no output (excepting application exceptions)
78 #: 2 - show warnings
79 #: 3 - show single line request summaries (for HTTP logging)
80 #: 4 - show additional events
81 #: 5 - show full request/response header info (HTTP Logging)
82 #: request body and GET response bodies not shown
83 "verbose": DEFAULT_VERBOSE,
84 #: Log options
85 "logging": {
86 "enable": None, # True: activate 'wsgidav' logger (in library mode)
87 "logger_date_format": DEFAULT_LOGGER_DATE_FORMAT,
88 "logger_format": DEFAULT_LOGGER_FORMAT,
89 "enable_loggers": [],
90 "debug_methods": [],
91 },
92 #: Options for `WsgiDavDirBrowser`
93 "dir_browser": {
94 "enable": True, # Render HTML listing for GET requests on collections
95 # Add a trailing slash to directory URLs (by generating a 301 redirect):
96 "directory_slash": True,
97 # List of fnmatch patterns:
98 "ignore": [
99 ".DS_Store", # macOS folder meta data
100 "._*", # macOS hidden data files
101 "Thumbs.db", # Windows image previews
102 ],
103 "icon": True,
104 "response_trailer": True, # Raw HTML code, appended as footer (True: use a default)
105 "show_user": True, # Show authenticated user an realm
106 # Send <dm:mount> response if request URL contains '?davmount' (rfc4709)
107 "davmount": True,
108 # Add 'Mount' link at the top
109 "davmount_links": False,
110 "ms_sharepoint_support": True, # Invoke MS Office documents for editing using WebDAV
111 "libre_office_support": True, # Invoke Libre Office documents for editing using WebDAV
112 # The path to the directory that contains template.html and associated assets.
113 # The default is the htdocs directory within the dir_browser directory.
114 "htdocs_path": None,
115 },
116}
When a Python dict is passed to the WsgiDAVApp
constructor, its values will override the defaults from above:
root_path = gettempdir()
provider = FilesystemProvider(root_path, readonly=False, fs_opts={})
config = {
"host": "0.0.0.0",
"port": 8080,
"provider_mapping": {"/": provider},
"verbose": 1,
}
app = WsgiDAVApp(config)
Use a Configuration File#
When running from the CLI (command line interface), some settings may be passed as arguments, e.g.:
$ wsgidav --host=0.0.0.0 --port=8080 --root=/tmp --auth=anonymous
Serving on http://0.0.0.0:8080 ...
Much more options are available when a configuration file is used.
By default wsgidav.yaml
and wsgidav.json
are searched in the
local directory.
An alternative file name can be specified like so:
$ wsgidav --config=my_config.yaml
To prevent the use of a local default configuration file, use this option:
$ wsgidav --no-config
The options described below can be defined for the CLI either
Note
The two supported file formats are just different ways for the CLI to
generate a Python dict that is then passed to the
WsgiDAVApp
constructor.
The YAML format is recommended.
For a start, copy
YAML Sample Configuration
and edit it to your needs.
(Alternatively use
JSON Sample Configuration
.)
Verbosity Level#
The verbosity level can have a value from 0 to 5 (default: 3):
Verbosity |
Option |
Log level |
Remarks |
---|---|---|---|
0 |
-qqq |
CRITICAL |
quiet |
1 |
ERROR |
no output (excepting application exceptions) |
|
2 |
-q |
WARN |
warnings and errors only |
3 |
INFO |
show single line request summaries (for HTTP logging) |
|
4 |
-v |
DEBUG |
show additional events |
5 |
-vv |
DEBUG |
show full request/response header info (HTTP Logging) request body and GET response bodies not shown |
Middleware Stack#
WsgiDAV is built as WSGI application (WsgiDAVApp
)
that is extended by a list of middleware components which implement additional
functionality.
This stack is defined as a list of WSGI compliant application instances, e.g.:
from wsgidav.mw.debug_filter import WsgiDavDebugFilter
debug_filter = WsgiDavDebugFilter(wsgidav_app, next_app, config)
conf = {
...
"middleware_stack": [
debug_filter,
...
],
...
}
If the middleware class constructor has a common signature, it is sufficient to
pass the class instead of the instantiated object.
The built-in middleware derives from BaseMiddleware
,
so we can simplify as:
from wsgidav.dir_browser import WsgiDavDirBrowser
from wsgidav.mw.debug_filter import WsgiDavDebugFilter
from wsgidav.error_printer import ErrorPrinter
from wsgidav.http_authenticator import HTTPAuthenticator
from wsgidav.request_resolver import RequestResolver
conf = {
...
"middleware_stack": [
WsgiDavDebugFilter,
ErrorPrinter,
HTTPAuthenticator,
WsgiDavDirBrowser,
RequestResolver, # this must be the last middleware item
],
...
}
The middleware stack can be configured and extended. The following example removes the directory browser, and adds a third-party debugging tool:
import dozer
# from wsgidav.dir_browser import WsgiDavDirBrowser
from wsgidav.mw.debug_filter import WsgiDavDebugFilter
from wsgidav.error_printer import ErrorPrinter
from wsgidav.http_authenticator import HTTPAuthenticator
from wsgidav.request_resolver import RequestResolver
# Enable online profiling and GC inspection. See https://github.com/mgedmin/dozer
# (Requires `pip install Dozer`):
dozer_app = dozer.Dozer(wsgidav_app)
dozer_profiler = dozer.Profiler(dozer_app, None, "/tmp")
conf = {
...
"middleware_stack": [
dozer_app,
dozer_profiler,
WsgiDavDebugFilter,
ErrorPrinter,
HTTPAuthenticator,
# WsgiDavDirBrowser,
RequestResolver, # this must be the last middleware item
],
...
}
The stack can also be defined in text files, for example YAML. Again, we can pass an import path for a WSGI compliant class if the signature is known. For third-party middleware however, the constructor’s positional arguments should be explicitly listed:
...
middleware_stack:
- class: dozer.Dozer
args:
- "${application}"
- class: dozer.Profiler
args:
- "${application}"
- null # global_conf
- /tmp # profile_path
- wsgidav.mw.debug_filter.WsgiDavDebugFilter
- wsgidav.error_printer.ErrorPrinter
- wsgidav.http_authenticator.HTTPAuthenticator
- wsgidav.dir_browser.WsgiDavDirBrowser
- wsgidav.request_resolver.RequestResolver
It is also possible to pass options as named args (i.e. ‘kwargs’):
...
middleware_stack:
...
- class: dozer.Profiler
kwargs:
app: "${application}"
profile_path: /tmp
...
Note that the external middleware must be available, for example by calling
pip install Doze
, so this will not be possible if WsgiDAV is running from
the MSI installer.
DAVProvider#
A DAVProvider handles read and write requests for all URLs that start with a given share path.
WsgiDAV comes bundled with FilesystemProvider
,
a DAVProvider that serves DAV requests by reading and writing to the server’s
file system.
However, custom DAVProviders may be implemented and used, that publish a
database backend, cloud drive, or any virtual data structure.
The provider_mapping
configuration routes share paths to specific
DAVProvider instances.
By default a writable FilesystemProvider
is
assumed, but can be forced to read-only.
Note that a DomainController may still restrict access completely or prevent
editing depending on authentication.
Three syntax variants are supported:
<share_path>: <folder_path>
: useFilesystemProvider(folder_path)
<share_path>: { "root": <folder_path>, "readonly": <bool> }
: useFilesystemProvider(folder_path, readonly)
<share_path>: { "class": <class_path>, args: [arg, ...], kwargs: {"arg1": val1, "arg2": val2, ... }}
Instantiate a custom class (derrived fromDAVProvider
) using named kwargs.
For example:
provider_mapping:
"/": "/path/to/share1"
"/home": "~"
"/pub":
root: "/path/to/share2"
readonly: true
"/share3":
class: path.to.CustomDAVProviderClass
args:
- pos_arg1
- pos_arg2
kwargs:
path: '/path/to/share3'
another_arg: 42
Property Manager#
The built-in PropertyManager`
.
Possible options are:
Disable locking, by passing
property_manager: null
.Enable default storage, which is implemented using a memory-based, not persistent storage, by passing
property_manager: true
. (This is an alias forproperty_manager: wsgidav.prop_man.property_manager.PropertyManager
)Enable an installed or custom storage
Example: Use a persistent shelve based property storage:
property_manager:
class: wsgidav.prop_man.property_manager.ShelvePropertyManager
storage_path: /path/to/wsgidav_locks.shelve
Lock Manager and Storage#
The built-in LockManager
requires a
LockStorageDict
instance.
Possible options are:
Disable locking, by passing
lock_storage: null
.Enable default locking, which is implemented using a memory-based, not persistent storage, by passing
lock_storage: true
. (This is an alias forlock_storage: wsgidav.lock_man.lock_storage.LockStorageDict
)Enable an installed lock storage
A persistent, shelve based LockStorageShelve
is also available:
lock_storage:
class: wsgidav.lock_man.lock_storage.LockStorageShelve
kwargs:
storage_path: /path/to/wsgidav_locks.shelve
Domain Controller#
The HTTP authentication middleware relies on a domain controller. Currently three variants are supported.
SimpleDomainController#
The wsgidav.dc.simple_dc.SimpleDomainController
allows to authenticate
against a plain mapping of shares and user names.
The pseudo-share "*"
maps all URLs that are not explicitly listed.
A value of true
can be used to enable anonymous access.
Example YAML configuration:
http_authenticator:
domain_controller: null # Same as wsgidav.dc.simple_dc.SimpleDomainController
accept_basic: true # Pass false to prevent sending clear text passwords
accept_digest: true
default_to_digest: true
simple_dc:
user_mapping:
"*":
"user1":
password: "abc123"
"user2":
password: "qwerty"
"/pub": true
An optional roles list will be passed in environ[“wsgidav.auth.roles”] to downstream middleware. This is currently not used by the provided middleware, but may be handy for custom handlers:
simple_dc:
user_mapping:
"*":
"user1":
password: "abc123"
roles: ["editor", "admin"]
"user2":
password: "abc123"
roles: []
If no config file is used, anonymous authentication can be enabled on the command line like:
$ wsgidav ... --auth=anonymous
which simply defines this setting:
simple_dc:
user_mapping:
"*": true
NTDomainController#
Allows users to authenticate against a Windows NT domain or a local computer.
The wsgidav.dc.nt_dc.NTDomainController
requires basic authentication
and therefore should use SSL.
Example YAML configuration:
ssl_certificate: wsgidav/server/sample_bogo_server.crt
ssl_private_key: wsgidav/server/sample_bogo_server.key
ssl_certificate_chain: None
http_authenticator:
domain_controller: wsgidav.dc.nt_dc.NTDomainController
accept_basic: true
accept_digest: false
default_to_digest: false
nt_dc:
preset_domain: null
preset_server: null
If no config file is used, NT authentication can be enabled on the command line like:
$ wsgidav ... --auth=nt
PAMDomainController#
Allows users to authenticate against a PAM (Pluggable Authentication Modules), that are at the core of user authentication in any modern linux distribution and macOS.
The wsgidav.dc.pam_dc.PAMDomainController
requires basic
authentication and therefore should use SSL.
Example YAML configuration that authenticates users against the server’s known user accounts:
ssl_certificate: wsgidav/server/sample_bogo_server.crt
ssl_private_key: wsgidav/server/sample_bogo_server.key
ssl_certificate_chain: None
http_authenticator:
domain_controller: wsgidav.dc.pam_dc.PAMDomainController
accept_basic: true
accept_digest: false
default_to_digest: false
pam_dc:
service: "login"
If no config file is used, PAM authentication can be enabled on the command line like:
$ wsgidav ... --auth=pam-login
Custom Domain Controllers#
A custom domain controller can be used like so:
http_authenticator:
domain_controller: path.to.CustomDomainController
The constructor must accept two arguments:
def __init__(self, wsgidav_app, config)
Note that this allows the custom controller to read the configuration dict and look for a custom section there.
Cors Middleware#
The wsgidav.mw.cors.Cors
Respond to CORS preflight OPTIONS request and
inject CORS headers.
This middleware is available by default, but needs configuration to be enabled.
A minimal (yet ):
cors:
#: List of allowed Origins or '*'
#: Default: false, i.e. prevent CORS
# allow_origin: null
allow_origin: '*'
This may be too unspecific though. See Cross-Origin Resource Sharing (CORS) .
Annotated YAML configuration:
cors:
#: List of allowed Origins or '*'
#: Default: false, i.e. prevent CORS
allow_origin: null
# allow_origin: '*'
# allow_origin:
# - 'https://example.com'
# - 'https://localhost:8081'
#: List or comma-separated string of allowed methods (returned as
#: response to preflight request)
allow_methods:
# allow_methods: POST,HEAD
#: List or comma-separated string of allowed header names (returned as
#: response to preflight request)
allow_headers:
# - X-PINGOTHER
#: List or comma-separated string of allowed headers that JavaScript in
#: browsers is allowed to access.
expose_headers:
#: Set to true to allow responses on requests with credentials flag set
allow_credentials: false
#: Time in seconds for how long the response to the preflight request can
#: be cached (default: 5)
max_age: 600
#: Add custom response headers (dict of header-name -> header-value items)
#: (This is not related to CORS or required to implement CORS functionality)
add_always:
# 'X-Foo-Header: 'qux'
Sample wsgidav.yaml
#
The YAML syntax is the recommended format to define configuration:
Download Sample Configuration
.
1# WsgiDAV configuration file
2#
3# 1. Rename this file to `wsgidav.yaml`.
4# 2. Adjust settings as appropriate.
5# 3. Run `wsgidav` from the same directory or pass file path with `--config` option.
6#
7# See https://wsgidav.readthedocs.io/en/latest/user_guide_configure.html
8#
9# ============================================================================
10# SERVER OPTIONS
11
12#: Run WsgiDAV inside this WSGI server.
13#: Supported servers:
14#: cheroot, ext-wsgiutils, gevent, gunicorn, paste, uvicorn, wsgiref
15#: 'wsgiref' and 'ext_wsgiutils' are simple builtin servers that should *not* be
16#: used in production.
17#: All other servers must have been installed before, e.g. `pip install cheroot`.
18#: (The binary MSI distribution already includes 'cheroot'.)
19#: Default: 'cheroot', use the `--server` command line option to change this.
20
21server: cheroot
22
23#: Server specific arguments, passed to the server. For example cheroot:
24#: https://cheroot.cherrypy.dev/en/latest/pkg/cheroot.wsgi.html#cheroot.wsgi.Server
25# server_args:
26# max: -1
27# numthreads: 10
28# request_queue_size: 5
29# shutdown_timeout: 5
30# timeout: 10
31
32# Server hostname (default: localhost, use --host on command line)
33host: 0.0.0.0
34
35# Server port (default: 8080, use --port on command line)
36port: 8080
37
38# Transfer block size in bytes
39block_size: 8192
40
41#: Add the MS-Author-Via Response Header to OPTIONS command to allow editing
42#: with Microsoft Office (default: true)
43add_header_MS_Author_Via: true
44
45hotfixes:
46 #: Handle Microsoft's Win32LastModifiedTime property.
47 #: This is useful only in the case when you copy files from a Windows
48 #: client into a WebDAV share. Windows sends the "last modified" time of
49 #: the file in a Microsoft extended property called "Win32LastModifiedTime"
50 #: instead of the standard WebDAV property "getlastmodified". So without
51 #: this config option set to "True", the "last modified" time of the copied
52 #: file will be "now" instead of its original value.
53 #: The proper solution for dealing with the Windows WebDAV client is to use
54 #: a persistent property manager. This setting is merely a work-around.
55 #: NOTE: Works with Win10, can't work with Win7. Other versions untested.
56 emulate_win32_lastmod: false
57 #: Re-encode PATH_INFO using UTF-8 (falling back to ISO-8859-1).
58 #: This seems to be wrong, since per PEP 3333 PATH_INFO is always ISO-8859-1
59 #: encoded (see https://www.python.org/dev/peps/pep-3333/#unicode-issues).
60 #: However it also seems to resolve errors when accessing resources with
61 #: Chinese characters, for example (see issue #73).
62 re_encode_path_info: true
63 #: Force unquoting of PATH_INFO. This should already be done by the WSGI
64 #: Framework, so this setting should only be used to fix unexpected problems
65 #: there (false fixes issue #8, true fixes issue #228).
66 unquote_path_info: false
67 #: Hotfix for WinXP / Vista: accept 'OPTIONS /' for a 'OPTIONS *'
68 #: (default: false)
69 treat_root_options_as_asterisk: false
70
71
72# ----------------------------------------------------------------------------
73# SSL Support
74
75#: The certificate should match the servers hostname, so the bogus certs will
76#: not work in all scenarios.
77#: (Paths can be absolute or relative to this config file.)
78
79# ssl_certificate: 'wsgidav/server/sample_bogo_server.crt'
80# ssl_private_key: 'wsgidav/server/sample_bogo_server.key'
81# ssl_certificate_chain: null
82
83#: Cheroot server supports 'builtin' and 'pyopenssl' (default: 'builtin')
84# ssl_adapter: 'pyopenssl'
85
86# ----------------------------------------------------------------------------
87
88#: Modify to customize the WSGI application stack.
89#: See here for an example how to add custom middlewares:
90#: https://wsgidav.readthedocs.io/en/latest/user_guide_configure.html#middleware-stack
91middleware_stack:
92 - wsgidav.mw.cors.Cors
93 # - wsgidav.mw.debug_filter.WsgiDavDebugFilter
94 - wsgidav.error_printer.ErrorPrinter
95 - wsgidav.http_authenticator.HTTPAuthenticator
96 - wsgidav.dir_browser.WsgiDavDirBrowser
97 - wsgidav.request_resolver.RequestResolver # this must be the last middleware item
98
99# ==============================================================================
100# SHARES
101
102#: Application root, applied before provider mapping shares, e.g.
103#: <mount_path>/<share_name>/<res_path>
104#: Set this to the mount point (aka location) when WsgiDAV is running behind a
105#: reverse proxy.
106#: If set, the mount path must have a leading (but not trailing) slash.
107mount_path: null
108
109#: Route share paths to DAVProvider instances
110#: By default a writable `FilesystemProvider` is assumed, but can be forced
111#: to read-only.
112#: Note that a DomainController may still restrict access completely or prevent
113#: editing depending on authentication.
114#:
115#: The following syntax variants are supported to use FilesystemProvider:
116#: <share_path>: <folder_path>
117#: or
118#: <share_path>: { 'root': <folder_path>, 'readonly': <bool> }
119#:
120#: or instantiate an arbitrary custom class:
121#:
122#: <share_path>: { 'class': <class_path>, args: [<arg>, ...], kwargs: {<arg>: <val>, ...} }
123
124provider_mapping:
125 '/': '/path/to/share1'
126 '/pub':
127 root: '/path/to/share2'
128 readonly: true
129 '/share3':
130 class: path.to.CustomDAVProviderClass
131 args:
132 - foo
133 - 42
134 kwargs:
135 path: '/path/to/share3'
136 another_arg: 42
137
138#: Addional configuration passed to `FilesystemProvider(..., fs_opts)`
139fs_dav_provider:
140 #: Mapping from request URL to physical file location, e.g.
141 #: make sure that a `/favicon.ico` URL is resolved, even if a `*.html`
142 #: or `*.txt` resource file was opened using the DirBrowser
143 # shadow_map:
144 # '/favicon.ico': 'file_path/to/favicon.ico'
145
146 #: Serve symbolic link files and folders (default: false)
147 follow_symlinks: false
148
149# ==============================================================================
150# AUTHENTICATION
151http_authenticator:
152 #: Allow basic authentication
153 accept_basic: true
154 #: Allow digest authentication
155 accept_digest: true
156 #: true (default digest) or false (default basic)
157 default_to_digest: true
158 #: Header field that will be accepted as authorized user.
159 #: Including quotes, for example: trusted_auth_header = 'REMOTE_USER'
160 trusted_auth_header: null
161 #: Domain controller that is used to resolve realms and authorization.
162 #: Default null: which uses SimpleDomainController and the
163 #: `simple_dc.user_mapping` option below.
164 #: (See http://wsgidav.readthedocs.io/en/latest/user_guide_configure.html
165 #: for details.)
166 domain_controller: null
167 # domain_controller: wsgidav.dc.simple_dc.SimpleDomainController
168 # domain_controller: wsgidav.dc.pam_dc.PAMDomainController
169 # domain_controller: wsgidav.dc.nt_dc.NTDomainController
170
171
172# Additional options for SimpleDomainController only:
173simple_dc:
174 # Access control per share.
175 # These routes must match the provider mapping.
176 # NOTE: Provider routes without a matching entry here, are inaccessible.
177 user_mapping:
178 '*': # default (used for all shares that are not explicitly listed)
179 'user1':
180 password: 'abc123'
181 # Optional: passed to downstream middleware as environ["wsgidav.auth.roles"]
182 roles: ['editor']
183 'user2':
184 password: 'def456'
185 password: 'qwerty'
186 '/pub': true # Pass true to allow anonymous access
187
188# Additional options for NTDomainController only:
189nt_dc:
190 preset_domain: null
191 preset_server: null
192
193# Additional options for PAMDomainController only:
194pam_dc:
195 service: 'login'
196 encoding: 'utf-8'
197 resetcreds: true
198
199
200# ----------------------------------------------------------------------------
201# CORS
202# (Requires `wsgidav.mw.cors.Cors`, which is enabled by default.)
203cors:
204 #: List of allowed Origins or '*'
205 #: Default: false, i.e. prevent CORS
206 allow_origin: null
207 # allow_origin: '*'
208 # allow_origin:
209 # - 'https://example.com'
210 # - 'https://localhost:8081'
211
212 #: List or comma-separated string of allowed methods (returned as
213 #: response to preflight request)
214 allow_methods:
215 # allow_methods: POST,HEAD
216 #: List or comma-separated string of allowed header names (returned as
217 #: response to preflight request)
218 allow_headers:
219 # - X-PINGOTHER
220 #: List or comma-separated string of allowed headers that JavaScript in
221 #: browsers is allowed to access.
222 expose_headers:
223 #: Set to true to allow responses on requests with credentials flag set
224 allow_credentials: false
225 #: Time in seconds for how long the response to the preflight request can
226 #: be cached (default: 5)
227 max_age: 600
228 #: Add custom response headers (dict of header-name -> header-value items)
229 #: (This is not related to CORS or required to implement CORS functionality)
230 add_always:
231 # 'X-Foo-Header: 'qux'
232
233# ----------------------------------------------------------------------------
234# Property Manager
235# null: (default) no support for dead properties
236# true: Use wsgidav.prop_man.property_manager.PropertyManager
237# which is an in-memory property manager (NOT persistent)
238#
239# Example: Use persistent shelve based property manager
240# property_manager:
241# class: wsgidav.prop_man.property_manager.ShelvePropertyManager
242# kwargs:
243# storage_path: 'wsgidav-props.shelve'
244
245property_manager: null
246
247#: Optional additional live property modification
248#: Note: by default live properties like file size and last-modified time are
249#: read-only, but that can be overriden here if the underlying DAV provider
250#: supports it. For now only the FileSystemProvider supports it and only namely
251#: changes to the last-modified timestamp. Enable it with the mutable_live_props
252#: list as below to allow clients to use the utime system call or e.g. the
253#: touch or cp / rsync commands with the preserve-timestamp flags on a mounted
254#: DAV share.
255#: Please note that the timestamp is set on the actual file or directory, so it
256#: is persistent even for in-memory property managers. It should also be noted
257#: that mutable last-modified may not be compliant with the RFC 4918.
258mutable_live_props:
259 # Enable to allow clients to use e.g. the touch or cp / rsync commands with the
260 # preserve-timestamp flags in a mounted DAV share (may be RFC4918 incompliant)
261 - '{DAV:}getlastmodified'
262
263
264# ----------------------------------------------------------------------------
265# Lock Manager Storage
266#
267# null: No lock support
268# true: (default) shortcut for
269# lock_storage: wsgidav.lock_man.lock_storage.LockStorageDict
270#
271# Note that the default LockStorageDict works in-memory, so it is
272# NOT persistent.
273#
274# Example: Use persistent shelve based lock storage:
275# lock_storage:
276# class: wsgidav.lock_man.lock_storage.LockStorageShelve
277# kwargs:
278# storage_path: /path/to/wsgidav_locks.shelve
279#
280# Check the documentation on how to develop custom lock storage.
281
282lock_storage: true
283
284
285# ==============================================================================
286# DEBUGGING
287
288#: Set verbosity level (can be overridden by -v or -q arguments)
289verbose: 3
290
291logging:
292 #: Enable logging when using wsgidav in library mode (always on, when running as CLI)
293 enable: null
294 #: Set logging output format
295 #: (see https://docs.python.org/3/library/logging.html#logging.Formatter)
296 logger_date_format: '%H:%M:%S'
297 logger_format: '%(asctime)s.%(msecs)03d - %(levelname)-8s: %(message)s'
298 # Example: Add date,thread id, and logger name:
299 # logger_date_format: '%Y-%m-%d %H:%M:%S'
300 # logger_format: '%(asctime)s.%(msecs)03d - <%(thread)05d> %(name)-27s %(levelname)-8s: %(message)s'
301
302 #: Enable specific module loggers
303 #: E.g. ['lock_manager', 'property_manager', 'http_authenticator', ...]
304 # enable_loggers: ['http_authenticator', ]
305
306 # Enable max. logging for certain http methods
307 # E.g. ['COPY', 'DELETE', 'GET', 'HEAD', 'LOCK', 'MOVE', 'OPTIONS', 'PROPFIND', 'PROPPATCH', 'PUT', 'UNLOCK']
308 debug_methods: []
309
310 # Enable max. logging during litmus suite tests that contain certain strings
311 # E.g. ['lock_excl', 'notowner_modify', 'fail_cond_put_unlocked', ...]
312 debug_litmus: []
313
314
315# ----------------------------------------------------------------------------
316# WsgiDavDirBrowser
317
318dir_browser:
319 enable: true
320 #: List of fnmatch patterns that will be hidden in the directory listing
321 ignore:
322 - '.DS_Store' # macOS folder meta data
323 - 'Thumbs.db' # Windows image previews
324 - '._*' # macOS hidden data files
325 #: Add a trailing slash to directory URLs (by generating a 301 redirect)
326 directory_slash: true
327 #: Display WsgiDAV icon in header
328 icon: true
329 #: Raw HTML code, appended as footer (true: use a default trailer)
330 response_trailer: true
331 #: Display the name and realm of the authenticated user (or 'anomymous')
332 show_user: true
333 show_logout: true
334 #: Send <dm:mount> response if request URL contains '?davmount'
335 #: (See https://tools.ietf.org/html/rfc4709)
336 davmount: true
337 #: Add a 'Mount' link at the top of the listing
338 davmount_links: false
339 #: Invoke MS Office documents for editing using WebDAV by adding a JavaScript
340 #: click handler.
341 #: - For IE 11 and below invokes the SharePoint ActiveXObject("SharePoint.OpenDocuments")
342 #: - If the custom legacy Firefox plugin is available, it will be used
343 #: https://docs.microsoft.com/en-us/previous-versions/office/developer/sharepoint-2010/ff407576(v%3Doffice.14)
344 #: - Otherwise the Office URL prefix is used (e.g. 'ms-word:ofe|u|http://server/path/file.docx')
345 ms_sharepoint_support: true
346 #: Invoke Libre Office documents for editing using WebDAV
347 libre_office_support: true
348 #: The path to the directory that contains template.html and associated
349 #: assets.
350 #: The default is the htdocs directory within the dir_browser directory.
351 htdocs_path: null
Sample wsgidav.json
#
We can also use a JSON file for configuration. The structure is identical to the YAML format.
See the ./sample_wsgidav.json example. (Note that the parser allows JavaScript-style comments)
Configuration Tips#
Running Behind a Reverse Proxy#
If WsgiDAV is running behind a reverse proxy, …
For example, when nginx is used to expose the
local WsgiDAV share http://127.0.0.1:8080/public_drive
as
http://example.com/drive
, the configuration files may look like this:
wsgidav.yaml
host: 127.0.0.1
port: 8080
mount_path: "/drive"
provider_mapping:
"/public_drive": # Exposed as http://HOST/drive by nginx reverse proxy
root: "fixtures/share"
nginx.conf
:
http {
...
server {
listen 80;
server_name example.com;
...
location /drive/ {
proxy_pass http://127.0.0.1:8080/public_drive/;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
}
# If dir browser is enabled for WsgiDAV:
location /drive/:dir_browser/ {
proxy_pass http://127.0.0.1:8080/:dir_browser/;
}
See the nginx docs for details.