1CASYNC(1) casync CASYNC(1)
2
6 casync - casync Documentation
7
9 casync [OPTIONS...] make [ARCHIVE | ARCHIVE_INDEX | BLOB_INDEX] [PATH]
10 casync [OPTIONS...] extract [ARCHIVE | ARCHIVE_INDEX | BLOB_INDEX] [PATH]
11 casync [OPTIONS...] list [ARCHIVE | ARCHIVE_INDEX | DIRECTORY]
12 casync [OPTIONS...] mtree [ARCHIVE | ARCHIVE_INDEX | DIRECTORY]
13 casync [OPTIONS...] stat [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]
14 casync [OPTIONS...] digest [ARCHIVE | BLOB | ARCHIVE_INDEX | BLOB_INDEX | DIRECTORY]
15 casync [OPTIONS...] mount [ARCHIVE | ARCHIVE_INDEX] PATH
16 casync [OPTIONS...] mkdev [BLOB | BLOB_INDEX] [NODE]
17 casync [OPTIONS...] gc BLOB_INDEX | ARCHIVE_INDEX ...
18
21 Content-Addressable Data Synchronization Tool
22
24 casync make [ARCHIVE | ARCHIVE_INDEX] [DIRECTORY]
25 casync make [BLOB_INDEX] FILE | DEVICE
26 This will create either a .catar archive or an .caidx index for for the
29 given DIRECTORY, or a .caibx index for the given FILE or block DEVICE.
30 The type of output is automatically chosen based on the file extension
31 (this may be overridden with --what=). DIRECTORY is optional, and the
32 current directory will be used if not specified.
33 When a .caidx or .caibx file is created, a .castr storage directory
35 will be created too, by default located in the same directory, and
36 named default.castr unless configured otherwise (see --store= option).
37 The metadata included in the archive is controlled by the --with-* and
39 --without-* options.
40 casync extract [ARCHIVE | ARCHIVE_INDEX] [DIRECTORY]
42 casync extract BLOB_INDEX FILE | DEVICE
43 This will extract the contents of a .catar archive or .caidx index into
46 the specified DIRECTORY, or the contents specified by BLOB_INDEX to the
47 specified FILE or block DEVICE. DIRECTORY may be omitted, and the cur‐
48 rent directory will be used by default.
49 The metadata replayed from the archive is controlled by the --with-*
51 and --without-* options.
52 casync list [ARCHIVE | ARCHIVE_INDEX | DIRECTORY]
54 This will list all the files and directories in the specified .catar
57 archive or .caidx index, or the directory. The argument is optional,
58 and the current directory will be used by default.
59 The output includes the permission mask and file names:
61 $ casync list /usr/share/doc/casync
63 drwxr-xr-x
64 -rw-r--r-- README.md
65 -rw-r--r-- TODO
66 casync mtree [ARCHIVE | ARCHIVE_INDEX | DIRECTORY]
68 This is similar to list, but includes information about each entry in
71 the key=value format defined by BSD mtree(5):
72 $ casync mtree /usr/share/doc/casync
74 . type=dir mode=0755 uid=0 gid=0 time=1500343585.721189650
75 README.md type=file mode=0644 size=7286 uid=0 gid=0 time=1498175562.000000000 sha256digest=af75eacac1f00abf6adaa7510a2c7fe00a4636daf9ea910d69d96f0a4ae85df4
76 TODO type=file mode=0644 size=2395 uid=0 gid=0 time=1498175562.000000000 sha256digest=316f11a03c08ec39f0328ab1f7446bd048507d3fbeafffe7c32fad4942244b7d
77 casync stat [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]
79 This will show detailed information about a file or directory PATH, as
82 found in either ARCHIVE or ARCHIVE_INDEX or underneath DIRECTORY. Both
83 arguments are optional. The first defaults to the current directory,
84 and the second the top-level path (.).
85 Example output:
87 $ casync stat .
89 File: .
90 Mode: drwxrwxr-x
91 FileAttr: ----------
92 FATAttr: ---
93 Offset: 0
94 Time: 2017-07-17 22:53:30.723304050
95 User: zbyszek (1000)
96 Group: zbyszek (1000)
97 casync digest [ARCHIVE | BLOB | ARCHIVE_INDEX | BLOB_INDEX | DIRECTORY]
99 This will compute and print the checksum of the argument. The argument
102 is optional and defaults to the current directory:
103 $ casync digest
105 d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7
106 $ casync digest .
108 d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7
109 casync mount [ARCHIVE | ARCHIVE_INDEX] PATH
111 This will mount the specified .catar archive or .caidx index at the
114 specified PATH, using the FUSE protocol.
115 casync mkdev [BLOB | BLOB_INDEX] [NODE]
117 This will create a block device NODE with the contents specified by the
120 .caibx BLOB_INDEX or just the file or block device BLOB, using the NBD
121 protocol.
122 Example:
124 $ sudo casync -v mkdev README.md
126 Attached: /dev/nbd0
127 (in another terminal)
129 $ sudo head -n1 /dev/nbd0
130 # casync — Content Addressable Data Synchronizer
131 When casync mkdev is killed, the device is destroyed.
133 casync gc ARCHIVE_INDEX | BLOB_INDEX ...
135 This will remove all chunks that are not used by one of the specified
138 indices (one or more blob and archive indices can be given). If --store
139 is not given, the default store for the first index will be used.
140 This command can be used to prune unused chunks from a shared chunk
142 store.
143
145 General options:
146 --help, -h
148 Show terse help output
149 --verbose, -v
151 Show terse status information during runtime
152 --dry-run, -n
154 Only print what would be removed with gc
155 --store=PATH
157 The primary chunk store to use
158 --extra-store=<PATH>
160 Additional chunk store to look for chunks in
161 --chunk-size=<[MIN:]AVG[:MAX]>
163 The minimal/average/maximum number of bytes in a chunk
164 --digest=<DIGEST>
166 Pick digest algorithm (sha512-256 or sha256)
167 --compression=<COMPRESSION>
169 Pick compression algorithm (zstd, xz or gzip)
170 --seed=<PATH>
172 Additional file or directory to use as seed
173 --cache=<PATH>
175 Directory to use as encoder cache
176 --cache-auto, -c
178 Pick encoder cache directory automatically
179 --rate-limit-bps=<LIMIT>
181 Maximum bandwidth in bytes/s for remote communication
182 --exclude-nodump=no
184 Don't exclude files with chattr(1)'s +d nodump flag when creat‐
185 ing archive
186 --exclude-submounts=yes
188 Exclude submounts when creating archive
189 --exclude-file=no
191 Don't respect .caexclude files in the file tree
192 --reflink=no
194 Don't create reflinks from seeds when extracting
195 --hardlink=yes
197 Create hardlinks from seeds when extracting
198 --punch-holes=no
200 Don't create sparse files when extracting
201 --delete=no
203 Don't delete existing files not listed in archive after extrac‐
204 tion
205 --undo-immutable=yes
207 When removing existing files, undo chattr(1)'s +i 'immutable'
208 flag when extracting
209 --seed-output=no
211 Don't implicitly add pre-existing output as seed when extracting
212 --recursive=no
214 List non-recursively
215 --mkdir=no
217 Don't automatically create mount directory if it is missing
218 --uid-shift=<yes|SHIFT>
220 Shift UIDs/GIDs
221 --uid-range=<RANGE>
223 Restrict UIDs/GIDs to range
224 Input/output selector:
226 --what=archive
228 Operate on archive file
229 --what=archive-index
231 Operate on archive index file
232 --what=blob
234 Operate on blob file
235 --what=blob-index
237 Operate on blob index file
238 --what=directory
240 Operate on directory
241 --what=help
243 Print a list of allowed values (and terminate the program)
244 Turn on archive feature sets:
246 --with=best
248 Store most accurate information
249 --with=unix
251 Store UNIX baseline information
252 --with=fat
254 Store FAT information
255 --with=chattr
257 Store chattr(1) file attributes
258 --with=fat-attrs
260 Store FAT file attributes
261 --with=privileged
263 Store file data that requires privileges to restore
264 --with=fuse
266 Store file data that can exposed again via 'casync mount'
267 To turn archive features off, --without=… may be used, such as --with‐
269 out=fat-attrs, --without=privileged, etc. To disable all optional fea‐
270 tures, --without=all may be used. (The positive form --with=all does
271 not make sense, because some features are conflicting. To enable the
272 maximum set of information, use --with=best.)
273 Individual archive features:
275 --with=<16bit-uids>
277 Store reduced 16bit UID/GID information
278 --with=<32bit-uids>
280 Store full 32bit UID/GID information
281 --with=<user-names>
283 Store user/group names
284 --with=<sec-time>
286 Store timestamps in 1s granularity
287 --with=<usec-time>
289 Store timestamps in 1µs granularity
290 --with=<nsec-time>
292 Store timestamps in 1ns granularity
293 --with=<2sec-time>
295 Store timestamps in 2s granularity
296 --with=<read-only>
298 Store per-file read only flag
299 --with=<permissions>
301 Store full per-file UNIX permissions
302 --with=<symlinks>
304 Store symbolic links
305 --with=<device-nodes>
307 Store block and character device nodes
308 --with=<fifos>
310 Store named pipe nodes
311 --with=<sockets>
313 Store AF_UNIX file system socket nodes
314 --with=<flag-hidden>
316 Store FAT "hidden" file flag
317 --with=<flag-system>
319 Store FAT "system" file flag
320 --with=<flag-archive>
322 Store FAT "archive" file flag
323 --with=<flag-append>
325 Store "append-only" file flag
326 --with=<flag-noatime>
328 Store "disable access time" file flag
329 --with=<flag-compr>
331 Store "enable compression" file flag
332 --with=<flag-nocow>
334 Store "disable copy-on-write" file flag
335 --with=<flag-nodump>
337 Store "disable dumping" file flag
338 --with=<flag-dirsync>
340 Store "synchronous" directory flag
341 --with=<flag-immutable>
343 Store "immutable" file flag
344 --with=<flag-sync>
346 Store "synchronous" file flag
347 --with=<flag-nocomp>
349 Store "disable compression" file flag
350 --with=<flag-projinherit>
352 Store "project quota inheritance" flag
353 --with=<subvolume>
355 Store btrfs subvolume information
356 --with=<subvolume-ro>
358 Store btrfs subvolume read-only property
359 --with=<xattrs>
361 Store extended file attributes
362 --with=<acl>
364 Store file access control lists
365 --with=<selinux>
367 Store SElinux file labels
368 --with=<fcaps>
370 Store file capabilities
371 --with=<quota-projid>
373 Store ext4/XFS quota project ID
374 (and similar: --without=16bit-uids, --without=32bit-uids, ...)
376
378 The various --with= and --without= parameters control the precise set
379 of metadata to store in the archive, or restore when extracting. These
380 flags only apply if casync operates on the file system level.
381
383 When generating an archive or index from a file system directory tree,
384 some files and directories are excluded by default and others may op‐
385 tionally be excluded:
386 1. Files and directories of virtual API file systems exposed by the
388 kernel (i.e. procfs, sysfs, cgroupfs, devpts … — but not tmpfs/de‐
389 vtmpfs) are excluded unconditionally.
390 2. Depending on whether symlinks, device nodes, fifos and sockets are
392 enabled for archiving with --with= and --without=, file nodes of
393 these types are excluded.
394 3. By default, files and directories with the +d [22mchattr(1) flag set are
396 excluded, however this behaviour may be turned off with --ex‐
397 clude-nodump=no.
398 4. Optionally, files and directories contained in submounts of the
400 specified file system tree are excluded, if --exclude-submounts=yes
401 is specified.
402 5. By default, any files and directories listed in .caexclude files in
404 the file hierarchy are excluded, however interpretation of these
405 files may be turned off with --exclude-file=no. These files operate
406 similar to git's .gitignore concept: they are read as text file
407 where each line is either empty/starts with # (in which case they
408 have no effect, which may be used for commenting), or list a glob‐
409 bing path pattern of files/directories to ignore. If a line contains
410 no / character the line applies to the directory the .caexclude file
411 is located in as well as all child directories of it. If it contains
412 at least one / character it is considered stricly relative to the
413 directory the .caexclude file is located in. .caexclude files may
414 appear in any directory of the file system tree that is archived,
415 however they have no effect when placed in directories that are
416 marked for exclusion via .caexclude files placed further up in the
417 directory tree. When a line ends in a / character it applies to di‐
418 rectories only, and not regular files or other file node types. If a
419 line is prefixed with a ! character matching files are excluded from
420 the exclusion, i.e. the effect of other matching lines that are not
421 prefixed like this is cancelled for matching files. ! lines uncondi‐
422 tionally take precedence over lines not marked like this. Moreover,
423 lines prefixed with ! also cancel the effect of patterns in .caex‐
424 clude files placed in directories further up the tree.
4251 Jul 21, 2021 CASYNC(1)