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