UNIXworkcode

1 --- 2 title: 'Configuration' 3 --- 4 5 The main configuration file for *dav* is `$HOME/.dav/config.xml` and is used for configuring repositories, proxies and encryption keys. This configuration is also used by *dav-sync*. The file is created automaticaly if it doesn't exist. 6 7 The *config.xml* file is an XML file with `<configuration>` as root element. The `<configuration>` element can have the following child elements: `<repository>`, `<http-proxy>`, `<https-proxy>`, `<key>`, `<namespace>` 8 9 ## repository 10 11 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. 12 13 Required child elements: `<name>`, `<url>` \ 14 Optional elements: `<user>`, `<password>`, `<default-key>`, `<full-encryption>`, `<content-encryption>`, `<decrypt-content>`, `<decrypt-name>`, `<cert>`, `<verification>`, `<ssl-version>`, `<authmethods>` 15 16 ### name 17 18 Unique repository identifer. 19 20 Type: string \ 21 Example: `<name>myrepo</name>` 22 23 ### url 24 25 The url must point to a valid WebDAV compilant collection. 26 27 Type: url \ 28 Example: `<url>https://example.com/webdav/repo1/</url>` 29 30 ### user 31 32 User used for authentication 33 34 Type: string \ 35 Example: `<user>alice</user>` 36 37 ### password 38 39 A base64 encoded password used for authentication. 40 41 Type: base64 string \ 42 Example: `<password>MTIzNDU2Nzg=</password>` 43 44 ### stored-user 45 46 Credentials id used for authentication. The credentials must be stored in the secret store. 47 48 Type: string \ 49 Example: `<stored-user>alice</stored-user>` 50 51 ### default-key 52 53 Identifer of the key used by default for encryption. There must be a configured key with this name. 54 55 Type: string \ 56 Example: `<default-key>mykey</default-key>` 57 58 ### full-encryption 59 60 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, `false` has no effect for this element. 61 62 Type: boolean \ 63 Default: false \ 64 Example: `<full-encryption>true</full-encryption>` 65 66 ### content-encryption 67 68 This element enables only content encryption and decryption. A value of `false` disables content encryption, but it does not disables content decryption, if this is enabled with `<decrypt-content>`. 69 70 Type: boolean \ 71 Default: false \ 72 Example: `<content-encryption>true</content-encryption>` 73 74 ### decrypt-content 75 76 Controls only the decryption of content. If `true` content is decrypted. 77 78 Type: boolean \ 79 Default false \ 80 Example: `<decrypt-content>true</decrypt-content>` 81 82 ### decrypt-name 83 84 Controls only the decryption of resource names. If `true` resource names are decrypted. This effects path to url resolution. 85 86 Type: boolean \ 87 Default: false \ 88 Example: `<decrypt-name>true</decrypt-name>` 89 90 ### cert 91 92 Path to a file containing certificates to verify the TLS connection to the server. 93 94 Type: string \ 95 Example: `<cert>/etc/certs/cabundle.pem</cert>` 96 97 Note: This element does the same as curl's `--cacert` option. 98 99 ### verification 100 101 This element can disable TLS certificate verification. 102 103 Type: boolean \ 104 Default: true \ 105 Example: `<verification>false</verification>` 106 107 ### ssl-version 108 109 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 110 111 Type: ssl version enum \ 112 Example: `<ssl-version>TLSv1.2</ssl-version>` 113 114 ### authmethods 115 116 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 117 118 Type: list of authmethod 119 120 Default: basic \ 121 Example: `<authmethods>basic digest</authmethods>` 122 123 ## key 124 125 The `<key>` 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. 126 127 Required child elements: `<name>`, `<file>` \ 128 Optional elements: `<type>` 129 130 ### name 131 132 Unique key identifer. 133 134 Type: string \ 135 Example: `<name>key1</name>` 136 137 ### file 138 139 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 *$HOME/.dav/*. 140 141 Type: string \ 142 Example: `<path>keys/key1.bin</path>` 143 144 ### type 145 146 Specifies the key type. Valid values are `aes128` or `aes256`. 147 148 Type: aes type enum \ 149 Default: aes256 \ 150 Example: `<type>aes128</type>` 151 152 ## http-proxy / https-proxy 153 154 Configuration for http and https proxies is the same. Both use the same elements, but https-proxy expects an https url. 155 156 Required child elements: `<url>` \ 157 Optional elements: `<user>`, `<password>`, `<no>` 158 159 ### url 160 161 Specifies the proxy url. 162 163 Type: url \ 164 Example: `<url>http://myproxy/</url>` 165 166 ### user 167 168 User used for authentication with the proxy. 169 170 Type: string \ 171 Example: `<user>alice</user>` 172 173 ### password 174 175 A base64 encoded password used for authentication. 176 177 Type: base64 string \ 178 Example: `<password>MTIzNDU2Nzg=</password>` 179 180 ### no 181 182 A comma separated list of all hosts that should not be accessed through the proxy. 183 184 Type: string \ 185 Example: `<no>host1, host2, host3</no>` 186 187 ## namespace 188 189 Configures an XML-namespace with prefix and uri. The prefix can be used with commands like `get-property`. The element must have the `prefix` and the `uri` attribute. 190 191 Type: no value 192 Example: `<namespace prefix="e" uri="http://example.com/" />` 193 194 ## Example 1: minimal repository configuration 195 196 A minimal configuration for a repository. If no user and/or password are configured, dav prompts for authentication informations if required. 197 198 <configuration> 199 <repository> 200 <name>myrepo</name> 201 <url>https://example.com/path/to/repo/</url> 202 </repository> 203 </configuration> 204 205 ## Example 2: repository with authentication informations 206 207 A typical configuration for easy accessing a repository without authentication prompt. 208 209 <configuration> 210 <repository> 211 <name>myrepo</name> 212 <url>https://example.com/path/to/repo/</url> 213 <user>alice</user> 214 <password>MTIzNDU2Nzg=</password> 215 </repository> 216 </configuration> 217 218 ## Example 3: repository with full encryption 219 220 A configuration for a full encrypted repository. Additionally to the repository a key must be configured. 221 222 <configuration> 223 <repository> 224 <name>myrepo</name> 225 <url>https://example.com/path/to/repo/</url> 226 <user>alice</user> 227 <password>MTIzNDU2Nzg=</password> 228 <full-encryption>true</full-encryption> 229 <default-key>mykey1</default-key> 230 </repository> 231 232 <key> 233 <name>mykey1</name> 234 <file>keys/mykey1</file> 235 <type>aes256</type> 236 </key> 237 </configuration> 238 239