sync-configuration.html - UNIXwork Code

1 <!DOCTYPE html> 2 <html xmlns="http://www.w3.org/1999/xhtml" lang="" xml:lang=""> 3 <head> 4 <meta charset="utf-8" /> 5 <meta name="generator" content="pandoc" /> 6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" /> 7 <title>Configuration</title> 8 <style type="text/css"> 9 code{white-space: pre-wrap;} 10 span.smallcaps{font-variant: small-caps;} 11 span.underline{text-decoration: underline;} 12 div.column{display: inline-block; vertical-align: top; width: 50%;} 13 </style> 14 <link rel="stylesheet" href="davdoc.css" /> 15  18 </head> 19 <body> 20 <div class="header"> 21 <a href="./index.html"><span>DavUtils documentation</span></a> 22 </div> 23 <div class="sidebar"> 24 <div class="nav"> 25 <h3>dav</h3> 26 <ul> 27 <li><a href="getting-started.html">Getting started</a></li> 28 <li><a href="commands.html">Commands</a></li> 29 <ul> 30 <li><a href="list.html">list</a></li> 31 <li><a href="get.html">get</a></li> 32 <li><a href="put.html">put</a></li> 33 <li><a href="mkdir.html">mkdir</a></li> 34 <li><a href="remove.html">remove</a></li> 35 <li><a href="copy.html">copy</a></li> 36 <li><a href="move.html">move</a></li> 37 <li><a href="rename.html">rename</a></li> 38 <li><a href="export.html">export</a></li> 39 <li><a href="import.html">import</a></li> 40 <li><a href="get-property.html">get-property</a></li> 41 <li><a href="set-property.html">set-property</a></li> 42 <li><a href="remove-property.html">remove-property</a></li> 43 <li><a href="lock.html">lock</a></li> 44 <li><a href="unlock.html">unlock</a></li> 45 <li><a href="info.html">info</a></li> 46 <li><a href="date.html">date</a></li> 47 <li><a href="versioncontrol.html">versioncontrol</a></li> 48 <li><a href="list-versions.html">list-versions</a></li> 49 <li><a href="checkout.html">checkout</a></li> 50 <li><a href="checkin.html">checkin</a></li> 51 <li><a href="uncheckout.html">uncheckout</a></li> 52 <li><a href="add-repository.html">add-repository</a></li> 53 <li><a href="remove-repository.html">remove-repository</a></li> 54 <li><a href="list-repositories.html">list-repositories</a></li> 55 <li><a href="repository-url.html">repository-url</a></li> 56 <li><a href="add-user.html">add-user</a></li> 57 <li><a href="remove-user.html">remove-user</a></li> 58 <li><a href="edit-user.html">edit-user</a></li> 59 <li><a href="list-users.html">list-users</a></li> 60 <li><a href="check-config.html">check-config</a></li> 61 </ul> 62 <li><a href="configuration.html">Configuration</a></li> 63 <li><a href="encryption.html">Encryption</a></li> 64 </ul> 65 </div> 66 <div class="nav"> 67 <h3>dav-sync</h3> 68 <ul> 69 <li><a href="introduction.html">Introduction</a></li> 70 <li><a href="sync-commands.html">Commands</a></li> 71 <ul> 72 <li><a href="pull.html">pull</a></li> 73 <li><a href="push.html">push</a></li> 74 <li><a href="archive.html">archive</a></li> 75 <li><a href="restore.html">restore</a></li> 76 <li><a href="list-conflicts.html">list-conflicts</a></li> 77 <li><a href="resolve-conflicts.html">resolve-conflicts</a></li> 78 <li><a href="delete-conflicts.html">delete-conflicts</a></li> 79 <li><a href="trash-info.html">trash-info</a></li> 80 <li><a href="empty-trash.html">empty-trash</a></li> 81 <li><a href="list-versions.html">list-versions</a></li> 82 <li><a href="add-tag.html">add-tag</a></li> 83 <li><a href="remove-tag.html">remove-tag</a></li> 84 <li><a href="set-tags.html">set-tags</a></li> 85 <li><a href="list-tags.html">list-tags</a></li> 86 <li><a href="add-directory.html">add-directory</a></li> 87 <li><a href="list-directories.html">list-directories</a></li> 88 <li><a href="sync-check-config.html">check-config</a></li> 89 <li><a href="check-repositories.html">check-repositories</a></li> 90 </ul> 91 <li><a href="sync-configuration.html">Configuration</a></li> 92 </ul> 93 </div> 94 </div> 95 96  97 <div class="content"> 98 <header> 99 <h1 class="title">Configuration</h1> 100 </header> 101 <p>The file <code>$HOME/.dav/sync.xml</code> is used for configuring sync-directories.</p> 102 <p>The <em>sync.xml</em> file is an XML file with <code><configuration></code> as root element. This element can only have <code><directory></code> elements as children.</p> 103 <h2 id="directory">directory</h2> 104 <p>This element configures a sync-directory. A sync-directory must have a unique name, a (local) path, repository and a database.</p> 105 <p>Required elements: <code><name></code>, <code><repository></code>, <code><path></code>, <code><database></code><br /> 106 Optional elements: <code><collection></code>, <code><trash></code>, <code><max-retry></code>, <code><backup-on-pull></code>, <code><lock-pull></code>, <code><lock-push></code>, <code><lock-timeout></code>, <code><filter></code>, <code><metadata></code>, <code><versioning></code>, <code><splitconfig></code>, <code><symlink-intern></code>, <code><symlink-extern></code>, <code><tagconfig></code>, <code><allow-cmd></code></p> 107 <h3 id="name">name</h3> 108 <p>Unique sync-directory identifer. This identifer is used in combination with all <em>dav-sync</em> commands.</p> 109 <p>Type: string<br /> 110 Example: <code><name>mysyncdir</name></code></p> 111 <h3 id="repository">repository</h3> 112 <p>Name of the WebDAV-repository. A repository with the same name must be configured in [config.xml][1].</p> 113 <p>Type: string<br /> 114 Example: <code><name>myrepo</name></code></p> 115 <h3 id="path">path</h3> 116 <p>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 <code>$</code> followed by the variable name optionally followed by a path. For example:</p> 117 <pre><code>`<path>$HOME/Documents</path>`</code></pre> 118 <p>The part between <code>$</code> and <code>/</code> is the environment variable name.</p> 119 <p>Type: string<br /> 120 Example: <code><path>/absolute/path</path></code></p> 121 <h3 id="database">database</h3> 122 <p>Path to the database file used for this sync-directory. The path must be relative to the <em>$HOME/.dav/</em> directory.</p> 123 <p>Type: string<br /> 124 Example: <code><database>myrepo-db.xml</database></code></p> 125 <h3 id="collection">collection</h3> 126 <p>Path of the collection relative to the repository root collection. For example if the repository url is <em>http://example.com/webdav/</em> and the collection value is <em>/myfiles/</em>, the directory is synchronized with <em>http://example.com/webdav/myfiles/</em></p> 127 <p>Type: string<br /> 128 Default: /<br /> 129 Example: <code><collection>/myfiles</collection></code></p> 130 <h3 id="hashing">hashing</h3> 131 <p>Enables file hashing. The hash will be used for checking if files are modified and should be synchronized.</p> 132 <p>Type: boolean<br /> 133 Default: false<br /> 134 Example: <code><hashing>true</hashing></code></p> 135 <h3 id="trash">trash</h3> 136 <p>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.</p> 137 <p>Type: string<br /> 138 Example: <code><trash>.trash</trash></code></p> 139 <h3 id="push-strategy">push-strategy</h3> 140 <p>Controls the strategy <em>push</em> uses for deciding which files should be pushed. Possible values are: <code>metadata</code> and <code>hash</code>.</p> 141 <p>Type: pushstrategy enum<br /> 142 Default: metadata Example: <code><push-strategy>hash</push-strategy></code></p> 143 <h3 id="max-retry">max-retry</h3> 144 <p>This integer value controls how many attempts of downloading/uploading a file in case of an error are made.</p> 145 <p>Type: integer<br /> 146 Default: 0<br /> 147 Example: <code><max-retry>3</max-retry></code></p> 148 <h3 id="backup-on-pull">backup-on-pull</h3> 149 <p>If this element has the value of true, the <em>pull</em> command will move old local files to the trash directory before downloading the new version from the server.</p> 150 <p>Type: boolean<br /> 151 Default: false<br /> 152 Example: <code><backup-on-pull>true</backup-on-pull></code></p> 153 <h3 id="lock-pull">lock-pull</h3> 154 <p>Enables locking for the <em>pull</em> command.</p> 155 <p>Type: boolean<br /> 156 Default: false<br /> 157 Example: <code><lock-pull>true</lock-pull></code></p> 158 <h3 id="lock-push">lock-push</h3> 159 <p>Enables locking for the <em>push</em> command.</p> 160 <p>Type: boolean<br /> 161 Default: false<br /> 162 Example: <code><lock-push>true</lock-push></code></p> 163 <h3 id="lock-timeout">lock-timeout</h3> 164 <p>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.</p> 165 <p>Type: integer<br /> 166 Default: 0<br /> 167 Example: <code><lock-timeout>50</lock-timeout></code></p> 168 <h3 id="metadata">metadata</h3> 169 <p>Controls which file metadata should be synchronized. Possible values are: <code>mtime</code>, <code>mode</code>, <code>xattr</code> and <code>all</code>. If this element is not specified, no metadata will be synchronized.</p> 170 <p>Type: list of metadata<br /> 171 Example: <code><metadata>mtime mode</metadata></code></p> 172 <h3 id="versioning">versioning</h3> 173 <p>Enables resource versioning for the commands <em>push</em> and <em>archive</em>.</p> 174 <p>Possible attributes: <code>type</code>, <code>always</code></p> 175 <p>The attribute <code>type</code> sets the versioning method type. Possible values are <code>simple</code> and <code>deltav</code>. With <em>simple</em> versioning, resources are moved to a version history collection before the new content is uploaded. With <em>deltav</em>, the DeltaV methods <em>checkout</em> and <em>checkin</em> are used to store versions. The default value of the <code>type</code> attribute is <code>simple</code>.</p> 176 <p>The boolean attribute <code>always</code> specifies if new versions should be always created. The default value is <code>false</code>.</p> 177 <p>Optional elements: <code><history></code> Example: <code><versioning type="simple" always="true" /></code></p> 178 <h3 id="history">history</h3> 179 <p>Specifies the history collection path for <em>simple</em> versioning. The path is interpreted relatively to the root of the sync directory.</p> 180 <p>Type: string<br /> 181 Default: <code>/.dav-version-history</code> Example:</p> 182 <pre><code><versioning type="simple"> 183 <history>/.backup/</history> 184 </versioning></code></pre> 185 <h3 id="symlink-intern">symlink-intern</h3> 186 <p>Configures the handling of symlinks, which have a target inside the sync directory. Possible values are: <code>sync</code>, <code>follow</code> and <code>ignore</code>.</p> 187 <p>Type: symlink enum<br /> 188 Default: follow<br /> 189 Example: <code><symlink-intern>sync</symlink-intern></code></p> 190 <h2 id="symlink-extern">symlink-extern</h2> 191 <p>Configures the handling of symlinks, which have a target outside the sync directory. Possible values are: <code>follow</code> and <code>ignore</code>. Unlike internal symlinks, external symlinks cannot be synced.</p> 192 <p>Type: symlink enum<br /> 193 Default: follow<br /> 194 Example: <code><symlink-extern>ignore</symlink-extern></code></p> 195 <h3 id="tagconfig">tagconfig</h3> 196 <p>Configures the local store for resource tags. If this element is specified, resource tags are stored locally.</p> 197 <p>Optional elements: local-store, detect-changes, xattr-name, on-conflict</p> 198 <h3 id="local-store">local-store</h3> 199 <p>Specifies the tag-store type. Currently the only available type is <code>xattr</code>.</p> 200 <p>The element can contain the attribute <code>format</code> with one of the following values: <code>text</code>, <code>csv</code>, <code>xml</code>, <code>macos</code>. The default value is <code>text</code>.</p> 201 <p>Type: tagstore type enum<br /> 202 Default: xattr<br /> 203 Example: <code><local-store format="csv">xattr</local-store></code></p> 204 <h3 id="xattr-name">xattr-name</h3> 205 <p>Specifies the name of the extended attribute for storing tags. The default value is <code>tags</code>, unless you are using the <code>macos</code> format, where the default value is <code>com.apple.metadata:_kMDItemUserTags</code>.</p> 206 <p>Type: string<br /> 207 Default: tags<br /> 208 Example: `<xattr-name>file_tags</xattr-name></p> 209 <h3 id="detect-changes">detect-changes</h3> 210 <p>Controls, if tag changes should be detected.</p> 211 <p>Type: boolean<br /> 212 Default: false<br /> 213 Example: <code><detect-changes>true</detect-changes></code></p> 214 <h3 id="on-conflict">on-conflict</h3> 215 <p>Specifies the behavior, when tag conflicts occur. Possible values are: <code>no_conflict</code>, <code>keep_local</code>, <code>keep_remote</code>, <code>merge</code></p> 216 <p>Type: onconflict enum<br /> 217 Default: no_conflict<br /> 218 Example: <code><on-conflict>merge</on-conflict></code></p> 219 <h3 id="splitconfig">splitconfig</h3> 220 <p>Parent element for all <code><split></code> elements.</p> 221 <h3 id="split">split</h3> 222 <p>Configures if and how files should be splitted into multiple parts on <em>push</em>.</p> 223 <p>The blocksize element configures the size of each part.</p> 224 <p>The elements filter and minsize specify, in which case the files should be splitted.</p> 225 <p>Required elements: <code><blocksize></code><br /> 226 Optional elements: <code><filter></code>, <code><minsize></code></p> 227 <p>Example:</p> 228 <pre><code><splitconfig> 229  230 <split> 231 <blocksize>10m</blocksize> 232 <filter> 233 <include>\.vmdk$</include> 234 </filter> 235 <minsize>100m</minsize> 236 </split> 237 </splitconfig></code></pre> 238 <h3 id="blocksize">blocksize</h3> 239 <p>Specifies the size of each file part.</p> 240 <p>Type: size<br /> 241 Example: <code><blocksize>100k</blocksize></code></p> 242 <h3 id="minsize">minsize</h3> 243 <p>Specifies the minimal size a file must have for enabling file splitting.</p> 244 <p>Type: size<br /> 245 Default: 0<br /> 246 Example: <code><minsize>100m</minsize></code></p> 247 <h3 id="filter">filter</h3> 248 <p>With the filter element, include and exclude filters can be specified, to control which files are synchronized. The <em>pull</em>, <em>push</em> and <em>archive</em> 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.</p> 249 <p>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.</p> 250 <p>Note: The file path is relative to the directory path (and WebDAV collection) but always starts with an path separator.</p> 251 <p>Optional elements: <code><include></code>, <code><exclude></code>, <code><tags></code></p> 252 <h3 id="include">include</h3> 253 <p>Controls which files will be included by <em>pull</em> and <em>push</em>. If an include filter is specified, only files matching this filter are included.</p> 254 <p>Type: regex string<br /> 255 Default: .*<br /> 256 Example:</p> 257 <pre><code><filter> 258 <include>\.pdf$</include> 259 </filter></code></pre> 260 <h3 id="exclude">exclude</h3> 261 <p>Controls which files will be excluded by <em>pull</em> and <em>push</em>.</p> 262 <p>Type: regex string<br /> 263 Example:</p> 264 <pre><code><filter> 265 <exclude>^/secretdir</exclude> 266 <exclude>\.DS_Store$</exclude> 267 </filter></code></pre> 268 <h3 id="tags">tags</h3> 269 <p>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.</p> 270 <p>Filter Syntax:</p> 271 <pre><code>filter ::= operator? , (tag_list | ("(" , filter , ")")+) 272 tag_list ::= tag , ("," tag)* 273 operator ::= "&" | "|" | "1" | "0"</code></pre> 274 <p>Type: tag filter expression<br /> 275 Example:</p> 276 <pre><code><filter> 277  278 <tags>| (tag1, tag2, tag3)</tags> 279 </filter></code></pre> 280 </div> 281  282 </body> 283 </html> 284

UNIXworkcode

UNIXwork`code`