WebDAV Setup for Sprite

WEBDAV.md

WebDAV Setup Guide for Sprite VM

This guide documents the complete setup process for running a WebDAV server in a Sprite VM, allowing file access via HTTP from macOS or other WebDAV clients.

Overview

• Server: WsgiDAV (Python-based WebDAV server)
• Web Server: Cheroot (bundled with WsgiDAV)
• Port: 8080 (configured as Sprite HTTP service)
• Served Directory: /home/sprite (entire home directory)
• Authentication: HTTP Basic Auth (username: sprite, password: sprite)

Installation Steps

1. Install WsgiDAV

pip3 install --user WsgiDAV cheroot

This installs:

• WsgiDAV - WebDAV server implementation
• cheroot - Pure-Python HTTP server
• Dependencies: defusedxml, Jinja2, json5, PyYAML, MarkupSafe

The wsgidav binary is installed to ~/.local/bin/wsgidav

2. Install jq (Required for sprite-env)

sudo apt-get update
sudo apt-get install -y jq

Note: sprite-env requires jq for JSON parsing. Skip this if already installed.

3. Create WebDAV Configuration File

Create ~/.wsgidav.yaml with the following content:

host: 0.0.0.0
port: 8080
server: cheroot

# Authentication - enable basic auth
http_authenticator:
  domain_controller: wsgidav.dc.simple_dc.SimpleDomainController
  accept_basic: true
  accept_digest: false
  default_to_digest: false

simple_dc:
  user_mapping:
    "/":
      "sprite":
        password: "sprite"
        description: "Sprite user"
        roles: []

# Serve home directory
provider_mapping:
  "/": /home/sprite

# Verbose logging
verbose: 1

# Enable directory browsing
dir_browser:
  enabled: true
  response_trailer: ""

Configuration Notes:

• host: 0.0.0.0 - Listen on all interfaces
• port: 8080 - Must match the --http-port in service creation
• server: cheroot - Use Cheroot web server
• provider_mapping - Maps URL path / to filesystem path /home/sprite
• simple_dc.user_mapping - Basic authentication credentials
• dir_browser.enabled: true - Allows browsing directories via web browser
• verbose: 1 - Enable logging for troubleshooting

4. Create Sprite Service

sprite-env services create webdav \
  --cmd /home/sprite/.local/bin/wsgidav \
  --args "--config=/home/sprite/.wsgidav.yaml" \
  --http-port 8080 \
  --dir /home/sprite \
  --duration 10s

Command Explanation:

• webdav - Service name
• --cmd - Full path to wsgidav executable
• --args - Command line arguments (config file path)
• --http-port 8080 - Routes Sprite proxy to this port; enables auto-start
• --dir /home/sprite - Working directory
• --duration 10s - Stream logs for 10 seconds after creation

5. Verify Installation

Check service status:

sprite-env services list

Expected output shows "status":"running" for the webdav service.

Test locally:

curl -u sprite:sprite http://localhost:8080/

Test WebDAV PROPFIND (list files):

curl -u sprite:sprite -X PROPFIND http://localhost:8080/ -H "Depth: 1"

View logs:

cat /.sprite/logs/services/webdav.log

Connecting from macOS

Option 1: Finder (Built-in WebDAV Client)

1. Get your Sprite URL from the Sprite dashboard/CLI
   • Format: https://your-sprite-id.sprites.dev
2. Open Finder
3. Press ⌘K or Go → Connect to Server
4. Enter your Sprite URL: https://your-sprite-id.sprites.dev
5. Username: sprite
6. Password: sprite
7. Click Connect

The home directory will mount as a network drive.

Option 2: Third-Party Clients

Cyberduck (Free, Open Source)

• Download: https://cyberduck.io
• Add bookmark with your Sprite URL
• Protocol: WebDAV (HTTPS)

Mountain Duck ($39, Mounts as Disk)

• Download: https://mountainduck.io
• Mounts WebDAV as a native disk in Finder
• By Cyberduck developers

Transmit ($45, Professional)

• Download: https://panic.com/transmit

Command Line (curl)

curl -u sprite:sprite https://your-sprite-id.sprites.dev/

Service Management

Check Service Status

sprite-env services list
sprite-env services get webdav

Stop Service

sprite-env services signal webdav TERM

Restart Service

# Stop service
sprite-env services signal webdav TERM

# Service will auto-restart on next HTTP request
# Or manually recreate:
sprite-env services create webdav \
  --cmd /home/sprite/.local/bin/wsgidav \
  --args "--config=/home/sprite/.wsgidav.yaml" \
  --http-port 8080 \
  --dir /home/sprite \
  --duration 10s

Delete Service

sprite-env services delete webdav

View Logs

# View all logs
cat /.sprite/logs/services/webdav.log

# Follow logs in real-time
tail -f /.sprite/logs/services/webdav.log

Customization

Change Password

1. Edit ~/.wsgidav.yaml
2. Update the password field:

   simple_dc:
     user_mapping:
       "/":
         "sprite":
           password: "your-new-password"

3. Restart the service:

   sprite-env services signal webdav TERM

Change Served Directory

1. Edit ~/.wsgidav.yaml
2. Update the provider_mapping:

   provider_mapping:
     "/": /path/to/your/directory

3. Optionally update the service working directory:

   sprite-env services delete webdav
   sprite-env services create webdav \
     --cmd /home/sprite/.local/bin/wsgidav \
     --args "--config=/home/sprite/.wsgidav.yaml" \
     --http-port 8080 \
     --dir /path/to/your/directory

Add Multiple Users

Edit ~/.wsgidav.yaml:

simple_dc:
  user_mapping:
    "/":
      "sprite":
        password: "password1"
        description: "Primary user"
        roles: []
      "user2":
        password: "password2"
        description: "Second user"
        roles: []

Disable Authentication (Not Recommended)

Edit ~/.wsgidav.yaml and remove the http_authenticator section entirely.

Warning: Only do this if you're certain the Sprite URL remains private or you've configured proper access controls externally.

Change Port

1. Edit ~/.wsgidav.yaml - update port: 8080 to your desired port
2. Recreate the service with the new --http-port value:

   sprite-env services delete webdav
   sprite-env services create webdav \
     --cmd /home/sprite/.local/bin/wsgidav \
     --args "--config=/home/sprite/.wsgidav.yaml" \
     --http-port YOUR_NEW_PORT \
     --dir /home/sprite

Note: Only one service can have an http_port configured in Sprite.

Troubleshooting

Service Won't Start

Check logs:

cat /.sprite/logs/services/webdav.log

Verify wsgidav is installed:

ls -la ~/.local/bin/wsgidav

Test configuration:

~/.local/bin/wsgidav --config=~/.wsgidav.yaml --help

Can't Connect from macOS

1. Verify service is running:

   sprite-env services list

2. Test local connectivity:

   curl -u sprite:sprite http://localhost:8080/

3. Verify your Sprite URL is correct (get from Sprite dashboard/CLI)

4. Check network policy allows your client domain:

   cat /.sprite/policy/network.json

Authentication Fails

1. Verify credentials in ~/.wsgidav.yaml
2. Ensure you restarted the service after changing password
3. Check logs for authentication errors:

   tail -f /.sprite/logs/services/webdav.log

Permission Denied Errors

WsgiDAV runs as the sprite user. Ensure served directories have proper permissions:

ls -la /home/sprite

Fix permissions if needed:

chmod 755 /home/sprite
chmod 644 /home/sprite/file.txt  # for files
chmod 755 /home/sprite/directory  # for directories

Persistence

Automatic Service Restart

Sprite services automatically restart when the VM boots, so your WebDAV server will be available after VM restarts.

Creating a Checkpoint

Save the current state including WebDAV configuration:

sprite-env checkpoints create "WebDAV server configured and running"

Restore from checkpoint:

sprite-env checkpoints restore v5  # Replace v5 with your checkpoint ID

Warning: Restoring a checkpoint drops the entire session and restarts the VM.

Security Considerations

1. Change Default Password: The default password sprite should be changed immediately
2. Sprite URL Authentication: By default, Sprite URLs require authentication, providing an additional security layer
3. HTTPS: Sprite proxy provides HTTPS, encrypting traffic between your client and the VM
4. Limited Exposure: Only expose the directories you actually need via provider_mapping
5. Public Access: If you make your Sprite URL public via the Sprite API, ensure strong passwords
6. Read-Only Access: To prevent modifications, WsgiDAV supports read-only mode (not configured in this setup)

File Structure

After setup, your VM will have:

/home/sprite/
├── .wsgidav.yaml              # WebDAV configuration
├── .local/
│   └── bin/
│       └── wsgidav            # WebDAV executable
└── .local/lib/python3.13/site-packages/
    ├── WsgiDAV/               # WebDAV library
    └── cheroot/               # Web server library

/.sprite/
├── logs/
│   └── services/
│       └── webdav.log         # Service logs
└── checkpoints/               # Checkpoints for backup/restore

Additional Resources

• WsgiDAV Documentation: https://wsgidav.readthedocs.io/
• Sprite Documentation: /.sprite/docs/
• WebDAV Protocol: RFC 4918

Quick Reference

# Start service (first time)
sprite-env services create webdav --cmd ~/.local/bin/wsgidav --args "--config=~/.wsgidav.yaml" --http-port 8080 --dir /home/sprite

# Check status
sprite-env services list

# View logs
cat /.sprite/logs/services/webdav.log

# Restart service
sprite-env services signal webdav TERM

# Delete service
sprite-env services delete webdav

# Create checkpoint
sprite-env checkpoints create "Description"

Summary

This setup provides a fully functional WebDAV server that:

• ✓ Runs as a Sprite service with auto-start on HTTP requests
• ✓ Serves your home directory with full read/write access
• ✓ Uses HTTP Basic authentication for security
• ✓ Automatically restarts on VM boot
• ✓ Provides HTTPS access via Sprite's proxy
• ✓ Works with all standard WebDAV clients

The server will be accessible at your Sprite URL and can be managed entirely through the sprite-env CLI.