comparison: docs/src/configuration.md
docs/src/configuration.md
- changeset 266
- 8c44c5919691
- parent 265
- ee9e63c437c4
- child 273
- c743721d566f
equal
deleted
inserted
replaced
| 265:ee9e63c437c4 | 266:8c44c5919691 |
|---|---|
| 1 Configuration | |
| 2 ============= | |
| 3 | |
| 4 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. | |
| 5 | |
| 6 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>` | |
| 7 | |
| 8 ## repository | |
| 9 | |
| 10 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. | |
| 11 | |
| 12 Required child elements: `<name>`, `<url>` \ | |
| 13 Optional elements: `<user>`, `<password>`, `<default-key>`, `<full-encryption>`, `<content-encryption>`, `<decrypt-content>`, `<decrypt-name>`, `<cert>`, `<verification>`, `<ssl-version>`, `<authmethods>` | |
| 14 | |
| 15 ### name | |
| 16 | |
| 17 Unique repository identifer. | |
| 18 | |
| 19 Type: string \ | |
| 20 Example: `<name>myrepo</name>` | |
| 21 | |
| 22 ### url | |
| 23 | |
| 24 The url must point to a valid WebDAV compilant collection. | |
| 25 | |
| 26 Type: string \ | |
| 27 Example: `<url>https://example.com/webdav/repo1/</url>` | |
| 28 | |
| 29 ### user | |
| 30 | |
| 31 User used for authentication | |
| 32 | |
| 33 Type: string \ | |
| 34 Example: `<user>alice</user>` | |
| 35 | |
| 36 ### password | |
| 37 | |
| 38 A base64 encoded password used for authentication. | |
| 39 | |
| 40 Type: base64 string \ | |
| 41 Example: `<password>MTIzNDU2Nzg=</password>` | |
| 42 | |
| 43 ### default-key | |
| 44 | |
| 45 Identifer of the key used by default for encryption. There must be a configured key with this name. | |
| 46 | |
| 47 Type: string \ | |
| 48 Example: `<key>mykey</key>` | |
| 49 | |
| 50 ### full-encryption | |
| 51 | |
| 52 If this element has the value of true, content and resource name encryption/decryption is enabled. Because encryption and decryption is disabled by default, `false` has no effect for this element. | |
| 53 | |
| 54 Type: boolean \ | |
| 55 Default: false \ | |
| 56 Example: `<full-encryption>true</full-encryption> | |
| 57 | |
| 58 ### content-encryption | |
| 59 | |
| 60 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>`. | |
| 61 | |
| 62 Type: boolean \ | |
| 63 Default: false \ | |
| 64 Example: `<content-encryption>true</content-encryption>` | |
| 65 | |
| 66 ### decrypt-content | |
| 67 | |
| 68 Controls only the decryption of content. If `true` content is decrypted. | |
| 69 | |
| 70 Type: boolean \ | |
| 71 Default false \ | |
| 72 Example: `<decrypt-content>true</decrypt-content>` | |
| 73 | |
| 74 ### decrypt-name | |
| 75 | |
| 76 Controls only the decryption of resource names. If `true` resource names are decrypted. This effects path to url resolution. | |
| 77 | |
| 78 Type: boolean \ | |
| 79 Default: false \ | |
| 80 Example: `<decrypt-name>true</decrypt-name>` | |
| 81 | |
| 82 ### cert | |
| 83 | |
| 84 Path to a file containing certificates to verify the TLS connection to the server. | |
| 85 | |
| 86 Type: string \ | |
| 87 Example: `<cert>/etc/certs/cabundle.pem</cert>` | |
| 88 | |
| 89 Note: This element does the same as curl's `--cacert` option. | |
| 90 | |
| 91 ### verification | |
| 92 | |
| 93 This element can disable TLS certificate verification. | |
| 94 | |
| 95 Type: boolean \ | |
| 96 Default: true \ | |
| 97 Example: `<verification>false</verification>` | |
| 98 | |
| 99 ### ssl-version | |
| 100 | |
| 101 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 | |
| 102 | |
| 103 Type: ssl version enum \ | |
| 104 Example: `<ssl-version>TLSv1.2</ssl-version>` | |
| 105 | |
| 106 ### authmethods | |
| 107 | |
| 108 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 | |
| 109 | |
| 110 Type: list of authmethod | |
| 111 | |
| 112 Default: basic \ | |
| 113 Example: `<authmethods>basic digest</authmethods>` | |
| 114 | |
| 115 ## key | |
| 116 | |
| 117 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. | |
| 118 | |
| 119 Required child elements: `<name>`, `<file>` \ | |
| 120 Optional elements: `<type>` | |
| 121 | |
| 122 ### name | |
| 123 | |
| 124 Unique key identifer. | |
| 125 | |
| 126 Type: string \ | |
| 127 Example: `<name>key1</name>` | |
| 128 | |
| 129 ### file | |
| 130 | |
| 131 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/*. | |
| 132 | |
| 133 Type: string \ | |
| 134 Example: `<path>keys/key1.bin</path>` | |
| 135 | |
| 136 ### type | |
| 137 | |
| 138 Specifies the key type. Valid values are `aes128` or `aes256`. | |
| 139 | |
| 140 Type: aes type enum \ | |
| 141 Default: aes256 \ | |
| 142 Example: `<type>aes128</type>` | |
| 143 | |
| 144 ## http-proxy / https-proxy | |
| 145 | |
| 146 Configuration for http and https proxies is the same. Both use the same elements, but https-proxy expects an https url. | |
| 147 | |
| 148 Required child elements: `<url>` \ | |
| 149 Optional elements: `<user>`, `<password>`, `<no>` | |
| 150 | |
| 151 ### url | |
| 152 | |
| 153 ### user | |
| 154 | |
| 155 ### password | |
| 156 | |
| 157 ### no | |
| 158 | |
| 159 ## Example 1: minimal repository configuration | |
| 160 | |
| 161 A minimal configuration for a repository. If no user and/or password are configured, dav prompts for authentication informations if required. | |
| 162 | |
| 163 <repository> | |
| 164 <name>myrepo</name> | |
| 165 <url>https://example.com/path/to/repo/</url> | |
| 166 </repository> | |
| 167 | |
| 168 ## Example 2: repository with authentication informations | |
| 169 | |
| 170 A typical configuration for easy accessing a repository without authentication prompt. | |
| 171 | |
| 172 <repository> | |
| 173 <name>myrepo</name> | |
| 174 <url>https://example.com/path/to/repo/</url> | |
| 175 <user>alice</user> | |
| 176 <password>MTIzNDU2Nzg=</password> | |
| 177 </repository> | |
| 178 |
