====== Using WebDAV ======

WebDAV is a protocol that allows for convenient mounting of a remote server on your desktop for easy file access. Once setup, using it is as simple as any other drag and drop navigation on your desktop. Native WebDAV clients differs in various operating systems. We know positively that WebDAV works in MacOS X and Windows XP, and there are also 3rd party utilities to help you mount your WebDAV storage.

===== Enabling WebDAV Access =====

To enable WebDAV access to a particular domain, make sure that you enable the DAV feature for the virtual server in Virtualmin:

  - Sign in to Virtualmin (see [[logins]]).
  - Select the virtual server from the drop-down in the left-hand navigation (your main virtual server should be already selected when you first login to Virtualmin).
  - Click **Edit Virtual Server**.
  - Click **Enabled features** to expand the features section.
  - Check **Enable DAV logins?**
  - Click **Save Virtual Server**.

The directives necessary to handle WebDAV requests will be added to the domain's virtualhost.

===== Adding a WebDAV user =====

Next we must create a user with WebDAV login access. The WebDAV login for the user will be a longform username (e.g. //joe@mysite.com// instead of //joe-mysite//).

  - Sign in to Virtualmin (see [[Logins]]).
  - Select a virtual server from the drop-down in the left-hand navigation (your main virtual server should be already selected when you first login to Virtualmin). The virtual server you select here will be the one that you'll be adding a user to.
  - In the left-hand navigation, click **Edit Mail and FTP Users** (or **Edit FTP Users** if Mail service is not enabled for this virtual server). 
  - Click **Add a user to this server.**
  - Enter your desired //Username//. The entire value (e.g. //joe@mysite.com//) will be used to log in via WebDAV.
  - For //Real name//, enter a name for your user (e.g. first name and surname).
  - The //Password// field will already be populated with password for your user. We recommend using the password that Virtualmin has created as they are fairly secure and you should also make a note of this password in case you need it (you can retrieve the password on the same page later on though).
  - Click **Other user permissions**, and set **DAV login enabled** to //Yes//.
  - Click **Create** to create your new user.

<note tip>If you have an existing user that you would like to provide with WebDAV access, you can edit the user on the same screen where you can create a user, just by clicking its name in the user list. With the user's page loaded, click **Other user permissions**, set **DAV login enabled** to //Yes//, and click **Save**.</note>

===== Connecting via WebDAV =====
To connect via WebDAV, be sure you are using:

  * The appropriate WebDAV URL (e.g. <nowiki>http://mysite.com/dav/</nowiki>).
  * The longform username for WebDAV (e.g. //joe@mysite.com// instead of //joe-mysite//).
  * The password for the user set in Virtualmin.

<note tip>If you only wish to publish to a single directory within your document root (see ** WebDAV and Write Access** below), you should add that directory name to your WebDAV URL (e.g. <nowiki>http://mysite.com/dav/dirname/</nowiki>).</note>

===== WebDAV and Write Access =====

You cannot write to your domain directories over WebDAV by default. If you need to, we can modify your domain's document root to allow writing over WebDAV, you just need to open a [[https://help.joyent.com/index.php?pg=request|support ticket]], stating the particular domain. Please read this document to the end until you do so though.

Why the hassle? The ownership models are different. The Apache WebDAV writes as the user which the web server runs as ('www'), while all other access methods run and write as your user (also scripts executed by the web server, typically PHP, Perl and Rails scripts will run as your user). All directories and files are owned by you by default, which means that WebDAV cannot write there.

An obvious solution would be to raise the permissions to allow WebDAV write there, but that would involve giving anybody write access (i.e. 'world', as in 777 chmod pattern for directories). The only clean solution is to chown (change ownership of) the directories and files to the 'www' user, which is what we'd do if you asked for WebDAV write access as per the 1st paragraph of this document.

The consequences are apparent: because the directories/files will be owned by 'www', you won't be allowed to create/modify/delete files there with SSH-based methods (e.g. SFTP). Allowing group write access won't work longterm, as WebDAV always creates new files with a 755 pattern (no group write access). Using both will likely leave you with a mix of files owned by 'www' and you, where files created by WebDAV cannot be modified by SFTP and vice versa.

Furthermore, if you run a web application on your domain which writes to disk on its own (e.g. a file upload feature as part of a PHP application), the scripts may refuse to write to a www-owned directories. In such case, you'll need to either keep the respective directories group-writable, or switch your site to mod_php (instead of FastCGI), so that the scripts are executed as 'www' too.

The bottom line is that changing the domain to allow WebDAV write access will break SFTP write access. We prefer the latter, hence keep things set up for SFTP by default. If you want to only use WebDAV for some reason though, it makes perfect sense to have the domain files turned over to the 'www' user.

Note that if you only need a file repository on your domain, we can chown a single subdirectory inside your domain only, and you can use it for WebDAV, while keeping the default ownership model (and SFTP access elsewhere). Same case if you want an 'ical' kind of directory to publish your iCal calendars to.