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