wfsctl(8) BSD System Manager's Manual wfsctl(8)
NAME
wfsctl -- WebDAV File Sharing control utility
SYNOPSYS
wfsctl command [arg]
OVERVIEW
The wfsctl utility allows administrators to start, stop, and check the status of the WebDAV File Sharing service (WFS). It also allows admin-
istrators to create and delete WebDAV share points. It operates by configuring the Apache httpd server. The wfsctl command requires root
privileges.
COMMANDS
wfsctl provides the following commands:
start Enable the WFS configuration, and either start or restart the Apache web server to pick it up. If necessary, this
action will create an SSL Identity matching the machine's host name as determined by the hostname(1) command, and
place it in the System keychain. It will also update, if necessary, environment variable definitions for use by param-
eterized httpd config files. (Note that starting the Apache web server is the equivalent of "apachectl start" which
loads a launch job for the httpd process.)
stop Disable the WFS configuration, and restart Apache if it's already running.
status Display the status of WFS, either "enabled" or "disabled", whether or not Apache is running.
shares Display existing WebDAV share points.
share path Create a WebDAV share point for the specified file system path.
unshare path | name Disable WebDAV for the share point at the specified file system path or share point name, and delete the share point
if no other file sharing service (AFP or SMB) was enabled on that share point.
diagnose Display detailed status of Apache and WebDAV-related processes.
DETAILS
WebDAV File Sharing operates by:
1. Recognizing WebDAV clients when they send OPTIONS or PROPFIND directives
2. Requiring such clients to provide OD credentials
3. Assigning those authenticated users an HTTP cookie to recognize them as WebDAV clients
4. Launching an instance of the Apache httpd process on behalf of that user, configured as a WebDAV server
5. Reverse-proxying HTTP traffic to that user-specific instance of httpd, so that the WebDAV client (typically an iWork app on iOS) can
access the home directory and share points on the server machine with privileges of the authenticated user
6. Recognizing share points that are marked as WebDAV share points.
Depending on how Apache is configured, this can coexist with other Apache web service functions.
NOTES
o WebDAV File Sharing requires SSL, and uses Basic authentication, with credentials that would otherwise be sent in the clear over the net-
work. Also note that it uses Apache modules mod_ssl for SSL, and mod_authnz_od_apple for Basic authentication with OpenDirectory creden-
tials.
o The name "webdav" is reserved (it triggers special handling of URLs), so share point paths named "/webdav" or containing "webdav" as a
subpath are not allowed. And folders named "webdav" within share points won't be usable. There are no restrictions on case variants such
as "WebDAV", or other variants such as "webdav.d".
o DropBox folders cannot be accessed via WebDAV File Sharing.
CONFIGURABLE SETTINGS
Certain settings are kept in /etc/wfs/wfs.plist and are configurable by the administrator, including:
ServerName The host name the Apache web server should use, and also the Common Name of the identity certificate. If this is not
configured, or set to an empty string, the hostname(1) of the machine is used.
ServerAddr The IP address the Apache web server should use to listen for HTTPS requests. Default is "*", which means all
addresses.
ServerPort The TCP port the Apache web server should use to listen for HTTPS requests. Default is the standard HTTPS port, 443.
AccessGroup The Open Directory group allowed access to the WebDAV File Sharing service. The default is "everyone", which gives
access to any authenticated user. Administrators can change this setting to restrict access further. Authenticated
users will have, at most, the privileges they are normally allowed by file system permissions. There is no provision
for guest access, so unauthenticated users have no access.
SynthesizeSharePointForUserHomeDir
Whether to allow remote WebDAV clients to see their home directory as a share point. Default is True.
The Apache config file for WebDAV File Sharing is parameterized, and the httpd server is managed by the httpd-wrapper utility, which passes
parameters to httpd. This is normally transparent, but note that to check the Apache config file syntax, do not use "apachectl configtest" or
"httpd -t". Instead, use "httpd-wrapper -t".
RETURN VALUES
wfsctl returns a status code of 0 for success. In the event of failure it returns a non-zero status, and may also dump additional diagnostic
information.
WEBDAV CLIENTS
o WebDAV clients must be properly configured to access WebDAV Shares on a remote host.
o WebDAV clients include certain iOS apps, like Numbers, Keynote, and Pages, and the macOS Finder's Connect-to-Server. (Note that the iOS
Files app does not find WebDAV File Sharing locations.)
o WebDAV clients must usually be configured with a full URL of the host, with a scheme of https (since an http->https redirect is not gen-
erally compatible with WebDAV operations). It's not necessary to specify /webdav in the path. So for example, the "Server Name" might be
specified as:
https://hostname.example.com
o The configurable virtual host behavior provided by macOS Server is not available, so WebDAV clients may not be able to use alternate host
names in their URLs.
FILES
/etc/wfs/httpd_webdavsharing.conf
The parameterized Apache config file for the main instance of httpd
/etc/wfs/httpd_webdavsharing_template.conf
The parameterized Apache config file for the user-specific instances of httpd
/etc/wfs/httpd_webdavsharing_sharepoints.conf
The Apache config file providing directives specific to each share point; dynamically generated when share points are modified by
wfsctl
/etc/wfs/wfs.plist
The file where admin-configurable settings for WFS are stored.
/Library/Server/Web/Config/apache2/WebConfigProperties.plist
If macOS Server is installed and promoted, WebDAVSharing settings in this file take precedence over those in /etc/wfs/wfs.plist.
/etc/apache2/env.plist
The file where environment variable definitions are managed automatically; these variables are passed to httpd for use in parameter-
ized config files.
/Library/Logs/WebDAVFileSharing.log
The main WebDAV File Sharing log file
/etc/apache2/other/httpd_webdavsharing.conf
A symlink seen by Apache when WebDAV File Sharing is enabled. When WebDAV File Sharing is disabled, this symlink is moved aside.
/var/run/webdavsharing/<username>/
A directory created on the behalf of each authenticated user to store user-specific WebDAV File Sharing logs.
/usr/share/sandbox/wfs.sb
The parameterized sandbox profile for user-specific httpd instances.
/etc/wfs/wfs.sb
The dynamically generated portion of the sandbox profile
SERVER APP
When macOS Server is installed and promoted, WebDAV File Sharing is reconfigured to support the WebDAV behaviors presented by Server:
1. macOS Server provides HTTP-based services (for Profile Manager) on standard HTTP/S TCP ports 80 and 443. So to avoid port conflict, the
desktop Apache configuration (including the configuration for WebDAV File Sharing) is switched to port 81, on localhost only, and WFS
traffic is reverse proxied to localhost:81.
2. macOS Server manages its own SSL certificates, and provides the SSL endpoint. So the desktop Apache configuration for WebDAV File Shar-
ing is switched to non-SSL.
When macOS Server is installed and promoted, it is still possible to use wfsctl to manage WebDAV share points, e. g.:
sudo wfsctl share /Volumes/Data/Share1
3. Any share points created in the UI on versions of macOS Server that predate High Sierra remain across updates, and those that were
marked as WebDAV share points should continue to be available after the update to High Sierra, whether or not macOS Server is installed.
When macOS Server is removed or demoted, the port changes and SSL changes made at Server promotion time are reversed.
SEE ALSO
httpd(8) httpd-wrapper(8)
macOS Sept. 20, 2017 macOS