.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "CASYNC" "1" "Nov 01, 2022" "1" "casync" .SH NAME casync \- casync Documentation .SH SYNOPSIS .nf \fBcasync\fP [\fIOPTIONS\fP\&...] make [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP | \fIBLOB_INDEX\fP] [\fIPATH\fP] \fBcasync\fP [\fIOPTIONS\fP\&...] extract [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP | \fIBLOB_INDEX\fP] [\fIPATH\fP] \fBcasync\fP [\fIOPTIONS\fP\&...] list [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP | \fIDIRECTORY\fP] [\fIPATH\fP] \fBcasync\fP [\fIOPTIONS\fP\&...] mtree [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP | \fIDIRECTORY\fP] [\fIPATH\fP] \fBcasync\fP [\fIOPTIONS\fP\&...] stat [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP | \fIDIRECTORY\fP] [\fIPATH\fP] \fBcasync\fP [\fIOPTIONS\fP\&...] digest [\fIARCHIVE\fP | \fIBLOB\fP | \fIARCHIVE_INDEX\fP | \fIBLOB_INDEX\fP | \fIDIRECTORY\fP] [PATH] \fBcasync\fP [\fIOPTIONS\fP\&...] mount [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP] \fIPATH\fP \fBcasync\fP [\fIOPTIONS\fP\&...] mkdev [\fIBLOB\fP | \fIBLOB_INDEX\fP] [\fINODE\fP] \fBcasync\fP [\fIOPTIONS\fP\&...] gc \fIBLOB_INDEX\fP | \fIARCHIVE_INDEX\fP ... .fi .sp .SH DESCRIPTION .sp Content\-Addressable Data Synchronization Tool .SH COMMANDS .nf \fBcasync\fP \fBmake\fP [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP] [\fIDIRECTORY\fP] \fBcasync\fP \fBmake\fP [\fIBLOB_INDEX\fP] \fIFILE\fP | \fIDEVICE\fP .fi .sp .sp This will create either a .catar archive or an .caidx index for the given \fIDIRECTORY\fP, or a .caibx index for the given \fIFILE\fP or block \fIDEVICE\fP\&. The type of output is automatically chosen based on the file extension (this may be overridden with \fB\-\-what=\fP). \fIDIRECTORY\fP is optional, and the current directory will be used if not specified. .sp When a .caidx or .caibx file is created, a .castr storage directory will be created too, by default located in the same directory, and named \fBdefault.castr\fP unless configured otherwise (see \fB\-\-store=\fP option). .sp The metadata included in the archive is controlled by the \fB\-\-with\-*\fP and \fB\-\-without\-*\fP options. .nf \fBcasync\fP \fBextract\fP [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP] [\fIDIRECTORY\fP] \fBcasync\fP \fBextract\fP \fIBLOB_INDEX\fP \fIFILE\fP | \fIDEVICE\fP .fi .sp .sp This will extract the contents of a .catar archive or .caidx index into the specified \fIDIRECTORY\fP, or the contents specified by \fIBLOB_INDEX\fP to the specified \fIFILE\fP or block \fIDEVICE\fP\&. \fIDIRECTORY\fP may be omitted, and the current directory will be used by default. .sp The metadata replayed from the archive is controlled by the \fB\-\-with\-*\fP and \fB\-\-without\-*\fP options. .nf \fBcasync\fP \fBlist\fP [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP | \fIDIRECTORY\fP] [\fIPATH\fP] .fi .sp .sp This will list all the files and directories at \fIPATH\fP as found in either \fIARCHIVE\fP or \fIARCHIVE_INDEX\fP or underneath \fIDIRECTORY\fP\&. Both arguments are optional. The first defaults to the current directory. The second defaults to the top\-level path of the archive (\fB/\fP). .sp The output includes the permission mask and file names: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ casync list /usr/share/doc/casync drwxr\-xr\-x \-rw\-r\-\-r\-\- README.md \-rw\-r\-\-r\-\- TODO .ft P .fi .UNINDENT .UNINDENT .nf \fBcasync\fP \fBmtree\fP [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP | \fIDIRECTORY\fP] [\fIPATH\fP] .fi .sp .sp This is similar to \fBlist\fP, but includes information about each entry in the key=value format defined by BSD mtree(5): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ 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 .ft P .fi .UNINDENT .UNINDENT .nf \fBcasync\fP \fBstat\fP [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP | \fIDIRECTORY\fP] [\fIPATH\fP] .fi .sp .sp This will show detailed information about a file or directory \fIPATH\fP, as found in either \fIARCHIVE\fP or \fIARCHIVE_INDEX\fP or underneath \fIDIRECTORY\fP\&. Both arguments are optional. The first defaults to the current directory, and the second the top\-level path (\fB/\fP). .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ casync stat . File: . Mode: drwxrwxr\-x FileAttr: \-\-\-\-\-\-\-\-\-\- FATAttr: \-\-\- Offset: 0 Time: 2017\-07\-17 22:53:30.723304050 User: zbyszek (1000) Group: zbyszek (1000) .ft P .fi .UNINDENT .UNINDENT .nf \fBcasync\fP \fBdigest\fP [\fIBLOB\fP | \fIBLOB_INDEX\fP | \fIDIRECTORY\fP] \fBcasync\fP \fBdigest\fP \fIARCHIVE\fP | \fIARCHIVE_INDEX\fP [PATH] .fi .sp .sp This will compute and print the checksum of the file or directory, or the given \fIPATH\fP as found in either \fIARCHIVE\fP or \fIARCHIVE_INDEX\fP\&. Both arguments are optional. The first default to the current directory. The second defaults to the top\-level path of the archive (\fB/\fP). .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ casync digest d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7 $ casync digest . d1698b0c4c27163284abea5d1e369b92e89dd07cb74378638849800e0406baf7 .ft P .fi .UNINDENT .UNINDENT .nf \fBcasync\fP \fBmount\fP [\fIARCHIVE\fP | \fIARCHIVE_INDEX\fP] \fIPATH\fP .fi .sp .sp This will mount the specified .catar archive or .caidx index at the specified \fIPATH\fP, using the FUSE protocol. .nf \fBcasync\fP \fBmkdev\fP [\fIBLOB\fP | \fIBLOB_INDEX\fP] [\fINODE\fP] .fi .sp .sp This will create a block device \fINODE\fP with the contents specified by the .caibx \fIBLOB_INDEX\fP or just the file or block device \fIBLOB\fP, using the NBD protocol. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo casync \-v mkdev README.md Attached: /dev/nbd0 (in another terminal) $ sudo head \-n1 /dev/nbd0 # casync — Content Addressable Data Synchronizer .ft P .fi .UNINDENT .UNINDENT .sp When \fBcasync mkdev\fP is killed, the device is destroyed. .nf \fBcasync\fP \fBgc\fP \fIARCHIVE_INDEX\fP | \fIBLOB_INDEX\fP ... .fi .sp .sp This will remove all chunks that are not used by one of the specified indices (one or more blob and archive indices can be given). If \fB\-\-store\fP is not given, the default store for the first index will be used. .sp This command can be used to prune unused chunks from a shared chunk store. .SH OPTIONS .sp General options: .INDENT 0.0 .TP .B \-\-help\fP,\fB \-h Show terse help output .TP .B \-\-version Show brief version information .TP .BI \-\-log\-level\fB= \fR,\fB \ \-l Set log level (debug, info, err) .TP .B \-\-verbose\fP,\fB \-v Show terse status information during runtime .TP .B \-\-dry\-run\fP,\fB \-n Only print what would be removed with \fBgc\fP .TP .BI \-\-store\fB= PATH The primary chunk store to use .TP .BI \-\-extra\-store\fB= Additional chunk store to look for chunks in .TP .BI \-\-chunk\-size\fB= <[MIN:]AVG[:MAX]> The minimal/average/maximum number of bytes in a chunk .TP .BI \-\-digest\fB= Pick digest algorithm (sha512\-256 or sha256) .TP .BI \-\-compression\fB= Pick compression algorithm (zstd, xz or gzip) .TP .BI \-\-seed\fB= Additional file or directory to use as seed .TP .BI \-\-cache\fB= Directory to use as encoder cache .TP .B \-\-cache\-auto\fP,\fB \-c Pick encoder cache directory automatically .TP .BI \-\-rate\-limit\-bps\fB= Maximum bandwidth in bytes/s for remote communication .TP .BI \-\-exclude\-nodump\fB= no Don\(aqt exclude files with chattr(1)\(aqs +d \fBnodump\fP flag when creating archive .TP .BI \-\-exclude\-submounts\fB= yes Exclude submounts when creating archive .TP .BI \-\-exclude\-file\fB= no Don\(aqt respect .caexclude files in the file tree .TP .BI \-\-reflink\fB= no Don\(aqt create reflinks from seeds when extracting .TP .BI \-\-hardlink\fB= yes Create hardlinks from seeds when extracting .TP .BI \-\-punch\-holes\fB= no Don\(aqt create sparse files when extracting .TP .BI \-\-delete\fB= no Don\(aqt delete existing files not listed in archive after extraction .TP .BI \-\-undo\-immutable\fB= yes When removing existing files, undo chattr(1)\(aqs +i \(aqimmutable\(aq flag when extracting .TP .BI \-\-seed\-output\fB= no Don\(aqt implicitly add pre\-existing output as seed when extracting .TP .BI \-\-recursive\fB= no List non\-recursively .TP .BI \-\-mkdir\fB= no Don\(aqt automatically create mount directory if it is missing .TP .BI \-\-uid\-shift\fB= Shift UIDs/GIDs .TP .BI \-\-uid\-range\fB= Restrict UIDs/GIDs to range .UNINDENT .sp Input/output selector: .INDENT 0.0 .TP .BI \-\-what\fB= archive Operate on archive file .TP .BI \-\-what\fB= archive\-index Operate on archive index file .TP .BI \-\-what\fB= blob Operate on blob file .TP .BI \-\-what\fB= blob\-index Operate on blob index file .TP .BI \-\-what\fB= directory Operate on directory .TP .BI \-\-what\fB= help Print a list of allowed values (and terminate the program) .UNINDENT .sp Turn on archive feature sets: .INDENT 0.0 .TP .BI \-\-with\fB= best Store most accurate information .TP .BI \-\-with\fB= unix Store UNIX baseline information .TP .BI \-\-with\fB= fat Store FAT information .TP .BI \-\-with\fB= chattr Store chattr(1) file attributes .TP .BI \-\-with\fB= fat\-attrs Store FAT file attributes .TP .BI \-\-with\fB= privileged Store file data that requires privileges to restore .TP .BI \-\-with\fB= fuse Store file data that can exposed again via \(aqcasync mount\(aq .UNINDENT .sp To turn archive features \fIoff\fP, \fB\-\-without=…\fP may be used, such as \fB\-\-without=fat\-attrs\fP, \fB\-\-without=privileged\fP, etc. To disable all optional features, \fB\-\-without=all\fP may be used. (The positive form \fB\-\-with=all\fP does not make sense, because some features are conflicting. To enable the maximum set of information, use \fB\-\-with=best\fP\&.) .sp Individual archive features: .INDENT 0.0 .TP .BI \-\-with\fB= <16bit\-uids> Store reduced 16bit UID/GID information .TP .BI \-\-with\fB= <32bit\-uids> Store full 32bit UID/GID information .TP .BI \-\-with\fB= Store user/group names .TP .BI \-\-with\fB= Store timestamps in 1s granularity .TP .BI \-\-with\fB= Store timestamps in 1µs granularity .TP .BI \-\-with\fB= Store timestamps in 1ns granularity .TP .BI \-\-with\fB= <2sec\-time> Store timestamps in 2s granularity .TP .BI \-\-with\fB= Store per\-file read only flag .TP .BI \-\-with\fB= Store full per\-file UNIX permissions .TP .BI \-\-with\fB= Store symbolic links .TP .BI \-\-with\fB= Store block and character device nodes .TP .BI \-\-with\fB= Store named pipe nodes .TP .BI \-\-with\fB= Store AF_UNIX file system socket nodes .TP .BI \-\-with\fB= Store FAT \(dqhidden\(dq file flag .TP .BI \-\-with\fB= Store FAT \(dqsystem\(dq file flag .TP .BI \-\-with\fB= Store FAT \(dqarchive\(dq file flag .TP .BI \-\-with\fB= Store \(dqappend\-only\(dq file flag .TP .BI \-\-with\fB= Store \(dqdisable access time\(dq file flag .TP .BI \-\-with\fB= Store \(dqenable compression\(dq file flag .TP .BI \-\-with\fB= Store \(dqdisable copy\-on\-write\(dq file flag .TP .BI \-\-with\fB= Store \(dqdisable dumping\(dq file flag .TP .BI \-\-with\fB= Store \(dqsynchronous\(dq directory flag .TP .BI \-\-with\fB= Store \(dqimmutable\(dq file flag .TP .BI \-\-with\fB= Store \(dqsynchronous\(dq file flag .TP .BI \-\-with\fB= Store \(dqdisable compression\(dq file flag .TP .BI \-\-with\fB= Store \(dqproject quota inheritance\(dq flag .TP .BI \-\-with\fB= Store btrfs subvolume information .TP .BI \-\-with\fB= Store btrfs subvolume read\-only property .TP .BI \-\-with\fB= Store extended file attributes .TP .BI \-\-with\fB= Store file access control lists .TP .BI \-\-with\fB= Store SElinux file labels .TP .BI \-\-with\fB= Store file capabilities .TP .BI \-\-with\fB= Store ext4/XFS quota project ID .UNINDENT .sp (and similar: \fB\-\-without=16bit\-uids\fP, \fB\-\-without=32bit\-uids\fP, ...) .SH ARCHIVE FEATURES .sp The various \fB\-\-with=\fP and \fB\-\-without=\fP parameters control the precise set of metadata to store in the archive, or restore when extracting. These flags only apply if \fBcasync\fP operates on the file system level. .SH EXCLUDING FILES AND DIRECTORIES FROM ARCHIVING .sp When generating an archive or index from a file system directory tree, some files and directories are excluded by default and others may optionally be excluded: .INDENT 0.0 .IP 1. 3 Files and directories of virtual API file systems exposed by the kernel (i.e. procfs, sysfs, cgroupfs, devpts … — but not tmpfs/devtmpfs) are excluded unconditionally. .IP 2. 3 Depending on whether symlinks, device nodes, fifos and sockets are enabled for archiving with \fB\-\-with=\fP and \fB\-\-without=\fP, file nodes of these types are excluded. .IP 3. 3 By default, files and directories with the \fB+d\fP chattr(1) flag set are excluded, however this behaviour may be turned off with \fB\-\-exclude\-nodump=no\fP\&. .IP 4. 3 Optionally, files and directories contained in submounts of the specified file system tree are excluded, if \fB\-\-exclude\-submounts=yes\fP is specified. .IP 5. 3 By default, any files and directories listed in \fB\&.caexclude\fP files in the file hierarchy are excluded, however interpretation of these files may be turned off with \fB\-\-exclude\-file=no\fP\&. These files operate similar to \fBgit\fP\(aqs \fB\&.gitignore\fP concept: they are read as text file where each line is either empty/starts with \fB#\fP (in which case they have no effect, which may be used for commenting), or list a globbing path pattern of files/directories to ignore. If a line contains no \fB/\fP character the line applies to the directory the \fB\&.caexclude\fP file is located in as well as all child directories of it. If it contains at least one \fB/\fP character it is considered stricly relative to the directory the \fB\&.caexclude\fP file is located in. \fB\&.caexclude\fP files may appear in any directory of the file system tree that is archived, however they have no effect when placed in directories that are marked for exclusion via \fB\&.caexclude\fP files placed further up in the directory tree. When a line ends in a \fB/\fP character it applies to directories only, and not regular files or other file node types. If a line is prefixed with a \fB!\fP 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. \fB!\fP lines unconditionally take precedence over lines not marked like this. Moreover, lines prefixed with \fB!\fP also cancel the effect of patterns in \fB\&.caexclude\fP files placed in directories further up the tree. .UNINDENT .\" Generated by docutils manpage writer. .