Configuration

PyWebDAV Server offers flexible configuration through command-line options, configuration files, and environment variables.

Backend Configuration

PyWebDAV Server uses vaultconfig to manage backend configurations with secure password obscuring.

Configuration Location

Backend configurations are stored in:

  • Linux/macOS: ~/.config/pywebdavserver/backends.toml

  • Windows: %APPDATA%\pywebdavserver\backends.toml

Interactive Configuration

The easiest way to configure backends is using the interactive wizard:

pywebdavserver config

This launches an interactive session where you can:

  • Add new backends

  • List existing backends

  • Show backend details

  • Remove backends

Managing Backends

Add a backend interactively:

pywebdavserver config

Then select option 2 (Add backend) and follow the prompts:

Add new backend
Backend name: my-local
Backend type (local, drime): local
Root directory path [/tmp/webdav]: /srv/webdav
Read-only mode? [y/N]: n

✓ Backend 'my-local' added successfully

List backends:

pywebdavserver config

Then select option 1 (List backends).

Remove a backend:

pywebdavserver config

Then select option 4 (Remove backend) and enter the backend name.

Show backend details:

pywebdavserver config

Then select option 3 (Show backend) and enter the backend name.

Password Obscuring

PyWebDAV Server automatically obscures sensitive values (passwords, API keys) in configuration files using a custom cipher key.

Important: This is obfuscation, not encryption. It prevents casual viewing but is not cryptographically secure. For production security, use proper access controls and file permissions.

The obscuring uses a randomly generated cipher key unique to pywebdavserver:

# In pywebdavserver/config.py
_PYWEBDAVSERVER_CIPHER_KEY = "..."

This means:

  • Other applications cannot reveal pywebdavserver passwords

  • Passwords are not stored in plain text

  • The cipher key is embedded in the package

Manual Configuration

You can also manually edit the TOML configuration file:

[my-local]
type = "local"
path = "/srv/webdav"
readonly = false

[drime-personal]
type = "drime"
api_key = "qO-l2HqnGGNrZM3ga4UI50iwySHFTmVl1pe2NW0oOxKQqBZWUw4"  # Obscured
workspace_id = 0
readonly = false
cache_ttl = 30.0
max_file_size = 524288000

Server Configuration

Command-Line Options

The pywebdavserver serve command accepts various options:

Storage Options:

  • --backend TEXT - Backend name or type (local/drime)

  • --backend-config TEXT - Named backend from configuration

  • --path PATH - Data directory for local backend

Network Options:

  • --host TEXT - Host address (default: 127.0.0.1)

  • --port INTEGER - Port number (default: 8080)

  • --ssl-cert PATH - SSL certificate file

  • --ssl-key PATH - SSL private key file

Authentication:

  • --no-auth - Disable authentication

  • --username TEXT - WebDAV username

  • --password TEXT - WebDAV password

Repository Options:

  • --readonly - Enable read-only mode (prevents writes)

Drime Backend Options:

  • --workspace-id INTEGER - Workspace ID (0 = personal)

  • --cache-ttl FLOAT - Cache TTL in seconds

  • --max-file-size INTEGER - Maximum file size in bytes

Debug:

  • -v, --verbose - Increase verbosity (repeat for more detail)

Environment Variables

PyWebDAV Server respects several environment variables:

Drime Backend:

  • DRIME_API_KEY - Drime API key

Configuration:

  • PYWEBDAVSERVER_CONFIG_DIR - Override default config directory

Authentication Setup

Basic Authentication

PyWebDAV Server supports HTTP Basic Authentication:

pywebdavserver serve \
    --backend local \
    --path /srv/webdav \
    --username admin \
    --password secret123

Security Note: Passwords are sent in base64 encoding (not encrypted). Always use HTTPS in production!

Anonymous Access

For development or public access:

pywebdavserver serve \
    --backend local \
    --path /srv/webdav \
    --no-auth

Warning: Only use --no-auth for development or when behind a secure gateway.

SSL/TLS Configuration

Generate Self-Signed Certificate

For testing:

openssl req -x509 -newkey rsa:4096 \
    -keyout key.pem \
    -out cert.pem \
    -days 365 \
    -nodes \
    -subj "/CN=localhost"

Start Server with SSL

pywebdavserver serve \
    --backend local \
    --path /srv/webdav \
    --ssl-cert cert.pem \
    --ssl-key key.pem \
    --username admin \
    --password secret123

Access the server:

# With self-signed cert
curl -k https://localhost:8080/ -u admin:secret123

Let’s Encrypt

For production, use Let’s Encrypt certificates:

# Get certificate with certbot
sudo certbot certonly --standalone -d webdav.example.com

# Start server
pywebdavserver serve \
    --backend local \
    --path /srv/webdav \
    --host 0.0.0.0 \
    --port 443 \
    --ssl-cert /etc/letsencrypt/live/webdav.example.com/fullchain.pem \
    --ssl-key /etc/letsencrypt/live/webdav.example.com/privkey.pem \
    --username admin \
    --password secret123

Read-Only Mode

In read-only mode, files can be read but not modified. This protects against:

  • Accidental modification

  • Unauthorized file changes

  • Data corruption

Enable read-only mode:

pywebdavserver serve \
    --backend local \
    --path /srv/webdav \
    --readonly

With read-only mode:

  • ✅ GET (download) works

  • ✅ PROPFIND (list) works

  • ✅ HEAD (metadata) works

  • ❌ PUT (upload) fails

  • ❌ DELETE (delete) fails

  • ❌ MKCOL (create directory) fails

  • ❌ MOVE (rename) fails

  • ❌ COPY (copy) fails

Note: Administrators can still modify files by accessing the storage directly.

Example Configuration Files

Production Setup

systemd service file (/etc/systemd/system/pywebdavserver.service):

[Unit]
Description=PyWebDAV Server - WebDAV server with pluggable backends
After=network.target

[Service]
Type=simple
User=webdav
Group=webdav
ExecStart=/usr/local/bin/pywebdavserver serve \
    --backend-config production-local \
    --host 0.0.0.0 \
    --port 8080 \
    --username admin \
    --password secret123
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Backend configuration (~/.config/pywebdavserver/backends.toml):

[production-local]
type = "local"
path = "/srv/webdav"
readonly = false

[production-drime]
type = "drime"
api_key = "qO-l2HqnGGNrZM3ga4UI50iwySHFTmVl1pe2NW0oOxKQqBZWUw4"
workspace_id = 0
readonly = false
cache_ttl = 30.0
max_file_size = 524288000

[backup-readonly]
type = "local"
path = "/backup/webdav"
readonly = true

Development Setup

For local development:

#!/bin/bash
# dev-server.sh

pywebdavserver serve \
    --backend local \
    --path /tmp/webdav-dev \
    --no-auth \
    -vvv

WebDAV Clients

Linux

davfs2:

# Install
sudo apt-get install davfs2

# Mount
sudo mount -t davfs http://localhost:8080/ /mnt/webdav

# With authentication
sudo mount -t davfs -o username=admin,password=secret123 \
    http://localhost:8080/ /mnt/webdav

# Add to /etc/fstab for automatic mounting
echo "http://localhost:8080/ /mnt/webdav davfs user,noauto 0 0" | \
    sudo tee -a /etc/fstab

cadaver:

# Install
sudo apt-get install cadaver

# Connect
cadaver http://localhost:8080/

macOS

Finder:

  1. Open Finder

  2. Press Cmd+K (or Go → Connect to Server)

  3. Enter: http://localhost:8080/

  4. Click Connect

Command line:

# Mount
mkdir ~/webdav
mount_webdav http://localhost:8080/ ~/webdav

Windows

Map Network Drive:

  1. Open File Explorer

  2. Right-click “This PC”

  3. Select “Map network drive”

  4. Enter: http://localhost:8080/

  5. Check “Connect using different credentials” if needed

Command line:

net use W: http://localhost:8080/ /user:admin secret123

Next Steps

  • Learn about backends for storage options

  • Read security for production deployment

  • See Command Line Interface for complete command reference