1CASYNC(1)                           casync                           CASYNC(1)
2
3
4

NAME

6       casync - casync Documentation
7

SYNOPSIS

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
19

DESCRIPTION

21       Content-Addressable Data Synchronization Tool
22

COMMANDS

24       casync make [ARCHIVE | ARCHIVE_INDEX] [DIRECTORY]
25       casync make [BLOB_INDEX] FILE | DEVICE
26
27
28       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
34       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
38       The  metadata included in the archive is controlled by the --with-* and
39       --without-* options.
40
41       casync extract [ARCHIVE | ARCHIVE_INDEX] [DIRECTORY]
42       casync extract BLOB_INDEX FILE | DEVICE
43
44
45       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
50       The  metadata  replayed  from the archive is controlled by the --with-*
51       and --without-* options.
52
53       casync list [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]
54
55
56       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
61       The output includes the permission mask and file names:
62
63          $ casync list /usr/share/doc/casync
64          drwxr-xr-x
65          -rw-r--r-- README.md
66          -rw-r--r-- TODO
67
68       casync mtree [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]
69
70
71       This  is  similar to list, but includes information about each entry in
72       the key=value format defined by BSD mtree(5):
73
74          $ 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
79       casync stat [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]
80
81
82       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
87       Example output:
88
89          $ 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
99       casync digest [BLOB | BLOB_INDEX | DIRECTORY]
100       casync digest ARCHIVE | ARCHIVE_INDEX [PATH]
101
102
103       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
108       Example:
109
110          $ casync digest
111          d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7
112
113          $ casync digest .
114          d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7
115
116       casync mount [ARCHIVE | ARCHIVE_INDEX] PATH
117
118
119       This will mount the specified .catar archive or  .caidx  index  at  the
120       specified PATH, using the FUSE protocol.
121
122       casync mkdev [BLOB | BLOB_INDEX] [NODE]
123
124
125       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
129       Example:
130
131          $ sudo casync -v mkdev README.md
132          Attached: /dev/nbd0
133
134          (in another terminal)
135          $ sudo head -n1 /dev/nbd0
136          # casync — Content Addressable Data Synchronizer
137
138       When casync mkdev is killed, the device is destroyed.
139
140       casync gc ARCHIVE_INDEX | BLOB_INDEX ...
141
142
143       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
147       This  command  can  be  used to prune unused chunks from a shared chunk
148       store.
149

OPTIONS

151       General options:
152
153       --help, -h
154              Show terse help output
155
156       --version
157              Show brief version information
158
159       --log-level=<LEVEL>, -l
160              Set log level (debug, info, err)
161
162       --verbose, -v
163              Show terse status information during runtime
164
165       --dry-run, -n
166              Only print what would be removed with gc
167
168       --store=PATH
169              The primary chunk store to use
170
171       --extra-store=<PATH>
172              Additional chunk store to look for chunks in
173
174       --chunk-size=<[MIN:]AVG[:MAX]>
175              The minimal/average/maximum number of bytes in a chunk
176
177       --digest=<DIGEST>
178              Pick digest algorithm (sha512-256 or sha256)
179
180       --compression=<COMPRESSION>
181              Pick compression algorithm (zstd, xz or gzip)
182
183       --seed=<PATH>
184              Additional file or directory to use as seed
185
186       --cache=<PATH>
187              Directory to use as encoder cache
188
189       --cache-auto, -c
190              Pick encoder cache directory automatically
191
192       --rate-limit-bps=<LIMIT>
193              Maximum bandwidth in bytes/s for remote communication
194
195       --exclude-nodump=no
196              Don't exclude files with chattr(1)'s +d nodump flag when  creat‐
197              ing archive
198
199       --exclude-submounts=yes
200              Exclude submounts when creating archive
201
202       --exclude-file=no
203              Don't respect .caexclude files in the file tree
204
205       --reflink=no
206              Don't create reflinks from seeds when extracting
207
208       --hardlink=yes
209              Create hardlinks from seeds when extracting
210
211       --punch-holes=no
212              Don't create sparse files when extracting
213
214       --delete=no
215              Don't  delete existing files not listed in archive after extrac‐
216              tion
217
218       --undo-immutable=yes
219              When removing existing files, undo  chattr(1)'s  +i  'immutable'
220              flag when extracting
221
222       --seed-output=no
223              Don't implicitly add pre-existing output as seed when extracting
224
225       --recursive=no
226              List non-recursively
227
228       --mkdir=no
229              Don't automatically create mount directory if it is missing
230
231       --uid-shift=<yes|SHIFT>
232              Shift UIDs/GIDs
233
234       --uid-range=<RANGE>
235              Restrict UIDs/GIDs to range
236
237       Input/output selector:
238
239       --what=archive
240              Operate on archive file
241
242       --what=archive-index
243              Operate on archive index file
244
245       --what=blob
246              Operate on blob file
247
248       --what=blob-index
249              Operate on blob index file
250
251       --what=directory
252              Operate on directory
253
254       --what=help
255              Print a list of allowed values (and terminate the program)
256
257       Turn on archive feature sets:
258
259       --with=best
260              Store most accurate information
261
262       --with=unix
263              Store UNIX baseline information
264
265       --with=fat
266              Store FAT information
267
268       --with=chattr
269              Store chattr(1) file attributes
270
271       --with=fat-attrs
272              Store FAT file attributes
273
274       --with=privileged
275              Store file data that requires privileges to restore
276
277       --with=fuse
278              Store file data that can exposed again via 'casync mount'
279
280       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
286       Individual archive features:
287
288       --with=<16bit-uids>
289              Store reduced 16bit UID/GID information
290
291       --with=<32bit-uids>
292              Store full 32bit UID/GID information
293
294       --with=<user-names>
295              Store user/group names
296
297       --with=<sec-time>
298              Store timestamps in 1s granularity
299
300       --with=<usec-time>
301              Store timestamps in 1µs granularity
302
303       --with=<nsec-time>
304              Store timestamps in 1ns granularity
305
306       --with=<2sec-time>
307              Store timestamps in 2s granularity
308
309       --with=<read-only>
310              Store per-file read only flag
311
312       --with=<permissions>
313              Store full per-file UNIX permissions
314
315       --with=<symlinks>
316              Store symbolic links
317
318       --with=<device-nodes>
319              Store block and character device nodes
320
321       --with=<fifos>
322              Store named pipe nodes
323
324       --with=<sockets>
325              Store AF_UNIX file system socket nodes
326
327       --with=<flag-hidden>
328              Store FAT "hidden" file flag
329
330       --with=<flag-system>
331              Store FAT "system" file flag
332
333       --with=<flag-archive>
334              Store FAT "archive" file flag
335
336       --with=<flag-append>
337              Store "append-only" file flag
338
339       --with=<flag-noatime>
340              Store "disable access time" file flag
341
342       --with=<flag-compr>
343              Store "enable compression" file flag
344
345       --with=<flag-nocow>
346              Store "disable copy-on-write" file flag
347
348       --with=<flag-nodump>
349              Store "disable dumping" file flag
350
351       --with=<flag-dirsync>
352              Store "synchronous" directory flag
353
354       --with=<flag-immutable>
355              Store "immutable" file flag
356
357       --with=<flag-sync>
358              Store "synchronous" file flag
359
360       --with=<flag-nocomp>
361              Store "disable compression" file flag
362
363       --with=<flag-projinherit>
364              Store "project quota inheritance" flag
365
366       --with=<subvolume>
367              Store btrfs subvolume information
368
369       --with=<subvolume-ro>
370              Store btrfs subvolume read-only property
371
372       --with=<xattrs>
373              Store extended file attributes
374
375       --with=<acl>
376              Store file access control lists
377
378       --with=<selinux>
379              Store SElinux file labels
380
381       --with=<fcaps>
382              Store file capabilities
383
384       --with=<quota-projid>
385              Store ext4/XFS quota project ID
386
387       (and similar: --without=16bit-uids, --without=32bit-uids, ...)
388

ARCHIVE FEATURES

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

EXCLUDING FILES AND DIRECTORIES FROM ARCHIVING

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
399       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
403       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
407       3. By default, files and directories with the +d chattr(1) flag set are
408          excluded, however this  behaviour  may  be  turned  off  with  --ex‐
409          clude-nodump=no.
410
411       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
415       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.
437
438
439
440
4411                                Jul 19, 2023                        CASYNC(1)
Impressum