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]
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
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 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]
54
55
56       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
60       The output includes the permission mask and file names:
61
62          $ casync list /usr/share/doc/casync
63          drwxr-xr-x
64          -rw-r--r-- README.md
65          -rw-r--r-- TODO
66
67       casync mtree [ARCHIVE | ARCHIVE_INDEX | DIRECTORY]
68
69
70       This is similar to list, but includes information about each  entry  in
71       the key=value format defined by BSD mtree(5):
72
73          $ 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
78       casync stat [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]
79
80
81       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
86       Example output:
87
88          $ 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
98       casync digest [ARCHIVE | BLOB | ARCHIVE_INDEX | BLOB_INDEX | DIRECTORY]
99
100
101       This will compute and print the checksum of the argument.  The argument
102       is optional and defaults to the current directory:
103
104          $ casync digest
105          d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7
106
107          $ casync digest .
108          d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7
109
110       casync mount [ARCHIVE | ARCHIVE_INDEX] PATH
111
112
113       This  will  mount  the  specified .catar archive or .caidx index at the
114       specified PATH, using the FUSE protocol.
115
116       casync mkdev [BLOB | BLOB_INDEX] [NODE]
117
118
119       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
123       Example:
124
125          $ sudo casync -v mkdev README.md
126          Attached: /dev/nbd0
127
128          (in another terminal)
129          $ sudo head -n1 /dev/nbd0
130          # casync — Content Addressable Data Synchronizer
131
132       When casync mkdev is killed, the device is destroyed.
133
134       casync gc ARCHIVE_INDEX | BLOB_INDEX ...
135
136
137       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
141       This command can be used to prune unused chunks  from  a  shared  chunk
142       store.
143

OPTIONS

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

ARCHIVE FEATURES

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

EXCLUDING FILES AND DIRECTORIES FROM ARCHIVING

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
385       optionally be excluded:
386
387       1. Files and directories of virtual API file  systems  exposed  by  the
388          kernel   (i.e.   procfs,   sysfs,  cgroupfs,  devpts  …  —  but  not
389          tmpfs/devtmpfs) are excluded unconditionally.
390
391       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
395       3. By default, files and directories with the +d chattr(1) flag set are
396          excluded,   however   this   behaviour   may   be  turned  off  with
397          --exclude-nodump=no.
398
399       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
403       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
418          directories only, and not regular files or other file node types. If
419          a line is prefixed with a ! character matching  files  are  excluded
420          from the exclusion, i.e. the effect of other matching lines that are
421          not prefixed like this is cancelled  for  matching  files.  !  lines
422          unconditionally  take  precedence  over  lines not marked like this.
423          Moreover, lines prefixed with ! also cancel the effect  of  patterns
424          in .caexclude files placed in directories further up the tree.
425
426
427
428
4291                                Jul 27, 2020                        CASYNC(1)
Impressum