Mercurial > hg > dav / changeset

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/Makefile	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,66 @@
+#
+# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
+#
+# Copyright 2017 Olaf Wintermann. All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#   1. Redistributions of source code must retain the above copyright
+#      notice, this list of conditions and the following disclaimer.
+#
+#   2. Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+#
+
+PANDOC=pandoc
+PFLAGS = -c davdoc.css -B header.html -A footer.html
+
+SRC = getting-started.md
+SRC += commands.md
+SRC += list.md
+SRC += get.md
+SRC += put.md
+SRC += mkdir.md
+SRC += remove.md
+SRC += copy.md
+SRC += move.md
+SRC += get-property.md
+SRC += set-property.md
+SRC += lock.md
+SRC += unlock.md
+SRC += info.md
+SRC += date.md
+SRC += configuration.md
+SRC += encryption.md
+
+HTML = $(SRC:%.md=build/%.html)
+
+FILES = build/davdoc.css
+
+all: build $(HTML) $(FILES)
+
+build:
+	mkdir -p build
+
+build/%.html: %.md
+	$(PANDOC) $(PFLAGS) $< -o $@
+
+build/davdoc.css:
+	cp davdoc.css build
+
+clean:
+	rm -Rf build

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/commands.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,44 @@
+Commands
+========
+
+Overview
+--------
+
+List resources:
+
+	dav list <url>
+
+Download resource:
+
+	dav get <url>
+
+Download all resources from a collection:
+
+	dav get -R <url>
+
+Upload a file:
+
+	dav put <url> <file>
+
+Upload all files from a directory:
+
+	dav put -R <url> <dir>
+
+Duplicate a resource or a collection on a server:
+
+	dav copy <src-url> <dst-url>
+
+There is also a move operation similar to copy:
+
+	dav move <src-url> <dst-url>
+
+These are the most common commands. There are also more commands for webdav locking and manipulating webdav properties.
+
+Common options
+--------------
+
+**`-N`** disable any authentication prompt. If authentication is required, dav will abort.
+
+**`-i`** disable TLS certificate verification
+
+**`-v`** enable verbose output. Internally `CURLOPT_VERBOSE` is set to 1 and verbose output is printed on stderr.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/date.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,23 @@
+dav date
+========
+
+**`date [url]`**
+
+The purpose of this command is to get the current date from a server and print it on stdout (http date format). This in useful in combination with the `-U` option for the `list` and `get` command.
+
+The *url* can be any http url. If no *url* is specified, the local time is used.
+
+### Example: incremental dav get
+
+It is possible to download only resources, which are modified since a specified date. The *date* command allows you to easily store the date of the last *get*.
+
+	$ dav get -R myserv/col/
+	...
+	$ dav date myserv > last_get
+	
+After some resources are changed on the server, you can download only the modified files.
+
+	$ dav get -R -U `cat last_get` myserv/col/
+
+
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/davdoc.css	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,79 @@
+.header, h1, h2, h3, .sidebar {
+    font-family: sans-serif;
+}
+
+div.header {
+    padding-top: 0.3em;
+    padding-bottom: 0.5em;
+    margin-bottom: 2em;
+    border: none;
+    border-bottom: 1px solid;
+    border-bottom-color: #2E2E2E;
+}
+
+div.header span {
+    font-size: 2em;
+    font-weight: bold;
+    margin-left: 1em;
+}
+
+div.header img {
+    float: right;
+}
+
+div.sidebar {
+    float: left;
+    width: 15em;
+}
+
+div.nav {
+    color: black;
+    background-color: #E9EBEC;
+    margin-bottom: 1em;
+    padding-bottom: 0.1em;
+}
+
+div.nav h3 {
+    color: white;
+    background-color: #5B6F7A;
+    font-size: 1.2em;
+    padding-top: 0.2em;
+    padding-bottom: 0.2em;
+    padding-left: 0.5em;
+    margin-top: 0;
+}
+
+div.nav ul {
+    margin-top: 0;
+    padding-top: 0;
+    font-size: 0.95em;
+}
+
+div.content {
+    margin-left: 16em;
+    padding: 0;
+    font-family: serif;
+    font-size: 1em;
+    min-width: 16em;
+}
+
+div.content h1 {
+    color: white;
+    background-color: #5B6F7A;
+    font-size: 1.2em;
+    padding-top: 0.2em;
+    padding-bottom: 0.2em;
+    padding-left: 0.5em;
+    padding-right: 0;
+    margin-top: 0;
+}
+
+div.content h2 {
+    font-size: 1.2em;
+}
+
+div.content h3 {
+    font-size: 1.05em;
+}
+
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/footer.html	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,3 @@
+</div>
+<!-- end content -->
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/get-property.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,27 @@
+dav get-property
+================
+
+**`get-property [-pc] [-n <uri>] <url> <property>`**
+
+Gets a specified resource property. Every WebDAV property has a name and an XMl namespace. A namespace can be specified with the `-n` option or with a prefixed name. A prefix and property name are separated by an **:**
+
+Example: `D:creationdate`
+
+`D` is the prefix, `creationdate` is the name.
+
+There are only two available prefixes:
+
+1. `D` for the `DAV:` namespace
+2. `idav` for `http://davutils.org/`
+
+To use an other namespace, use the `-n` option.
+
+If the property name has no prefix, and no namespace is specified, the default namespace `DAV:` is used.
+
+**`-p`** disable file name and path decryption if enabled
+
+**`-c`** enable file name and path decryption
+
+**`-n <uri>`** specify property namespace
+
+**Note:** Properties are never encrypted.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/get.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,23 @@
+dav get
+=======
+
+**`get [-pcR] [-o <file>] [-u <date>] <url>`**
+
+Downloads a resource. It can also download collections and its child resources.
+When downloading a single resource, the default local file name is the resource
+name. When downloading collections, it does NOT create a local directory with
+the collection's name and places it children in there, but it downloads the
+children directly to the current working directory.
+
+**`-p`** disable file name and content decryption. You get exactly what is stored
+  on the server.
+  
+**`-c`** enable file name and content decryption
+
+**`-R`** download a collection
+
+**`-o <file>`** specify the local output file. A **-** indicates stdout
+
+**`-u <date>`** downloads only files which are modified since the specified date. Uses the http date format
+
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/getting-started.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,44 @@
+Getting started
+===============
+
+### Test
+
+After successful installation you can test dav with your WebDAV server.
+
+	dav list http://example.com/webdav/
+
+This lists all child resources of the specified collection. If you are unfamiliar to WebDAV terminology this means basically listing all files in a directory, similar to the ls unix tool. Infact you can also write dav ls instead of dav list and there is also a -l option like ls has one. 
+
+### Create a repository
+
+All dav commands are expecting a url argument, but it may be a bit cumbersome to type a full url every time. But you can configure a repository in the dav configuration file ($HOME/.dav/config.xml) with the servers url, optional authentication information and other options. After that you can access a webdav server just with the repository name and an optional path.
+
+So when you have created a repository with the name myserv and the url http://example.com/webdav/, you can just type
+
+	dav list myserv
+
+You can add a path to the repository name to access an other url
+
+	dav list myserv/mycollection/
+
+This lists the content of http://example.com/webdav/mycollection/
+
+The easiest way to create a repository is with the add-repository command. This is a simple configuration assistant.
+
+	$ dav add-repository
+	Each repository must have an unique name.
+	name: myserv
+
+	Specify the repository base url.
+	url: http://example.com/webdav/
+
+	User for HTTP authentication.
+	user (optional): myuser
+	password (optional): 
+
+
+	Added repository: myserv (http://example.com/webdav/)
+
+You can also configure the config.xml yourself, check out this example page and the config.xml spec.
+
+More informations about urls and path in dav here.

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/header.html	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,38 @@
+<div class="header">
+	<span>davutils documentation</span>
+</div>
+<div class="sidebar">
+	<div class="nav">
+		<h3>dav</h3>
+			<ul>
+				<li><a href="getting-started.html">Getting started</a></li>
+				<li><a href="commands.html">Commands</a></li>
+					<ul>
+						<li><a href="list.html">list</a></li>
+						<li><a href="get.html">get</a></li>
+						<li><a href="put.html">put</a></li>
+						<li><a href="mkdir.html">mkdir</a></li>
+						<li><a href="remove.html">remove</a></li>
+						<li><a href="copy.html">copy</a></li>
+						<li><a href="move.html">move</a></li>
+						<li><a href="get-property.html">get-property</a></li>
+						<li><a href="set-property.html">set-property</a></li>
+						<li><a href="lock.html">lock</a></li>
+						<li><a href="unlock.html">unlock</a></li>
+						<li><a href="info.html">info</a></li>
+						<li><a href="date.html">date</a></li>
+					</ul>
+				<li><a href="configuration.html">Configuration</a></li>
+				<li><a href="encryption.html">Encryption</a></li>
+			</ul>
+	</div>
+	<div class="nav">
+		<h3>dav-sync</h3>
+			<ul>
+				<li><a href=".">.</a></li>
+			</ul>
+	</div>
+</div>
+
+<!-- begin content -->
+<div class="content">

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/info.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,49 @@
+dav info
+========
+
+**`info [-pc] <url>`**
+
+Prints some information and lists all properties for the resource specified by url.
+
+### Example 1: info of a collection
+
+In this example *myserv* is a configured repository with the base url *https://example.com/webdav/*. Because *col* is not encrypted, the *url* is just the *path* appended to base url.
+
+	$ dav info myserv/col/
+	name: col
+	path: /col
+	url:  https://example.com/webdav/col
+	type: collection
+	size: 28
+
+	namespace: DAV:
+	  creationdate: 2017-06-14T09:32:43Z
+	  getetag: "1000-551e83bebc19c"
+	  getlastmodified: Wed, 14 Jun 2017 09:32:43 GMT
+	  supportedlock:
+
+### Example 2: encrypted resource
+
+With encrypted resources, the *path* and *url* are different. The real resource name is random, but the name used by *dav* is stored in the *crypto-name* property. 
+
+	$ dav info -c myserv/crres
+	name: crres
+	path: /crres
+	url:  https://example.com/webdav/wsIwbLxuJQTGtgiMAD1KGeaY
+	type: resource
+	size: 48 bytes
+
+	namespace: DAV:
+	  creationdate: 2017-07-09T16:18:09Z
+	  getcontentlength: 48
+	  getetag: "30-553e4cfecd170"
+	  getlastmodified: Sun, 09 Jul 2017 16:18:09 GMT
+	  supportedlock: 
+
+	namespace: http://apache.org/dav/props/
+	  executable: F
+
+	namespace: http://davutils.org/
+	  crypto-hash: fm4zstp/FevTs1aoUXc3+mqTmAf2Go+zQ34rSp8/ixDlGLQJXR74Je+WMl1zxZKbS/+5VwDhyZ9pT3gInsq2SA==
+	  crypto-key: mykey
+	  crypto-name: ZU+lZtFi3dprBz44714plYwfRnhyI/apYq46Sk/B6QU=

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/list.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,49 @@
+dav list
+========
+
+**`dav list [-altepcR] [-u <date>] <url>`**
+
+Lists child resources of the specified collection. Without any options it
+shows only the direct children and hides files beginning with a dot.
+
+Options
+-------
+
+**`-a`** don't hide files whose names begins with a dot `.`
+
+**`-l`** shows additional information for resources
+
+Example:
+
+	--     4.2 KiB  Oct 11  2015  somefile
+
+The first column contains to fields for flags.
+
+1. Field: `d-` indicates a collection
+2. Field: `-c` indicates an encrypted resource
+
+Also encrypted collections are possible, but only the collection name is encrypted, the content may be unencrypted.
+
+The second column in the `list -l` output is the resource size. The number has always a suffix (bytes, KiB, MiB, GiB, TiB). To get the exact content-length in bytes you can use the [dav info][1] command.
+
+[1]: ./info.html
+
+The third column is the date of the last modification. The `strftime` format is `%b %d %H:%M` if the year is the same. Otherwise the format is `%b %d  %Y`.
+
+The last column is the resource name. If the `-R` option is specified, the resource path is shown.
+
+**`-t`** this options only work in combination with `-l` and it adds the resource content type to the output (after the flags)
+
+**`-e`** similar to `-l`, but with 6 flag fields. Currently only the first 4 fields are used. The last two are reserved for future use.
+
+3. Field: **l** indicates a locked resource
+4. Field: **x** indicates a executable resource (executable property with http://apache.org/dav/props/ namespace)
+
+**`-p`** disables file name and path decryption if enabled
+
+**`-c`** enables file name and path decryption
+
+**`-R`** recursively shows all resources in the collection and all child collections
+
+**`-u <date>`** shows only resources with a lastmodified date after the specified
+  date. Uses the http date format

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/lock.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,21 @@
+dav lock
+========
+
+**`lock [-pc] <url>`**
+
+Creates a lock on the resource specified by the url. The lock is an exclusive write lock with infinity depth.
+
+If the resource is successfully locked, a lock token for this resource is printed on stdout. This lock token should be saved somewhere to unlock the resource eventually.
+
+**`-p`** disable file name and path decryption if enabled
+
+**`-c`** enable file name and path decryption
+
+### Example 1: lock resource and use the lock token
+
+	$ dav lock myserv/resource
+	opaquelocktoken:0454905e-f2ff-45c4-a3d7-5c4e4db5ce37
+	$ dav put -L opaquelocktoken:0454905e-f2ff-45c4-a3d7-5c4e4db5ce37 myserv/resource newfile
+	$ dav unlock -L opaquelocktoken:0454905e-f2ff-45c4-a3d7-5c4e4db5ce37 myserv/resource
+
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/mkdir.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,15 @@
+dav mkdir
+=========
+
+**`mkdir [-pc] [-k <key>] [-L <lock>] <url>`**
+
+Creates a collection. All intermediate collections are created.
+
+**`-p`** disable file name encryption and decryption
+
+**`-c`** enables file file name and content encryption
+
+**`-k <key>`** use the specified key for encryption. The key must be configured in
+  the config.xml file
+
+**`-L <lock>`** use a lock token

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/put.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,27 @@
+dav put
+=======
+
+**`put [-pcR] [-k <key>] [-L <lock>] <url> <file>`**
+
+Uploads a file or a directory. When uploading a file and the url points to
+an existing collection, a resource inside this collection with the file's name is created. When the url points to a non-existing resource, the resource is
+created.
+
+When uploading a directory, you need to specify the -R option. It uploads
+all files in the directory to the specified url, but it does not create a
+collection for the directory itself.
+
+**`-p`** disable file name encryption and decryption
+
+**`-c`** enable file name and content encryption
+
+**`-R`** upload directory
+
+**`-k <key>`** use the specified key for encryption. The key must be configured in
+  the config.xml file
+
+**`-L <lock>`** use a lock token. See [dav lock][1]
+
+[1]: ./lock.html
+
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/remove.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,13 @@
+dav remove
+==========
+
+**`remove [-pc] [-L <lock>] <url>`**
+
+Removes a resource. When removing a collection, all unterneath resources are
+removed.
+
+**`-p`** disable file name and path decryption if enabled
+
+**`-c`** enable file name and path decryption
+
+**`-L`** <lock> use a lock token

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/set-property.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,24 @@
+dav set-property
+================
+
+**`set-property [-pc] [-L <lock>] [-n <uri>] <url> <property> [value]`**
+
+Sets a resource property to a specified value.
+
+property is a property name with or without prefix (see [get-property][1] for details).
+
+[1]: ./get-property.html
+
+If no value is specified, the content for the property is read from stdin.
+
+**`-p`** disable file name and path decryption if enabled
+
+**`-c`** enable file name and path decryption
+
+**`-L <lock>`** use a lock token. See [dav lock][1]
+
+**`-n <uri>`** specify property namespace
+
+**Note:** Properties are never encrypted.
+
+

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/src/unlock.md	Sun Jul 09 20:15:14 2017 +0200
@@ -0,0 +1,25 @@
+dav unlock
+==========
+
+**`unlock [-pc] [-L <lock>] <url>`**
+
+Unlocks the specified url with a lock token. If no lock token is specified with the `-L` option, it read from stdin.
+
+**`-p`** disable file name and path decryption if enabled
+
+**`-c`** enable file name and path decryption
+
+**`-L <lock>`** use a lock token
+
+### Example 1: unlock with lock token from stdin
+
+	$ dav lock myserv/resource > locktoken
+	$ dav unlock myserv/resource < locktoken
+
+### Example 2: unlock with lock token from command line argument
+
+	$ dav lock myserv/resource
+	opaquelocktoken:0454905e-f2ff-45c4-a3d7-5c4e4db5ce37
+	$ dav unlock -L opaquelocktoken:0454905e-f2ff-45c4-a3d7-5c4e4db5ce37 myserv/resource
+
+