Attention

You are looking at outdated documentation for version 2.x. A newer version is available.

Configuration

This document describes the configuration options of a WsgiDAV server.

The configuration file uses Python syntax to specify these options:

• Server options (hostname, port, SSL cert, …)
• List of share-name / WebDAV provider mappings
• 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)

The options described below can be defined for the CLI either

• in YAML syntax inside a wsgidav.yaml file,
• in JSON syntax inside a wsgidav.json file, or
• in Python syntax inside a wsgidav.conf file.

Note

The three supported file formats are just different ways for the CLI to generate a Python dict that is then passed to the WsgiDAVApp constructor.

See the annotated_wsgidav.conf

For a start, you should copy Sample Configuration or Annotated Sample Configuration and edit it to your needs. You can also start with a (YAML Sample Configuration) or a (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	-qq	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

Sample wsgidav.yaml

The YAML syntax is probably the most concise format to define configuration:

# Sample WsgiDAV configuration file
#
# 1. Rename this file to `wsgidav.yaml`
# 2. Adjust settings as appropriate
# 3. Run `wsgidav` from the same directory or pass file name with `--config` option.
#
# See http://wsgidav.readthedocs.io/en/latest/user_guide_configure.html

host: 0.0.0.0
port: 8080

# Set verbosity to standard
verbose: 1

# Remove this block to prevent directory browsing
dir_browser:
    enable: true
    response_trailer:
    davmount: false
    ms_mount: false
    ms_sharepoint_plugin: true
    ms_sharepoint_urls: false

provider_mapping:
    "/share1": "/path/to/share1"
    "/share2": "/path/to/share2"

user_mapping:
    "/share1":
        "user1":
            password: "abc123"
            description: "User 1 for Share 1"
            roles: []
    "/share2":
        "user1":
            password: "def456"
            description: "User 1 for Share 2"
            roles: []
        "user2":
            password: "qwerty"
            description: "User 2 for Share 2"
            roles: []

acceptbasic: false
acceptdigest: true
defaultdigest: true

Sample wsgidav.json

We can also use a JSON file for configuration if we don’t require the full power of Python code to set everything up.

Note that the parser ignores JavaScript-style comments:

/* Sample WsgiDAV configuration file
 *
 * 1. Rename this file to `wsgidav.json`
 * 2. Adjust settings as appropriate
 * 3. Run `wsgidav` from the same directory or pass file name with `--config` option.
 *
 * JSON formatted, but JavaScript-style comments are allowed.
 *
 * See http://wsgidav.readthedocs.io/en/latest/user_guide_configure.html
 */
{
    "host": "0.0.0.0",
    "port": 8080,
    // Verbosity 0..3
    "verbose": 1,
    // Remove this block to prevent directory browsing
    "dir_browser": {
        "enable": true,
        "response_trailer": "",
        "davmount": false,
        "ms_mount": false,
        "ms_sharepoint_plugin": true,
        "ms_sharepoint_urls": false
    },
    "provider_mapping": {
        "/share1": "/path/to/share1",
        "/share2": "/path/to/share2"
    },
    "user_mapping": {
        "/share1": {
            "user1": {
                "password": "abc123",
                "description": "User 1 for Share 1",
                "roles": []
            }
        },
        "/share2": {
            "user1": {
                "password": "def456",
                "description": "User 1 for Share 2",
                "roles": []
            },
            "user2": {
                "password": "qwerty",
                "description": "User 2 for Share 2",
                "roles": []
            }
        }
    },
    "acceptbasic": false,
    "acceptdigest": true,
    "defaultdigest": true
}

Sample wsgidav.conf

This format uses plain Python syntax, which allows us to use Python data structures, and even write helpers function, etc.

# Note: This file is in Python syntax and format

################################################################################
# WsgiDAV configuration file
# See
#   http://wsgidav.readthedocs.io/en/latest/run-configure.html
# for some explanation of the configuration file format.
################################################################################

# HELPERS - Do not modify this section

provider_mapping = {}
user_mapping = {}

def addShare(shareName, davProvider):
    provider_mapping[shareName] = davProvider


def addUser(realmName, user, password, description, roles=[]):
    realmName = "/" + realmName.strip(r"\/")
    userDict = user_mapping.setdefault(realmName, {}).setdefault(user, {})
    userDict["password"] = password
    userDict["description"] = description
    userDict["roles"] = roles


################################################################################
# SERVER OPTIONS
#===============================================================================
# Run WsgiDAV inside this  WSGI server.
# Supported servers: "cheroot", "cherrypy-wsgiserver", "ext_wsgiutils",
#     "flup-fcgi", "flup-fcgi-fork", "paste", "wsgiref"
# 'wsgiref' and 'ext_wsgiutils' are simple builtin servers that should *not* be
# used in production.
# All other servers must have been installed before, e.g. `pip install cheroot`.
# (The binary distribution already includes 'cheroot'.)
# Default: "cheroot", use the --server option on command line to change this.

#server = "cheroot"

# Additional arguments passed to the server on initialization (depends on `server`)
# For example for cheroot:

#server_args = {
#    "numthreads": 10,
#    "max": -1,
#    "request_queue_size": 5,
#    "timeout": 10,
#    "shutdown_timeout": 5,
#    "verbose": 0,
#}

# Server port (default: 8080, use --port on command line)
port = 8080

# Server hostname (default: localhost, use --host on command line)
host = "localhost"

#===============================================================================
# Enable SSL support
# Note:
# A valid certificate must match the servers hostname, so the bogus certs will
# not work in all scenarios.
# Create your own certificates instead!

# ssl_certificate = "wsgidav/server/sample_bogo_server.crt"
# ssl_private_key = "wsgidav/server/sample_bogo_server.key"
# ssl_certificate_chain = None

# Cheroot server supports 'builtin' and 'pyopenssl' (default: 'builtin')
# ssl_adapter = "pyopenssl"


#================================================================================
# Misc. setings
#

# Add the MS-Author-Via Response Header to OPTIONS command to allow editing
# with Microsoft Office (default: False)

add_header_MS_Author_Via = True


# Block size in bytes

# block_size = 8192


# Set this to True, to force unquoting of PATH_INFO. This should already be done by the WSGI
# Framework, so this setting should only be used to fix unexpected problems there (see issue #8).

# unquote_path_info = False


# Re-encode PATH_INFO using UTF-8 (falling back to ISO-8859-1).
# This seems to be wrong, since per PEP 3333 PATH_INFO is always ISO-8859-1 encoded
# (see https://www.python.org/dev/peps/pep-3333/#unicode-issues).
# However it seems to resolve errors when accessing resources with Chinese characters, for
# example (see issue #73).
# Set to `None` (the default) to enable this for Python 3 only.

# re_encode_path_info = None


#===============================================================================
# Middlewares
#
# Use this section to modify the default middleware stack

#from wsgidav.dir_browser import WsgiDavDirBrowser
#from debug_filter import WsgiDavDebugFilter
#from http_authenticator import HTTPAuthenticator
#from error_printer import ErrorPrinter
#middleware_stack = [ WsgiDavDirBrowser, HTTPAuthenticator, ErrorPrinter, WsgiDavDebugFilter ]

#===============================================================================
# Debugging

verbose = 3          # 0 - quiet
                     # 1 - no output (excepting application exceptions)
                     # 2 - warnings and errors only
                     # 3 - show single line request summaries (HTTP logging)
                     # 4 - show additional events
                     # 5 - show full request/response header info (HTTP Logging)
                     #     request body and GET response bodies not shown


# Enable specific module loggers
# E.g. ["lock_manager", "property_manager", "http_authenticator", ...]
enable_loggers = []

# Enable max. logging for certain http methods
# E.g. ["COPY", "DELETE", "GET", "HEAD", "LOCK", "MOVE", "OPTIONS", "PROPFIND", "PROPPATCH", "PUT", "UNLOCK"]
debug_methods = []

# Enable max. logging during  litmus suite tests that contain certain strings
# E.g. ["lock_excl", "notowner_modify", "fail_cond_put_unlocked", ...]
debug_litmus = []


################################################################################
# WsgiDavDirBrowser

dir_browser = {
    "enable": True,               # Render HTML listing for GET requests on collections
    "response_trailer": "",       # Raw HTML code, appended as footer
    "davmount": False,            # Send <dm:mount> response if request URL contains '?davmount'
    "ms_mount": False,            # Add an 'open as webfolder' link (requires Windows)
    "ms_sharepoint_plugin": True, # Invoke MS Offce documents for editing using WebDAV
    "ms_sharepoint_urls": False,  # Prepend 'ms-word:ofe|u|' to URL for MS Offce documents
#    "app_class": MyBrowser,      # (DEPRECATED with 2.4.0) Used instead of WsgiDavDirBrowser
}


################################################################################
# DAV Provider

#===============================================================================
# Property Manager
#
# Uncomment this lines to specify your own property manager.
# Default:        no support for dead properties
# Also available: wsgidav.property_manager.PropertyManager
#                 wsgidav.property_manager.ShelvePropertyManager
#
# Check the documentation on how to develop custom property managers.
# Note that the default PropertyManager works in-memory, and thus is NOT
# persistent.

### Use in-memory property manager (NOT persistent)
# (this is the same as passing 'propsmanager = True')
#from wsgidav.property_manager import PropertyManager
#propsmanager = PropertyManager()

### Use persistent shelve based property manager
#from wsgidav.property_manager import ShelvePropertyManager
#propsmanager = ShelvePropertyManager("wsgidav-props.shelve")

### Use persistent MongoDB based property manager
#from wsgidav.addons.mongo_property_manager import MongoPropertyManager
#prop_man_opts = {}
#propsmanager = MongoPropertyManager(prop_man_opts)

### Use persistent CouchDB based property manager
#from wsgidav.addons.couch_property_manager import CouchPropertyManager
#prop_man_opts = {}
#propsmanager = CouchPropertyManager(prop_man_opts)

### Use in-memory property manager (NOT persistent)
propsmanager = True


### Optional additional live property modification
# Note: by default live properties like file size and last-modified time are
# read-only, but that can be overriden here if the underlying DAV provider
# supports it. For now only the FileSystemProvider supports it and only namely
# changes to the last-modified timestamp. Enable it with the mutable_live_props
# list as below to allow clients to use the utime system call or e.g. the
# touch or cp / rsync commands with the preserve-timestamp flags on a mounted
# DAV share.
# Please note that the timestamp is set on the actual file or directory, so it
# is persistent even for in-memory property managers. It should also be noted
# that mutable last-modified may not be compliant with the RFC 4918.
#mutable_live_props = ["{DAV:}getlastmodified"]


#===============================================================================
# Lock Manager
#
# Uncomment this lines to specify your own locks manager.
# Default:        wsgidav.lock_storage.LockStorageDict
# Also available: wsgidav.lock_storage.LockStorageShelve
#
# Check the documentation on how to develop custom lock managers.
# Note that the default LockStorageDict works in-memory, and thus is NOT
# persistent.

# Example: Use in-memory lock storage
#          (this is the same as passing 'locksmanager = True', which is default)
#from wsgidav.lock_storage import LockStorageDict
#locksmanager = LockStorageDict()


# Example: Use PERSISTENT shelve based lock manager
#from wsgidav.lock_storage import LockStorageShelve
#locksmanager = LockStorageShelve("wsgidav-locks.shelve")


################################################################################
# SHARES
#
# If you would like to publish files in the location '/v_root' through a
# WsgiDAV share 'files', so that it can be accessed by this URL:
#     http://server:port/files
# insert the following line:
#     addShare("files", "/v_root")
# or, on a Windows box:
#     addShare("files", "c:\\v_root")
#
# To access the same directory using a root level share
#     http://server:port/
# insert this line:
#     addShare("", "/v_root")
#
# The above examples use wsgidav.fs_dav_provider.FilesystemProvider, which is
# the default provider implementation.
#
# If you wish to use a custom provider, an object must be passed as second
# parameter. See the examples below.


### Add a read-write file share:
addShare("dav", r"C:\temp")

### Add a read-only file share:
#from wsgidav.fs_dav_provider import FilesystemProvider
#addShare("tmp", FilesystemProvider("/tmp", readonly=True))


### Publish an MySQL 'world' database as share '/world-db'
#from wsgidav.addons.mysql_dav_provider import MySQLBrowserProvider
#addShare("world-db", MySQLBrowserProvider("localhost", "root", "test", "world"))


### Publish a virtual structure
#from wsgidav.samples.virtual_dav_provider import VirtualResourceProvider
#addShare("virtres", VirtualResourceProvider())


### Publish a Mercurial repository
#from wsgidav.addons.hg_dav_provider import HgResourceProvider
#addShare("hg", HgResourceProvider("PATH_OR_URL"))


### Publish a MongoDB
#from wsgidav.samples.mongo_dav_provider import MongoResourceProvider
#mongo_dav_opts = {}
#addShare("mongo", MongoResourceProvider(mongo_dav_opts))


################################################################################
# AUTHENTICATION
#===============================================================================
# HTTP Authentication Options

acceptbasic = True    # Allow basic authentication, True or False
acceptdigest = True   # Allow digest authentication, True or False
defaultdigest = True  # True (default digest) or False (default basic)

# Enter the name of a header field that will be accepted as authorized user.
# Including quotes, for example: trusted_auth_header = "REMOTE_USER"
trusted_auth_header = None


#===============================================================================
# Domain Controller
# Uncomment this line to specify your own domain controller
# Default: wsgidav.domain_controller, which uses the USERS section below
#
# Example:
#   use a domain controller that allows users to authenticate against a
#   Windows NT domain or a local computer.
#   Note: NTDomainController requires basic authentication:
#         Set acceptbasic=True, acceptdigest=False, defaultdigest=False

#from wsgidav.addons.nt_domain_controller import NTDomainController
#domaincontroller = NTDomainController(presetdomain=None, presetserver=None)
#acceptbasic = True
#acceptdigest = False
#defaultdigest = False


#===============================================================================
# USERS
#
# This section is ONLY used by the DEFAULT Domain Controller.
#
# Users are defined per realm:
#     addUser(<realm>, <user>, <password>, <description>)
#
# Note that the default Domain Controller uses the share name as realm name.
#
# If no users are specified for a realm, no authentication is required.
# Thus granting read-write access to anonymous!
#
# Note: If you wish to use Windows WebDAV support (such as Windows XP's My
# Network Places), you need to include the domain of the user as part of the
# username (note the DOUBLE slash), such as:
# addUser("v_root", "domain\\user", "password", "description")

addUser("", "tester", "secret", "")
addUser("", "tester2", "secret2", "")

#addUser("dav", "tester", "secret", "")
#addUser("dav", "tester2", "secret2", "")

#addUser("virtres", "tester", "secret", "")