oddmu-webdav(5)

Name

oddmu-webdav - how to setup Web-DAV using Apache for Oddmu

Description

With the Apache Web-DAV module enabled, users can mount the wiki as a remote file system and edit files using their favourite text editor. If you want to offer users direct file access to the wiki, this can be accomplished via ssh, sftp or Web-DAV.

The benefit of using the Apache Web-DAV module is that access has to be configured only once.

Configuration

In the following example, "data" is not an action provided by Oddmu but an actual directory for Oddmu files. In the example below, "/home/alex/campaignwiki.org/data" is both the document root for static files and the data directory for Oddmu. This is the directory where Oddmu needs to run. When users request the "/data" path, authentication is required but the request is not proxied to Oddmu since the "ProxyPassMatch" directive doesn't handle "/data". Instead, Apache gets to handle it. Since "data" is part of all the "LocationMatch" directives, credentials are required to save (PUT) files.

"Dav On" enables Web-DAV for the "knochentanz" wiki. It is enabled for all the actions, but since only "/data" is handled by Apache, this has no effect for all the other actions, allowing us to specify the required users only once.

MDomain campaignwiki.org

<VirtualHost *:80>
    ServerName campaignwiki.org
    Redirect permanent / https://campaignwiki.org/
</VirtualHost>

<VirtualHost *:443>
    ServerAdmin alex@campaignwiki.org
    ServerName campaignwiki.org
    DocumentRoot /home/alex/campaignwiki.org
    <Directory /home/alex/campaignwiki.org>
        Options Includes Indexes MultiViews SymLinksIfOwnerMatch
        AllowOverride All
	Require all granted
    </Directory>
    SSLEngine on
    ProxyPassMatch \
      "^/((view|preview|diff|edit|save|add|append|upload|drop|list|delete|search|archive/.+)/(.*))$" \
      "unix:/home/oddmu/campaignwiki.sock|http://localhost/$1"
    # /archive only for subdirectories
    Redirect "/archive/data.zip" "/view/archive"
    <LocationMatch "^/(data|edit|preview|save|add|append|upload|drop|list|delete)/">
      AuthType Basic
      AuthName "Password Required"
      AuthUserFile /home/oddmu/.htpasswd
      Require user admin alex
    </LocationMatch>
    <LocationMatch "^/(data|edit|preview|save|add|append|upload|drop|list|delete|archive)/knochentanz">
      Require user admin alex knochentanz
      Dav On
    </LocationMatch>
</VirtualHost>

In order for this to work, you must enable the mod_dav_fs module. This automatically enables to the mod_dav module, too. Restart the server after installing enabling a module.

sudo a2enmod mod_dav_fs
sudo apachectl restart

Check the permissions for the data directory. If the Oddmu service uses the "oddmu" user and Apache uses the "www-data" user, you could add the data directory to the "www-data" group and give it write permissions:

sudo chown oddmu:www-data /home/alex/campaignwiki.org/data/knochentanz
sudo chmod g+w /home/alex/campaignwiki.org/data/knochentanz

Examples

Web-DAV clients are often implemented such that they only work with servers that exactly match their assumptions. If you're trying to use *gvfs*(7), the Windows File Explorer or the macOS Finder to edit Oddmu pages using Web-DAV, you're on your own.

This section has examples sessions using tools that work.

cadaver

Here's how to use *cadaver*(1). The "edit" command uses the editor specified in the EDITOR environment variable. In this example, that's "emacsclient --alternate-editor= ".

cadaver https://campaignwiki.org/data/knochentanz/
Authentication required for Password Required on server `campaignwiki.org':
Username: knochentanz
Password: 
dav:/data/knochentanz/> edit index.md
Locking `index.md': succeeded.
Downloading `/data/knochentanz/index.md' to /tmp/cadaver-edit-fHTllt.md
Progress: [=============================>] 100.0% of 2725 bytes succeeded.
Running editor: `emacsclient --alternate-editor= /tmp/cadaver-edit-fHTllt.md'...
Waiting for Emacs...
Changes were made.
Uploading changes to `/data/knochentanz/index.md'
Progress: [=============================>] 100.0% of 2726 bytes succeeded.
Unlocking `index.md': succeeded.

curl and hdav

Here's how to use *curl*(1) to get the file from the public "/view" location and how to use *hdav*(1) to put the file to the protected "/data" location. In this example, *ed*(1) is used to append the word "test" to the file.

alex@melanobombus ~> curl --output index.md https://campaignwiki.org/view/knochentanz/index.md
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  2726  100  2726    0     0  36662      0 --:--:-- --:--:-- --:--:-- 37861
alex@melanobombus ~> ed index.md 
2726
a
test
.
w
2731
q
alex@melanobombus ~> hdav put index.md https://campaignwiki.org/data/knochentanz/index.md --username knochentanz
hDAV version 1.3.4, Copyright (C) 2012-2016  Clint Adams
hDAV comes with ABSOLUTELY NO WARRANTY.
This is free software, and you are welcome to redistribute it
under certain conditions.

Password for knochentanz at URL https://campaignwiki.org/data/knochentanz/index.md: ********

davfs2

Here's how to use *davfs2*(1) using *mount*(1). Now the whole wiki is mounted and can be edited like local files. In this example, *echo*(1) and redirection is used to append the word "test" to a file.

alex@melanobombus ~> mkdir knochentanz
alex@melanobombus ~> sudo mount -t davfs -o username=knochentanz,uid=alex \
    https://campaignwiki.org/data/knochentanz/ knochentanz/
  Password:  ********
alex@melanobombus ~> echo test >> knochentanz/index.md

Authors

Maintained by Alex Schroeder alex@gnu.org.

alex@gnu.org