git-annex/doc/special_remotes/webdav.mdwn

This special remote type stores file contents in a WebDAV server.

## configuration

The environment variables `WEBDAV_USERNAME` and `WEBDAV_PASSWORD` are used
to supply login credentials. You need to set these only when running
`git annex initremote`, as they will be cached in a file only you 
can read inside the local git repository.

A number of parameters can be passed to `git annex initremote` to configure
the webdav remote.

* `encryption` - Required. Either "none" to disable encryption (not recommended),
  or a value that can be looked up (using gpg -k) to find a gpg encryption
  key that will be given access to the remote, or "shared" which allows
  every clone of the repository to access the encrypted data (use with caution).

  Note that additional gpg keys can be given access to a remote by
  rerunning initremote with the new key id. See [[encryption]].

* `embedcreds` - Optional. Set to "yes" embed the login credentials inside
  the git repository, which allows other clones to also access them. This is
  the default when gpg encryption is enabled; the credentials are stored
  encrypted and only those with the repository's keys can access them.

  It is not the default when using shared encryption, or no encryption.
  Think carefully about who can access your repository before using
  embedcreds without gpg encryption.

* `url` - Required. The URL to the WebDAV directory where files will be
  stored. This can be a subdirectory of a larger WebDAV repository, and will
  be created as needed. Use of a https URL is strongly
  encouraged, since HTTP basic authentication is used.

* `chunksize` - Avoid storing files larger than the specified size in
  WebDAV. For use when the WebDAV server has file size
  limitations. The default is to never chunk files.  
  The value can use specified using any commonly used units.
  Example: `chunksize=75 megabytes`  
  Note that enabling chunking on an existing remote with non-chunked
  files is not recommended.

Setup example:

	# WEBDAV_USERNAME=joey@kitenet.net WEBDAV_PASSWORD=xxxxxxx git annex initremote box.com type=webdav url=https://www.box.com/dav/git-annex chunksize=75mb encryption=joey@kitenet.net
skeltal webdav special remote Doesn't actually store anything yet, but initremote works and tests the server. 2012-11-15 00:25:00 +00:00			`This special remote type stores file contents in a WebDAV server.`

			`## configuration`

			The environment variables `WEBDAV_USERNAME` and `WEBDAV_PASSWORD` are used
Allow controlling whether login credentials for S3 and webdav are committed to the repository, by setting embedcreds=yes\|no when running initremote. 2012-11-19 21:32:58 +00:00			`to supply login credentials. You need to set these only when running`
			`git annex initremote`, as they will be cached in a file only you
			`can read inside the local git repository.`
skeltal webdav special remote Doesn't actually store anything yet, but initremote works and tests the server. 2012-11-15 00:25:00 +00:00
			A number of parameters can be passed to `git annex initremote` to configure
			`the webdav remote.`

Allow controlling whether login credentials for S3 and webdav are committed to the repository, by setting embedcreds=yes\|no when running initremote. 2012-11-19 21:32:58 +00:00			* `encryption` - Required. Either "none" to disable encryption (not recommended),
skeltal webdav special remote Doesn't actually store anything yet, but initremote works and tests the server. 2012-11-15 00:25:00 +00:00			`or a value that can be looked up (using gpg -k) to find a gpg encryption`
Allow controlling whether login credentials for S3 and webdav are committed to the repository, by setting embedcreds=yes\|no when running initremote. 2012-11-19 21:32:58 +00:00			`key that will be given access to the remote, or "shared" which allows`
			`every clone of the repository to access the encrypted data (use with caution).`

			`Note that additional gpg keys can be given access to a remote by`
			`rerunning initremote with the new key id. See [[encryption]].`

			* `embedcreds` - Optional. Set to "yes" embed the login credentials inside
			`the git repository, which allows other clones to also access them. This is`
			`the default when gpg encryption is enabled; the credentials are stored`
			`encrypted and only those with the repository's keys can access them.`

			`It is not the default when using shared encryption, or no encryption.`
			`Think carefully about who can access your repository before using`
			`embedcreds without gpg encryption.`
skeltal webdav special remote Doesn't actually store anything yet, but initremote works and tests the server. 2012-11-15 00:25:00 +00:00
			* `url` - Required. The URL to the WebDAV directory where files will be
webdav is fully working in non-enctypted mode 2012-11-16 04:09:22 +00:00			`stored. This can be a subdirectory of a larger WebDAV repository, and will`
			`be created as needed. Use of a https URL is strongly`
skeltal webdav special remote Doesn't actually store anything yet, but initremote works and tests the server. 2012-11-15 00:25:00 +00:00			`encouraged, since HTTP basic authentication is used.`

			* `chunksize` - Avoid storing files larger than the specified size in
			`WebDAV. For use when the WebDAV server has file size`
			`limitations. The default is to never chunk files.`
			`The value can use specified using any commonly used units.`
drop webdav compatability with the directory special remote etc The benefit of using a compatable directory structure does not outweigh the cost in complexity of handling the multiple locations content can be stored in directory special remotes. And this also allows doing away with the parent directories, which can't be made unwritable in DAV, so have no benefit there. This will save 2 http calls per file store. But, kept the directory hashing, just in case. 2012-11-16 04:42:33 +00:00			Example: `chunksize=75 megabytes`
skeltal webdav special remote Doesn't actually store anything yet, but initremote works and tests the server. 2012-11-15 00:25:00 +00:00			`Note that enabling chunking on an existing remote with non-chunked`
			`files is not recommended.`

			`Setup example:`

drop webdav compatability with the directory special remote etc The benefit of using a compatable directory structure does not outweigh the cost in complexity of handling the multiple locations content can be stored in directory special remotes. And this also allows doing away with the parent directories, which can't be made unwritable in DAV, so have no benefit there. This will save 2 http calls per file store. But, kept the directory hashing, just in case. 2012-11-16 04:42:33 +00:00			`# WEBDAV_USERNAME=joey@kitenet.net WEBDAV_PASSWORD=xxxxxxx git annex initremote box.com type=webdav url=https://www.box.com/dav/git-annex chunksize=75mb encryption=joey@kitenet.net`