Configuring a WebDAV server for OmniPresence sync

Please note: due to the wide array of possible setup configurations and outside factors involved with custom hosting setups, troubleshooting, setting up, or administering WebDAV servers is beyond the scope of the tech support we are able to provide.

IMPORTANT: When you expose files and folders on your computer to the internet (even with password protection), you assume some risk. These steps assume that you’re familiar with the Apache web server and understand this risk. You should be comfortable with the responsibilities of maintaining a server, including keeping your Mac up to date with the latest security patches. These instructions are offered as guidance for those interested in self-hosting, but should not be considered a comprehensive overview of the Apache implementation process.

Setting up WebDAV without Server.app

OS X Server includes WebDAV as one of the options for file sharing. However, this WebDAV implementation is a fairly complex configuration that utilizes a proxy to create Apache processes that run as user accounts. In our experience this configuration has had a number of hard-to-identify bugs that can corrupt your data. We don’t recommend using it at this time.

Instead of using OS X Server’s built-in file sharing WebDAV configuration, we recommend manually configuring a WebDAV share by editing the appropriate Apache configuration file. This requires some knowledge of both the Apache web server and Apple’s implementation. You should also be comfortable with the command line. This configuration will emulate Apple’s configuration by allowing you to login to a WebDAV share using system account credentials. You will also be able to use posix group permissions to control access to the shares. However, all files and folders must be owned by the Apache web server (_www) since this configuration will use the web server’s account to read/write all files.

• For more information about the Apache httpd server, see the excellent documentation on apache.org

• There is an overview of Apple’s configuration of the Apache httpd server see their documentation website. While Apple’s documentation is sparse, they do outline what directories are used for configuration files, which is a great place to start poking around.

• Take particular note of Apple’s ReadMe.txt file (/Library/Server/web/config/Apache2/ReadMe.txt). It goes into more operational details about what they’ve configured and what you may and may not touch.

Configuring Apache

Assuming that you have never used Apple’s built-in file sharing feature to host WebDAV configuring Apache is fairly straightforward.

Make a copy of the example WebDAV configuration file and move it to OS X Server’s website configuration directory. The example configuration file is located at:

/etc/Apache2/original/extra/httpd-dav.conf 

Copy this file to the website configuration path with a new filename. In this case we chose omnipresence-dav.conf but you can name it whatever makes the most sense to you.

cp /etc/Apache2/original/extra/httpd-dav.conf /Library/Server/Web/Config/apache2/sites/omnipresence-dav.conf

Note: any file that you put in /Library/Server/Web/Config/apache2/sites/ that ends in “.conf” will be included by OS X Server in the Apache configuration when the Websites service is started. If your configuration file has any errors in it the Apache service will not start.

The example configuration file outlines how a WebDAV share is defined. We will edit it to define a single share called “omnipresence” that uses OS X’s user and group accounts to control access. Remove the example configuration’s Directory directive block and replace it with your own configuration. It should look like our example omnipresence share that we’ve configured below:

# Map the URL /omnipresence to the filepath that we want to host a WebDAV share.
Alias /omnipresence "/Volumes/System/Users/Shared/OmniPresence/"

# Turn on WebDAV sharing and only allow user accounts in the posix group “staff” to access it.
<Directory "/Volumes/System/Users/Shared/OmniPresence/">
  Dav On

  Order Allow,Deny
  Allow from all

  # Use Open Directory for authentication.
  AuthType Digest
  Require group maxgeekery
</Directory>

Note: the _www user, which is the posix account that Apache runs as, must have read and write access to to the WebDAV share.

For more information about Alias, Directory, and Dav directives in Apache configuration files see the following Apache documentation sections.

Also, be sure to understand the processing of Order directives so that you don’t accidentally make your WebDAV share readable (or writable!) to the rest of the Internet:

• http://httpd.Apache.org/docs/2.2/mod/mod_authz_host.html#order

Starting the Service

When you are satisfied with your configuration, start the Websites service and test your new WebDAV share to make sure that it is accessible and that the permissions are correct!

If, by chance, you previously enabled WebDAV on file shares using OS X’s File Sharing service you will need to turn it off. This may be harder than it sounds! On some versions of OS X Server (before Mavericks) turning off WebDAV in the File Sharing service in Server.app did not, in fact, turn off WebDAV sharing. While the WebDAV share will no longer allow client access it still creates httpd processes that respond to client connections. This could cause conflicts with other WebDAV shares that you may want to setup. In our test case, we had to unload the serverd launchd job and then load it back for OS X Server to stop creating Apache processes running Apple’s WebDAV configuration. For some reason, even reboots of the system did not change the WebDAV sharing state.

To stop and then start serverd use launchctl

% sudo launchctl unload /Library/LaunchDaemons/com.apple.serverd.plist
% sudo launchctl load /Library/LaunchDaemons/com.apple.serverd.plist

Only unload and load the serverd process if, after turning WebDAV sharing off, you notice processes that are still configured as WebDAV shares and a reboot of the system does not clear them. Note that these processes only appear if a client tries to access the server system with those user’s credentials. So, after a fresh reboot the system may look clear, but double check by watching the processes on the system while a client connects.

Example processes you should not see after turning off Apple’s WebDAV share. The account maxgeekery is a user account on the system.

% ps aux |grep http                                                                                                                                                                     ~
maxgeekery               3128   0.0  0.0  2432784    628 s002  S+    6:29PM   0:00.00 grep http
maxgeekery               3117   0.0  0.0  2462048   1392   ??  S     6:29PM   0:00.00 /usr/sbin/httpd -f /Library/Server/Web/Config/apache2/httpd_webdavsharing_template.conf -D FOREGROUND -k start
maxgeekery               3116   0.0  0.0  2453856   2460   ??  Ss    6:29PM   0:00.07 /usr/sbin/httpd -f /Library/Server/Web/Config/apache2/httpd_webdavsharing_template.conf -D FOREGROUND -k start

You may also see other httpd processes running as root or _www. You can safely ignore them in this context.

_www              3089   0.0  0.0  2509032   2996   ??  S     6:29PM   0:00.01 /usr/sbin/httpd -D FOREGROUND -f /Library/Server/Web/Config/apache2/httpd_server_app.conf
root              3083   0.0  0.0  2456696   5016   ??  Ss    6:29PM   0:00.09 /usr/sbin/httpd -D FOREGROUND -f /Library/Server/Web/Config/apache2/httpd_server_app.conf
_www              3118   0.0  0.0  2492648   2880   ??  S     6:29PM   0:00.01 /usr/sbin/httpd -D FOREGROUND -f /Library/Server/Web/Config/apache2/httpd_server_app.conf