CASYNC(1)

📦
version 2+20201210 · 10 versions
, in ubuntu stonking

okay bestie, come sit down, we're reading the casync manual together and you're gonna understand all of it, no cap 🫶

✨ NAME ✨

casync — casync Documentation

🌈 SYNOPSIS 🌈

casync [OPTIONS...] make [ARCHIVE | ARCHIVE_INDEX | BLOB_INDEX] [PATH]
casync [OPTIONS...] extract [ARCHIVE | ARCHIVE_INDEX | BLOB_INDEX] [PATH]
casync [OPTIONS...] list [ARCHIVE | ARCHIVE_INDEX | DIRECTORY]
casync [OPTIONS...] mtree [ARCHIVE | ARCHIVE_INDEX | DIRECTORY]
casync [OPTIONS...] stat [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]
casync [OPTIONS...] digest [ARCHIVE | BLOB | ARCHIVE_INDEX | BLOB_INDEX | DIRECTORY]
casync [OPTIONS...] mount [ARCHIVE | ARCHIVE_INDEX] PATH
casync [OPTIONS...] mkdev [BLOB | BLOB_INDEX] [NODE]
casync [OPTIONS...] gc BLOB_INDEX | ARCHIVE_INDEX ...

💅 DESCRIPTION 💅

Content-Addressable Data Synchronization Tool.

That's the whole description, bestie. It's giving minimalist icon. The rest of the page is where the lore lives 💖

🎀 COMMANDS 🎀

🦋 casync make 🦋

casync make [ARCHIVE | ARCHIVE_INDEX] [DIRECTORY]
casync make [BLOB_INDEX] FILE | DEVICE

Okay so this one creates stuff. It'll make either a .catar archive or a .caidx index for the DIRECTORY you hand it, or a .caibx index for the FILE or block DEVICE you hand it.

The type of output? Chosen automatically, based on the file extension — no manual picking needed — but you can override that with --what=. And DIRECTORY is optional, so if you don't specify one, the current directory gets used. slay.

When a .caidx or .caibx file is created, a .castr storage directory gets created too, by default in the same directory, named default.castr — unless you configured it otherwise (see the --store= option, we'll get to her).

Which metadata ends up in the archive is controlled by the --with-* and --without-* options. you're in charge, periodt

🦋 casync extract 🦋

casync extract [ARCHIVE | ARCHIVE_INDEX] [DIRECTORY]
casync extract BLOB_INDEX FILE | DEVICE

This is the reverse of make, the ✨unmake✨. It extracts the contents of a .catar archive or .caidx index into the DIRECTORY you specify, or it puts the contents specified by BLOB_INDEX into the FILE or block DEVICE you specify.

DIRECTORY can be omitted — if you skip it, the current directory is the default. same energy as make, love that for us.

Which metadata gets replayed from the archive is controlled by the --with-* and --without-* options.

🦋 casync list 🦋

casync list [ARCHIVE | ARCHIVE_INDEX | DIRECTORY]

Lists every file and directory inside the .catar archive or .caidx index you point at, or inside the directory. The argument is optional and defaults to the current directory.

The output includes the permission mask and the file names, like:

$ casync list /usr/share/doc/casync
drwxr-xr-x
-rw-r--r-- README.md
-rw-r--r-- TODO

🦋 casync mtree 🦋

casync mtree [ARCHIVE | ARCHIVE_INDEX | DIRECTORY]

Basically list's glow-up cousin — same idea, except it includes info about every entry in the key=value format defined by BSD mtree(5):

$ casync mtree /usr/share/doc/casync
. type=dir mode=0755 uid=0 gid=0 time=1500343585.721189650
README.md type=file mode=0644 size=7286 uid=0 gid=0 time=1498175562.000000000 sha256digest=af75eacac1f00abf6adaa7510a2c7fe00a4636daf9ea910d69d96f0a4ae85df4
TODO type=file mode=0644 size=2395 uid=0 gid=0 time=1498175562.000000000 sha256digest=316f11a03c08ec39f0328ab1f7446bd048507d3fbeafffe7c32fad4942244b7d

🦋 casync stat 🦋

casync stat [ARCHIVE | ARCHIVE_INDEX | DIRECTORY] [PATH]

This one shows you detailed info about a file or directory PATH, as found in either ARCHIVE or ARCHIVE_INDEX, or underneath DIRECTORY. Both arguments are optional — the first defaults to the current directory, and the second defaults to the top-level path (.).

Example output, because seeing it hits different:

$ casync stat .
    File: .
    Mode: drwxrwxr-x
FileAttr: ----------
 FATAttr: ---
  Offset: 0
    Time: 2017-07-17 22:53:30.723304050
    User: zbyszek (1000)
   Group: zbyszek (1000)

🦋 casync digest 🦋

casync digest [ARCHIVE | BLOB | ARCHIVE_INDEX | BLOB_INDEX | DIRECTORY]

Computes and prints the checksum of the argument. The argument is optional and defaults to the current directory:

$ casync digest
d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7

$ casync digest .
d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7

see, same answer, the default is doing exactly what it says 💖

🦋 casync mount 🦋

casync mount [ARCHIVE | ARCHIVE_INDEX] PATH

Mounts the specified .catar archive or .caidx index at the specified PATH, using the FUSE protocol. yes bestie, FUSE. iconic behaviour.

🦋 casync mkdev 🦋

casync mkdev [BLOB | BLOB_INDEX] [NODE]

Creates a block device NODE with the contents specified by the .caibx BLOB_INDEX, or just the file or block device BLOB, using the NBD protocol.

Example time:

$ sudo casync -v mkdev README.md
Attached: /dev/nbd0

and then, in another terminal:

$ sudo head -n1 /dev/nbd0
# casync — Content Addressable Data Synchronizer
⚠️ heads up: when casync mkdev is killed, the device is destroyed. so, like, be aware of that 💀

🦋 casync gc 🦋

casync gc ARCHIVE_INDEX | BLOB_INDEX ...

The garbage collector ✨. This removes all the chunks that aren't used by one of the indices you specify (and yes, you can pass one or more blob and archive indices). If --store isn't given, the default store for the first index gets used.

Use her to prune unused chunks out of a shared chunk store. spring cleaning energy 🧹

💖 OPTIONS 💖

🌸 General options 🌸

  • --help, -h — Show terse help output
  • --version — Show brief version information
  • --log-level=<LEVEL>, -l — Set log level (debug, info, err)
  • --verbose, -v — Show terse status information during runtime
  • --dry-run, -n — Only print what would be removed with gc
  • --store=PATH — The primary chunk store to use
  • --extra-store=<PATH> — Additional chunk store to look for chunks in
  • --chunk-size=<[MIN:]AVG[:MAX]> — The minimal/average/maximum number of bytes in a chunk
  • --digest=<DIGEST> — Pick digest algorithm (sha512-256 or sha256)
  • --compression=<COMPRESSION> — Pick compression algorithm (zstd, xz or gzip)
  • --seed=<PATH> — Additional file or directory to use as seed
  • --cache=<PATH> — Directory to use as encoder cache
  • --cache-auto, -c — Pick encoder cache directory automatically
  • --rate-limit-bps=<LIMIT> — Maximum bandwidth in bytes/s for remote communication
  • --exclude-nodump=no — Don't exclude files with chattr(1)'s +d nodump flag when creating archive
  • --exclude-submounts=yes — Exclude submounts when creating archive
  • --exclude-file=no — Don't respect .caexclude files in the file tree
  • --reflink=no — Don't create reflinks from seeds when extracting
  • --hardlink=yes — Create hardlinks from seeds when extracting
  • --punch-holes=no — Don't create sparse files when extracting
  • --delete=no — Don't delete existing files not listed in archive after extraction
  • --undo-immutable=yes — When removing existing files, undo chattr(1)'s +i 'immutable' flag when extracting
  • --seed-output=no — Don't implicitly add pre-existing output as seed when extracting
  • --recursive=no — List non-recursively
  • --mkdir=no — Don't automatically create mount directory if it is missing
  • --uid-shift=<yes|SHIFT> — Shift UIDs/GIDs
  • --uid-range=<RANGE> — Restrict UIDs/GIDs to range

🌸 Input/output selector 🌸

  • --what=archive — Operate on archive file
  • --what=archive-index — Operate on archive index file
  • --what=blob — Operate on blob file
  • --what=blob-index — Operate on blob index file
  • --what=directory — Operate on directory
  • --what=help — Print a list of allowed values (and terminate the program)

🌸 Turn on archive feature sets 🌸

  • --with=best — Store most accurate information
  • --with=unix — Store UNIX baseline information
  • --with=fat — Store FAT information
  • --with=chattr — Store chattr(1) file attributes
  • --with=fat-attrs — Store FAT file attributes
  • --with=privileged — Store file data that requires privileges to restore
  • --with=fuse — Store file data that can exposed again via 'casync mount'

To turn archive features off, --without=… may be used, such as --without=fat-attrs, --without=privileged, etc. To disable all optional features, --without=all may be used. (The positive form --with=all does not make sense, because some features are conflicting. To enable the maximum set of information, use --with=best.) that's the tea ☕

🌸 Individual archive features 🌸

  • --with=<16bit-uids> — Store reduced 16bit UID/GID information
  • --with=<32bit-uids> — Store full 32bit UID/GID information
  • --with=<user-names> — Store user/group names
  • --with=<sec-time> — Store timestamps in 1s granularity
  • --with=<usec-time> — Store timestamps in 1µs granularity
  • --with=<nsec-time> — Store timestamps in 1ns granularity
  • --with=<2sec-time> — Store timestamps in 2s granularity
  • --with=<read-only> — Store per-file read only flag
  • --with=<permissions> — Store full per-file UNIX permissions
  • --with=<symlinks> — Store symbolic links
  • --with=<device-nodes> — Store block and character device nodes
  • --with=<fifos> — Store named pipe nodes
  • --with=<sockets> — Store AF_UNIX file system socket nodes
  • --with=<flag-hidden> — Store FAT "hidden" file flag
  • --with=<flag-system> — Store FAT "system" file flag
  • --with=<flag-archive> — Store FAT "archive" file flag
  • --with=<flag-append> — Store "append-only" file flag
  • --with=<flag-noatime> — Store "disable access time" file flag
  • --with=<flag-compr> — Store "enable compression" file flag
  • --with=<flag-nocow> — Store "disable copy-on-write" file flag
  • --with=<flag-nodump> — Store "disable dumping" file flag
  • --with=<flag-dirsync> — Store "synchronous" directory flag
  • --with=<flag-immutable> — Store "immutable" file flag
  • --with=<flag-sync> — Store "synchronous" file flag
  • --with=<flag-nocomp> — Store "disable compression" file flag
  • --with=<flag-projinherit> — Store "project quota inheritance" flag
  • --with=<subvolume> — Store btrfs subvolume information
  • --with=<subvolume-ro> — Store btrfs subvolume read-only property
  • --with=<xattrs> — Store extended file attributes
  • --with=<acl> — Store file access control lists
  • --with=<selinux> — Store SElinux file labels
  • --with=<fcaps> — Store file capabilities
  • --with=<quota-projid> — Store ext4/XFS quota project ID

(and similar: --without=16bit-uids, --without=32bit-uids, ...) — so literally every one of these has a mirror-flip --without= twin, iykyk 🪞

🌟 ARCHIVE FEATURES 🌟

So all those --with= and --without= parameters are what control the precise set of metadata that gets stored in the archive — or restored when you're extracting. chef's kiss, very precise, very demure.

💡 but bestie, listen: these flags only apply if casync operates on the file system level. so don't come for them if you're doing blob stuff. 🫶

✨ EXCLUDING FILES AND DIRECTORIES FROM ARCHIVING ✨

okay bestie, listen up, because this part is lowkey the most important vibe check in the whole page 💅 when you're generating an archive or an index from a file system directory tree, some stuff gets yeeted by default and other stuff you can choose to yeet. Here's the full tea:

  1. Virtual API file systems exposed by the kernel get excluded UNCONDITIONALLY, no discussion, no appeal — we're talking procfs, sysfs, cgroupfs, devpts … but NOT tmpfs/devtmpfs, those two are fine and stay. Periodt.
  2. Depending on whether symlinks, device nodes, fifos and sockets are enabled for archiving with --with= and --without=, file nodes of those types get excluded. So like, if you said no to a type, its nodes are not invited to the party 🙅‍♀️
  3. By default, files and directories with the +d chattr(1) flag set are excluded. But you can turn that behaviour off with --exclude-nodump=no if you want them in there. Your call, bestie.
  4. Optionally, files and directories contained in submounts of the specified file system tree get excluded — but only if you specifically ask with --exclude-submounts=yes. Otherwise they're staying. 🫶
  5. By default, anything listed in .caexclude files anywhere in the file hierarchy gets excluded. You can turn interpretation of these files off entirely with --exclude-file=no. These files work kinda like git's .gitignore concept, and here's exactly how they behave:
    • They're read as a text file, where each line is either empty or starts with # (in which case it has no effect at all — that's your commenting mechanism, use it, it's iconic ✨), or it lists a globbing path pattern of files/directories to ignore.
    • If a line contains no / character, the line applies to the directory the .caexclude file is located in as well as all child directories of it. So it's giving "me and my whole bloodline" energy.
    • If it contains at least one / character, it is considered strictly relative to the directory the .caexclude file is located in. No wandering off, it knows exactly where it lives.
    • .caexclude files may appear in any directory of the file system tree that is archived. BUT — they have no effect when placed in directories that are marked for exclusion via .caexclude files placed further up in the directory tree. Like girl, you're already gone, nobody's reading your notes 💀
    • When a line ends in a / character, it applies to directories only, and not regular files or other file node types. Directories-only, we love a specialist 👑
    • If a line is prefixed with a ! character, matching files are excluded from the exclusion — i.e. the effect of other matching lines that are not prefixed like this is cancelled for matching files. So it's a "not me tho" pass. 🎀
    • ! lines unconditionally take precedence over lines not marked like this. Unconditional. No arguments. It ate and left no crumbs.
    • Moreover, lines prefixed with ! also cancel the effect of patterns in .caexclude files placed in directories further up the tree. Yeah, it reaches up. Powerful behaviour fr fr 🌈

and that's the whole page, bestie, we made it 🦋 this was casync, manual section 1, dated Aug 23, 2026 — go forth and archive responsibly, mwah 💖🌸

📦 where this page comes from