docs/html/configuration.html

changeset 294
dd5c0ebdf54f
parent 285
02d3e4b1245f
child 306
4a1596b45ff2
equal deleted inserted replaced
293:8f90dcfd0439 294:dd5c0ebdf54f
69 </div> 69 </div>
70 <p>The main configuration file for <em>dav</em> is <code>$HOME/.dav/config.xml</code> and is used for configuring repositories, proxies and encryption keys. This configuration is also used by <em>dav-sync</em>. The file is created automaticaly if it doesn't exist.</p> 70 <p>The main configuration file for <em>dav</em> is <code>$HOME/.dav/config.xml</code> and is used for configuring repositories, proxies and encryption keys. This configuration is also used by <em>dav-sync</em>. The file is created automaticaly if it doesn't exist.</p>
71 <p>The <em>config.xml</em> file is an XML file with <code>&lt;configuration&gt;</code> as root element. The <code>&lt;configuration&gt;</code> element can have the following child elements: <code>&lt;repository&gt;</code>, <code>&lt;http-proxy&gt;</code>, <code>&lt;https-proxy&gt;</code>, <code>&lt;key&gt;</code></p> 71 <p>The <em>config.xml</em> file is an XML file with <code>&lt;configuration&gt;</code> as root element. The <code>&lt;configuration&gt;</code> element can have the following child elements: <code>&lt;repository&gt;</code>, <code>&lt;http-proxy&gt;</code>, <code>&lt;https-proxy&gt;</code>, <code>&lt;key&gt;</code></p>
72 <h2 id="repository">repository</h2> 72 <h2 id="repository">repository</h2>
73 <p>This element is used to configure a repository. A repository must have a unique name to identify the repository and a url pointing to the root collection for this repository.</p> 73 <p>This element is used to configure a repository. A repository must have a unique name to identify the repository and a url pointing to the root collection for this repository.</p>
74 <p>Required child elements: <code>&lt;name&gt;</code>, <code>&lt;url&gt;</code><br />Optional elements: <code>&lt;user&gt;</code>, <code>&lt;password&gt;</code>, <code>&lt;default-key&gt;</code>, <code>&lt;full-encryption&gt;</code>, <code>&lt;content-encryption&gt;</code>, <code>&lt;decrypt-content&gt;</code>, <code>&lt;decrypt-name&gt;</code>, <code>&lt;cert&gt;</code>, <code>&lt;verification&gt;</code>, <code>&lt;ssl-version&gt;</code>, <code>&lt;authmethods&gt;</code></p> 74 <p>Required child elements: <code>&lt;name&gt;</code>, <code>&lt;url&gt;</code><br />
75 Optional elements: <code>&lt;user&gt;</code>, <code>&lt;password&gt;</code>, <code>&lt;default-key&gt;</code>, <code>&lt;full-encryption&gt;</code>, <code>&lt;content-encryption&gt;</code>, <code>&lt;decrypt-content&gt;</code>, <code>&lt;decrypt-name&gt;</code>, <code>&lt;cert&gt;</code>, <code>&lt;verification&gt;</code>, <code>&lt;ssl-version&gt;</code>, <code>&lt;authmethods&gt;</code></p>
75 <h3 id="name">name</h3> 76 <h3 id="name">name</h3>
76 <p>Unique repository identifer.</p> 77 <p>Unique repository identifer.</p>
77 <p>Type: string<br />Example: <code>&lt;name&gt;myrepo&lt;/name&gt;</code></p> 78 <p>Type: string<br />
79 Example: <code>&lt;name&gt;myrepo&lt;/name&gt;</code></p>
78 <h3 id="url">url</h3> 80 <h3 id="url">url</h3>
79 <p>The url must point to a valid WebDAV compilant collection.</p> 81 <p>The url must point to a valid WebDAV compilant collection.</p>
80 <p>Type: url<br />Example: <code>&lt;url&gt;https://example.com/webdav/repo1/&lt;/url&gt;</code></p> 82 <p>Type: url<br />
83 Example: <code>&lt;url&gt;https://example.com/webdav/repo1/&lt;/url&gt;</code></p>
81 <h3 id="user">user</h3> 84 <h3 id="user">user</h3>
82 <p>User used for authentication</p> 85 <p>User used for authentication</p>
83 <p>Type: string<br />Example: <code>&lt;user&gt;alice&lt;/user&gt;</code></p> 86 <p>Type: string<br />
87 Example: <code>&lt;user&gt;alice&lt;/user&gt;</code></p>
84 <h3 id="password">password</h3> 88 <h3 id="password">password</h3>
85 <p>A base64 encoded password used for authentication.</p> 89 <p>A base64 encoded password used for authentication.</p>
86 <p>Type: base64 string<br />Example: <code>&lt;password&gt;MTIzNDU2Nzg=&lt;/password&gt;</code></p> 90 <p>Type: base64 string<br />
91 Example: <code>&lt;password&gt;MTIzNDU2Nzg=&lt;/password&gt;</code></p>
87 <h3 id="default-key">default-key</h3> 92 <h3 id="default-key">default-key</h3>
88 <p>Identifer of the key used by default for encryption. There must be a configured key with this name.</p> 93 <p>Identifer of the key used by default for encryption. There must be a configured key with this name.</p>
89 <p>Type: string<br />Example: <code>&lt;key&gt;mykey&lt;/key&gt;</code></p> 94 <p>Type: string<br />
95 Example: <code>&lt;key&gt;mykey&lt;/key&gt;</code></p>
90 <h3 id="full-encryption">full-encryption</h3> 96 <h3 id="full-encryption">full-encryption</h3>
91 <p>If this element has the value of true, content and resource name encryption/decryption is enabled. Because encryption and decryption is disabled by default, <code>false</code> has no effect for this element.</p> 97 <p>If this element has the value of true, content and resource name encryption/decryption is enabled. Resources are only encrypted if the repository has a default-key or a key is specified via command line option. Because encryption and decryption is disabled by default, <code>false</code> has no effect for this element.</p>
92 <p>Type: boolean<br />Default: false<br />Example: `<full-encryption>true</full-encryption></p> 98 <p>Type: boolean<br />
99 Default: false<br />
100 Example: `<full-encryption>true</full-encryption></p>
93 <h3 id="content-encryption">content-encryption</h3> 101 <h3 id="content-encryption">content-encryption</h3>
94 <p>This element enables only content encryption and decryption. A value of <code>false</code> disables content encryption, but it does not disables content decryption, if this is enabled with <code>&lt;decrypt-content&gt;</code>.</p> 102 <p>This element enables only content encryption and decryption. A value of <code>false</code> disables content encryption, but it does not disables content decryption, if this is enabled with <code>&lt;decrypt-content&gt;</code>.</p>
95 <p>Type: boolean<br />Default: false<br />Example: <code>&lt;content-encryption&gt;true&lt;/content-encryption&gt;</code></p> 103 <p>Type: boolean<br />
104 Default: false<br />
105 Example: <code>&lt;content-encryption&gt;true&lt;/content-encryption&gt;</code></p>
96 <h3 id="decrypt-content">decrypt-content</h3> 106 <h3 id="decrypt-content">decrypt-content</h3>
97 <p>Controls only the decryption of content. If <code>true</code> content is decrypted.</p> 107 <p>Controls only the decryption of content. If <code>true</code> content is decrypted.</p>
98 <p>Type: boolean<br />Default false<br />Example: <code>&lt;decrypt-content&gt;true&lt;/decrypt-content&gt;</code></p> 108 <p>Type: boolean<br />
109 Default false<br />
110 Example: <code>&lt;decrypt-content&gt;true&lt;/decrypt-content&gt;</code></p>
99 <h3 id="decrypt-name">decrypt-name</h3> 111 <h3 id="decrypt-name">decrypt-name</h3>
100 <p>Controls only the decryption of resource names. If <code>true</code> resource names are decrypted. This effects path to url resolution.</p> 112 <p>Controls only the decryption of resource names. If <code>true</code> resource names are decrypted. This effects path to url resolution.</p>
101 <p>Type: boolean<br />Default: false<br />Example: <code>&lt;decrypt-name&gt;true&lt;/decrypt-name&gt;</code></p> 113 <p>Type: boolean<br />
114 Default: false<br />
115 Example: <code>&lt;decrypt-name&gt;true&lt;/decrypt-name&gt;</code></p>
102 <h3 id="cert">cert</h3> 116 <h3 id="cert">cert</h3>
103 <p>Path to a file containing certificates to verify the TLS connection to the server.</p> 117 <p>Path to a file containing certificates to verify the TLS connection to the server.</p>
104 <p>Type: string<br />Example: <code>&lt;cert&gt;/etc/certs/cabundle.pem&lt;/cert&gt;</code></p> 118 <p>Type: string<br />
119 Example: <code>&lt;cert&gt;/etc/certs/cabundle.pem&lt;/cert&gt;</code></p>
105 <p>Note: This element does the same as curl's <code>--cacert</code> option.</p> 120 <p>Note: This element does the same as curl's <code>--cacert</code> option.</p>
106 <h3 id="verification">verification</h3> 121 <h3 id="verification">verification</h3>
107 <p>This element can disable TLS certificate verification.</p> 122 <p>This element can disable TLS certificate verification.</p>
108 <p>Type: boolean<br />Default: true<br />Example: <code>&lt;verification&gt;false&lt;/verification&gt;</code></p> 123 <p>Type: boolean<br />
124 Default: true<br />
125 Example: <code>&lt;verification&gt;false&lt;/verification&gt;</code></p>
109 <h3 id="ssl-version">ssl-version</h3> 126 <h3 id="ssl-version">ssl-version</h3>
110 <p>Specifies the SSL version to attempt to use. The value must be one of this strings: TLSv1, TLSv1.0, TLSv1.1, TLSv1.2, SSLv2, SSLv3</p> 127 <p>Specifies the SSL version to attempt to use. The value must be one of this strings: TLSv1, TLSv1.0, TLSv1.1, TLSv1.2, SSLv2, SSLv3</p>
111 <p>Type: ssl version enum<br />Example: <code>&lt;ssl-version&gt;TLSv1.2&lt;/ssl-version&gt;</code></p> 128 <p>Type: ssl version enum<br />
129 Example: <code>&lt;ssl-version&gt;TLSv1.2&lt;/ssl-version&gt;</code></p>
112 <h3 id="authmethods">authmethods</h3> 130 <h3 id="authmethods">authmethods</h3>
113 <p>Controls which http authentication methods are used. Multiple methods can be used. The value must be one or more authentication methods separated by space. Valid authentication methods are: basic, digest, negotiate, ntlm, any, none</p> 131 <p>Controls which http authentication methods are used. Multiple methods can be used. The value must be one or more authentication methods separated by space. Valid authentication methods are: basic, digest, negotiate, ntlm, any, none</p>
114 <p>Type: list of authmethod</p> 132 <p>Type: list of authmethod</p>
115 <p>Default: basic<br />Example: <code>&lt;authmethods&gt;basic digest&lt;/authmethods&gt;</code></p> 133 <p>Default: basic<br />
134 Example: <code>&lt;authmethods&gt;basic digest&lt;/authmethods&gt;</code></p>
116 <h2 id="key">key</h2> 135 <h2 id="key">key</h2>
117 <p>The <code>&lt;key&gt;</code> element configures a key used for encryption. A key must have a unique name, which is stored in the properties of encrypted resources. To decrypt resources, dav looks for configured keys with this name, therefore the name of the key should never changed and must be the same on all hosts accessing the same repository.</p> 136 <p>The <code>&lt;key&gt;</code> element configures a key used for encryption. A key must have a unique name, which is stored in the properties of encrypted resources. To decrypt resources, dav looks for configured keys with this name, therefore the name of the key should never changed and must be the same on all hosts accessing the same repository.</p>
118 <p>Required child elements: <code>&lt;name&gt;</code>, <code>&lt;file&gt;</code><br />Optional elements: <code>&lt;type&gt;</code></p> 137 <p>Required child elements: <code>&lt;name&gt;</code>, <code>&lt;file&gt;</code><br />
138 Optional elements: <code>&lt;type&gt;</code></p>
119 <h3 id="name-1">name</h3> 139 <h3 id="name-1">name</h3>
120 <p>Unique key identifer.</p> 140 <p>Unique key identifer.</p>
121 <p>Type: string<br />Example: <code>&lt;name&gt;key1&lt;/name&gt;</code></p> 141 <p>Type: string<br />
142 Example: <code>&lt;name&gt;key1&lt;/name&gt;</code></p>
122 <h3 id="file">file</h3> 143 <h3 id="file">file</h3>
123 <p>Path to the content of the key. The file should contain 32 (aes256) or 16 (aes128) bytes. If value is not an absolut path, it must be relative to the dav config directory <em>$HOME/.dav/</em>.</p> 144 <p>Path to the content of the key. The file should contain 32 (aes256) or 16 (aes128) bytes. If value is not an absolut path, it must be relative to the dav config directory <em>$HOME/.dav/</em>.</p>
124 <p>Type: string<br />Example: <code>&lt;path&gt;keys/key1.bin&lt;/path&gt;</code></p> 145 <p>Type: string<br />
146 Example: <code>&lt;path&gt;keys/key1.bin&lt;/path&gt;</code></p>
125 <h3 id="type">type</h3> 147 <h3 id="type">type</h3>
126 <p>Specifies the key type. Valid values are <code>aes128</code> or <code>aes256</code>.</p> 148 <p>Specifies the key type. Valid values are <code>aes128</code> or <code>aes256</code>.</p>
127 <p>Type: aes type enum<br />Default: aes256<br />Example: <code>&lt;type&gt;aes128&lt;/type&gt;</code></p> 149 <p>Type: aes type enum<br />
150 Default: aes256<br />
151 Example: <code>&lt;type&gt;aes128&lt;/type&gt;</code></p>
128 <h2 id="http-proxy-https-proxy">http-proxy / https-proxy</h2> 152 <h2 id="http-proxy-https-proxy">http-proxy / https-proxy</h2>
129 <p>Configuration for http and https proxies is the same. Both use the same elements, but https-proxy expects an https url.</p> 153 <p>Configuration for http and https proxies is the same. Both use the same elements, but https-proxy expects an https url.</p>
130 <p>Required child elements: <code>&lt;url&gt;</code><br />Optional elements: <code>&lt;user&gt;</code>, <code>&lt;password&gt;</code>, <code>&lt;no&gt;</code></p> 154 <p>Required child elements: <code>&lt;url&gt;</code><br />
155 Optional elements: <code>&lt;user&gt;</code>, <code>&lt;password&gt;</code>, <code>&lt;no&gt;</code></p>
131 <h3 id="url-1">url</h3> 156 <h3 id="url-1">url</h3>
132 <p>Specifies the proxy url.</p> 157 <p>Specifies the proxy url.</p>
133 <p>Type: url<br />Example: <code>&lt;url&gt;http://myproxy/&lt;/url&gt;</code></p> 158 <p>Type: url<br />
159 Example: <code>&lt;url&gt;http://myproxy/&lt;/url&gt;</code></p>
134 <h3 id="user-1">user</h3> 160 <h3 id="user-1">user</h3>
135 <p>User used for authentication with the proxy.</p> 161 <p>User used for authentication with the proxy.</p>
136 <p>Type: string<br />Example: <code>&lt;user&gt;alice&lt;/user&gt;</code></p> 162 <p>Type: string<br />
163 Example: <code>&lt;user&gt;alice&lt;/user&gt;</code></p>
137 <h3 id="password-1">password</h3> 164 <h3 id="password-1">password</h3>
138 <p>A base64 encoded password used for authentication.</p> 165 <p>A base64 encoded password used for authentication.</p>
139 <p>Type: base64 string<br />Example: <code>&lt;password&gt;MTIzNDU2Nzg=&lt;/password&gt;</code></p> 166 <p>Type: base64 string<br />
167 Example: <code>&lt;password&gt;MTIzNDU2Nzg=&lt;/password&gt;</code></p>
140 <h3 id="no">no</h3> 168 <h3 id="no">no</h3>
141 <p>A comma separated list of all hosts that should not be accessed through the proxy.</p> 169 <p>A comma separated list of all hosts that should not be accessed through the proxy.</p>
142 <p>Type: string<br />Example: <code>&lt;no&gt;host1, host2, host3&lt;/no&gt;</code></p> 170 <p>Type: string<br />
171 Example: <code>&lt;no&gt;host1, host2, host3&lt;/no&gt;</code></p>
143 <h2 id="example-1-minimal-repository-configuration">Example 1: minimal repository configuration</h2> 172 <h2 id="example-1-minimal-repository-configuration">Example 1: minimal repository configuration</h2>
144 <p>A minimal configuration for a repository. If no user and/or password are configured, dav prompts for authentication informations if required.</p> 173 <p>A minimal configuration for a repository. If no user and/or password are configured, dav prompts for authentication informations if required.</p>
145 <pre><code>&lt;configuration&gt; 174 <pre><code>&lt;configuration&gt;
146 &lt;repository&gt; 175 &lt;repository&gt;
147 &lt;name&gt;myrepo&lt;/name&gt; 176 &lt;name&gt;myrepo&lt;/name&gt;
165 &lt;name&gt;myrepo&lt;/name&gt; 194 &lt;name&gt;myrepo&lt;/name&gt;
166 &lt;url&gt;https://example.com/path/to/repo/&lt;/url&gt; 195 &lt;url&gt;https://example.com/path/to/repo/&lt;/url&gt;
167 &lt;user&gt;alice&lt;/user&gt; 196 &lt;user&gt;alice&lt;/user&gt;
168 &lt;password&gt;MTIzNDU2Nzg=&lt;/password&gt; 197 &lt;password&gt;MTIzNDU2Nzg=&lt;/password&gt;
169 &lt;full-encryption&gt;true&lt;/full-encryption&gt; 198 &lt;full-encryption&gt;true&lt;/full-encryption&gt;
199 &lt;default-key&gt;mykey1&lt;/default-key&gt;
170 &lt;/repository&gt; 200 &lt;/repository&gt;
171 201
172 &lt;key&gt; 202 &lt;key&gt;
173 &lt;name&gt;mykey1&lt;/name&gt; 203 &lt;name&gt;mykey1&lt;/name&gt;
174 &lt;file&gt;keys/mykey1&lt;/file&gt; 204 &lt;file&gt;keys/mykey1&lt;/file&gt;

mercurial