sync-configuration.md - UNIXwork Code

1 --- 2 title: 'Configuration' 3 --- 4 5 The file `$HOME/.dav/sync.xml` is used for configuring sync-directories. 6 7 The *sync.xml* file is an XML file with `<configuration>` as root element. This element can only have `<directory>` elements as children. 8 9 ## directory 10 11 This element configures a sync-directory. A sync-directory must have a unique name, a (local) path, repository and a database. 12 13 Required elements: `<name>`, `<repository>`, `<path>`, `<database>` \ 14 Optional elements: `<collection>`, `<trash>`, `<max-retry>`, `<backup-on-pull>`, `<lock-pull>`, `<lock-push>`, `<lock-timeout>`, `<filter>`, `<metadata>`, `<versioning>`, `<splitconfig>`, `<symlink-intern>`, `<symlink-extern>`, `<tagconfig>`, `<allow-cmd>` 15 16 ### name 17 18 Unique sync-directory identifer. This identifer is used in combination with all *dav-sync* commands. 19 20 Type: string \ 21 Example: `<name>mysyncdir</name>` 22 23 ### repository 24 25 Name of the WebDAV-repository. A repository with the same name must be configured in [config.xml][1]. 26 27 Type: string \ 28 Example: `<name>myrepo</name>` 29 30 ### path 31 32 The path of the local directory that should be synchronized. The path must be an absolute path or start with an environment variable. A path with an environment variable must start with an `$` followed by the variable name optionally followed by a path. For example: 33 34 `<path>$HOME/Documents</path>` 35 36 The part between `$` and `/` is the environment variable name. 37 38 Type: string \ 39 Example: `<path>/absolute/path</path>` 40 41 ### database 42 43 Path to the database file used for this sync-directory. The path must be relative to the *$HOME/.dav/* directory. 44 45 Type: string \ 46 Example: `<database>myrepo-db.xml</database>` 47 48 ### collection 49 50 Path of the collection relative to the repository root collection. For example if the repository url is *http://example.com/webdav/* and the collection value is */myfiles/*, the directory is synchronized with *http://example.com/webdav/myfiles/* 51 52 Type: string \ 53 Default: / \ 54 Example: `<collection>/myfiles</collection>` 55 56 ### hashing 57 58 Enables file hashing. The hash will be used for checking if files are modified and should be synchronized. 59 60 Type: boolean \ 61 Default: false \ 62 Example: `<hashing>true</hashing>` 63 64 ### trash 65 66 Path to the trash directory for this sync-directory. Files that should be deleted will be moved to this directory. The value must be an absolute path or relative to the sync-directory path. 67 68 Type: string \ 69 Example: `<trash>.trash</trash>` 70 71 ### push-strategy 72 73 Controls the strategy *push* uses for deciding which files should be pushed. Possible values are: `metadata` and `hash`. 74 75 Type: pushstrategy enum \ 76 Default: metadata 77 Example: `<push-strategy>hash</push-strategy>` 78 79 ### max-retry 80 81 This integer value controls how many attempts of downloading/uploading a file in case of an error are made. 82 83 Type: integer \ 84 Default: 0 \ 85 Example: `<max-retry>3</max-retry>` 86 87 ### backup-on-pull 88 89 If this element has the value of true, the *pull* command will move old local files to the trash directory before downloading the new version from the server. 90 91 Type: boolean \ 92 Default: false \ 93 Example: `<backup-on-pull>true</backup-on-pull>` 94 95 ### lock-pull 96 97 Enables locking for the *pull* command. 98 99 Type: boolean \ 100 Default: false \ 101 Example: `<lock-pull>true</lock-pull>` 102 103 ### lock-push 104 105 Enables locking for the *push* command. 106 107 Type: boolean \ 108 Default: false \ 109 Example: `<lock-push>true</lock-push>` 110 111 ### lock-timeout 112 113 Specifies the lock timeout in seconds. If the lock-timeout is 0, the client doesn't request a specific timeout and the server's default value is used. If the lock-timeout is -1, a infinite timeout is requested. 114 115 Type: integer \ 116 Default: 0 \ 117 Example: `<lock-timeout>50</lock-timeout>` 118 119 ### metadata 120 121 Controls which file metadata should be synchronized. Possible values are: `mtime`, `mode`, `xattr` and `all`. If this element is not specified, no metadata will be synchronized. 122 123 Type: list of metadata \ 124 Example: `<metadata>mtime mode</metadata>` 125 126 ### versioning 127 128 Enables resource versioning for the commands *push* and *archive*. 129 130 Possible attributes: `type`, `always` 131 132 The attribute `type` sets the versioning method type. Possible values are `simple` and `deltav`. With *simple* versioning, resources are moved to a version history collection before the new content is uploaded. With *deltav*, the DeltaV methods *checkout* and *checkin* are used to store versions. The default value of the `type` attribute is `simple`. 133 134 The boolean attribute `always` specifies if new versions should be always created. The default value is `false`. 135 136 Optional elements: `<history>` 137 Example: `<versioning type="simple" always="true" />` 138 139 ### history 140 141 Specifies the history collection path for *simple* versioning. The path is interpreted relatively to the root of the sync directory. 142 143 Type: string \ 144 Default: `/.dav-version-history` 145 Example: 146 147 <versioning type="simple"> 148 <history>/.backup/</history> 149 </versioning> 150 151 ### symlink-intern 152 153 Configures the handling of symlinks, which have a target inside the sync directory. Possible values are: `sync`, `follow` and `ignore`. 154 155 Type: symlink enum \ 156 Default: follow \ 157 Example: `<symlink-intern>sync</symlink-intern>` 158 159 ## symlink-extern 160 161 Configures the handling of symlinks, which have a target outside the sync directory. Possible values are: `follow` and `ignore`. Unlike internal symlinks, external symlinks cannot be synced. 162 163 Type: symlink enum \ 164 Default: follow \ 165 Example: `<symlink-extern>ignore</symlink-extern>` 166 167 ### tagconfig 168 169 Configures the local store for resource tags. If this element is specified, resource tags are stored locally. 170 171 Optional elements: local-store, detect-changes, xattr-name, on-conflict 172 173 ### local-store 174 175 Specifies the tag-store type. Currently the only available type is `xattr`. 176 177 The element can contain the attribute `format` with one of the following values: `text`, `csv`, `xml`, `macos`. The default value is `text`. 178 179 Type: tagstore type enum \ 180 Default: xattr \ 181 Example: `<local-store format="csv">xattr</local-store>` 182 183 ### xattr-name 184 185 Specifies the name of the extended attribute for storing tags. The default value is `tags`, unless you are using the `macos` format, where the default value is `com.apple.metadata:_kMDItemUserTags`. 186 187 Type: string \ 188 Default: tags \ 189 Example: `<xattr-name>file_tags</xattr-name> 190 191 ### detect-changes 192 193 Controls, if tag changes should be detected. 194 195 Type: boolean \ 196 Default: false \ 197 Example: `<detect-changes>true</detect-changes>` 198 199 ### on-conflict 200 201 Specifies the behavior, when tag conflicts occur. Possible values are: `no_conflict`, `keep_local`, `keep_remote`, `merge` 202 203 Type: onconflict enum \ 204 Default: no_conflict \ 205 Example: `<on-conflict>merge</on-conflict>` 206 207 ### splitconfig 208 209 Parent element for all `<split>` elements. 210 211 ### split 212 213 Configures if and how files should be splitted into multiple parts on *push*. 214 215 The blocksize element configures the size of each part. 216 217 The elements filter and minsize specify, in which case the files should be splitted. 218 219 Required elements: `<blocksize>` \ 220 Optional elements: `<filter>`, `<minsize>` 221 222 Example: 223 224 <splitconfig> 225  226 <split> 227 <blocksize>10m</blocksize> 228 <filter> 229 <include>\.vmdk$</include> 230 </filter> 231 <minsize>100m</minsize> 232 </split> 233 </splitconfig> 234 235 ### blocksize 236 237 Specifies the size of each file part. 238 239 Type: size \ 240 Example: `<blocksize>100k</blocksize>` 241 242 ### minsize 243 244 Specifies the minimal size a file must have for enabling file splitting. 245 246 Type: size \ 247 Default: 0 \ 248 Example: `<minsize>100m</minsize>` 249 250 ### filter 251 252 With the filter element, include and exclude filters can be specified, to control which files are synchronized. The *pull*, *push* and *archive* command apply these filters to file paths. At first it is checked if a file is matching any include filter. If so only files matching not an exclude filter are further processed. 253 254 It is also possible to filter resources by tags. Tags can dynamically be applied to individual files. The tag filter elements contains a tag filter expression. Only files that match the filter expression are synchronized. 255 256 Note: The file path is relative to the directory path (and WebDAV collection) but always starts with an path separator. 257 258 Optional elements: `<include>`, `<exclude>`, `<tags>` 259 260 ### include 261 262 Controls which files will be included by *pull* and *push*. If an include filter is specified, only files matching this filter are included. 263 264 Type: regex string \ 265 Default: .* \ 266 Example: 267 268 <filter> 269 <include>\.pdf$</include> 270 </filter> 271 272 ### exclude 273 274 Controls which files will be excluded by *pull* and *push*. 275 276 Type: regex string \ 277 Example: 278 279 <filter> 280 <exclude>^/secretdir</exclude> 281 <exclude>\.DS_Store$</exclude> 282 </filter> 283 284 ### tags 285 286 Filters resources by tags. Only resources, that are not a collection, are effected. If tags are not stored locally, the pull command still uses the filter. 287 288 Filter Syntax: 289 290 filter ::= operator? , (tag_list | ("(" , filter , ")")+) 291 tag_list ::= tag , ("," tag)* 292 operator ::= "&" | "|" | "1" | "0" 293 294 Type: tag filter expression \ 295 Example: 296 297 <filter> 298  299 <tags>| (tag1, tag2, tag3)</tags> 300 </filter> 301 302

UNIXworkcode

UNIXwork`code`