Technical reference
Architecture, operations, measured numbers and known limits.
The long version. README.md covers installation and everyday use; this file holds the design rationale, the operational details and the packaging notes behind it.
How it works
vault.coffer is a single SQLCipher
(encrypted SQLite) database. Directories and files are rows in that
database; file content is stored in 128 KiB chunks. Mounting is done via
FUSE through the fuser crate, which
is why no root privileges are required: FUSE mounts are owned by, and only
accessible to, the user who created them.
Why this design, and what "auto-grow" means here
The container has no fixed size. SQLite simply extends the backing file
as you write more data into it — there is no --auto-grow flag to set and
no resize step to run, ever. That also means there's no risky "grow the
filesystem live" operation, which is usually where these containers get
corrupted. Optionally cap it with --max-size at creation time if you want
a hard ceiling (e.g. coffer create vault.coffer --max-size 10G); writes
past that are rejected with ENOSPC instead of silently eating your whole
disk.
Why this doesn't destroy your data on a crash
This was the main ask, so it's worth spelling out:
- WAL journaling. The container runs in SQLite's
Write-Ahead Log mode with
synchronous=NORMAL. This is one of the most heavily crash-tested on-disk formats in existence — SQLite ships with a dedicated crash- simulation test suite for exactly this property. Akill -9of the mount process mid-write loses at most the last unflushed write; it does not corrupt the container. This was verified directly while building this tool: 1000+ files were written, the mount process was hard-killed mid-write, andcoffer checkafterwards reported no corruption with every previously-written file byte-for-byte intact. - Per-page HMAC integrity. SQLCipher attaches an HMAC to every 4 KiB
page.
coffer check <file>runsPRAGMA cipher_integrity_check(catches tampering/bit-rot at the encryption layer) andPRAGMA integrity_check(catches structural corruption) without modifying anything. Note: SQLCipher itself has a confirmed upstream bug wherecipher_integrity_checkmisreports every page past the 4GB mark as HMAC-failed on containers larger than that (reproduced independently of this project, across two separate SQLCipher builds - not something we can fix here).coffer checkdetects this specific false-positive pattern and treatsintegrity_check(which actually decrypts and verifies every page) as authoritative, so it won't cry wolf on a large, healthy container - while still correctly failing on real corruption anywhere in the file. - Live, consistent backups.
coffer backup <file> <dest>uses SQLite's online backup API to make a byte-consistent copy — safe to run even while the container is mounted and being written to. (With exclusive locking, the default on NFS, the running mount makes the copy itself - see Locking on network filesystems.) On a terminal it shows a plain progress bar on stderr; from cron it stays quiet. Cheap insurance; consider cronning it. - Wrong password fails loudly. SQLCipher refuses to open the database at all if the passphrase is wrong (HMAC check on page 1 fails immediately) rather than silently returning garbage.
Encryption
SQLCipher defaults: AES-256-CBC per page + HMAC-SHA512, key derived from
your password with PBKDF2. This is solid, standard, "not the point of the
project" encryption — nobody had to hand-roll a cipher for this to work
well. Change the password any time with coffer passwd <file>.
Handling many files
File and directory metadata live in two indexed SQLite tables: one row
per inode, and one row per name in dentries (primary key
(parent, name), plus an index on the inode it points at), so lookups
and readdir stay fast regardless of how many files are inside. Reading/listing was never
the bottleneck at any scale tested (find -type f | wc -l over 95,000 files
takes well under a second - readdir() reports a real file type per entry,
so tools like find don't need an extra syscall per file just to answer
-type f).
See Performance at scale below for the full write-throughput benchmark.
Extended attributes
Extended attributes (user.*, security.*, whatever a tool sets) are
stored per inode in their own table, xattrs, with the same limits Linux
itself applies (255-byte names, 64 KiB values, E2BIG/ERANGE beyond
that) and the same XATTR_CREATE/XATTR_REPLACE semantics as
setxattr(2). They follow the inode through renames, are deleted with
it, and travel with cp --preserve=xattr, rsync -X and coffer backup.
The table is an additive extra, not a schema version bump: a writable open
creates it when missing (CREATE TABLE IF NOT EXISTS), and a version of
coffer from before 0.1.3 never looks at it - it only reads meta,
inodes and data - so containers keep opening in both directions. A
trigger created alongside the table (xattrs_gc, after delete on
inodes) drops an inode's attributes whenever its row goes, and since the
trigger lives in the database it also fires for an older coffer that
unlinks the file, so no orphan rows are left behind either way. Since
format 2 that cross-version path is gone: a container predating the table
is format 1, and a read-only mount of one is refused outright, so
CofferFS only ever runs against a container that has the table. Names
must be valid UTF-8, like file names in a container.
One consequence of answering getxattr at all: the kernel would then ask
for security.capability before every buffered write, to know whether
file capabilities must be dropped - an extra round trip per write(2),
serialised on the single FUSE thread. coffer therefore negotiates
FUSE_HANDLE_KILLPRIV_V2 (Linux 5.11+) and takes the job over, which
means doing all of it: a write, a truncate or a chown drops the setuid
bit and the security.capability attribute, and the setgid bit as well
if the file is group-executable - without that bit S_ISGID marks
mandatory locking rather than a privilege, and Linux leaves it alone.
Truncates by a caller with CAP_FSETID (root stands in for it here) keep
the bits, as they do on any other filesystem, and a chmod in the same
request always wins over the drop. For writes the kernel says when;
fuser surfaces no such flag for truncate and chown, so coffer applies
the rule itself. Older kernels refuse the capability and keep the round
trip.
Hard links
A file can have several names. The name-to-inode mapping lives in its own
table, dentries, instead of being a column on the inode, so link(2)
is just another row and unlink(2) removes the inode only once its last
name is gone. stat reports the real link count, find -samefile finds
every name, cp -l and rsync -aH round-trip, and a write or a chmod
through one name is visible through all of them, because there is only
one inode. Directories keep reporting nlink 2 and link(2) on one is
EPERM, as on any Linux filesystem.
This is the one change so far that could not be made additive, so it
bumps the container format from 1 to 2. Format 1 kept parent and name
on the inode row itself, where a second name has nowhere to go. The first
writable open of a format-1 container therefore migrates it: one
transaction creates dentries, fills it from the existing rows, rewrites
inodes without the two columns, and sets meta.schema_version to 2. A
line on stderr says it is happening. The file content is not touched -
only the inode table is rebuilt, so the cost scales with the number of
files, not with how much data they hold. Two details are easy to get
wrong and both are deliberate: the inode numbers are copied explicitly
and the AUTOINCREMENT high-water mark is carried over before the old
table is dropped (copying the surviving rows alone would lower it in any
container whose newest file had since been deleted, and the next file
would be handed a number already used), and the xattrs table is
recreated afterwards because dropping the old inodes table takes the
xattrs_gc trigger with it.
It is not only mount that does this. Every writable open migrates, so
coffer passwd and coffer compact upgrade a container too - which is
why the refused read-only mount names compact as an alternative. Only
info, check and backup open read-only and leave a format-1
container exactly as it was.
The migration is one-way, which is the honest part of the trade: coffer
0.1.x compares meta.schema_version and refuses a format-2 container
with "container format version 2, this coffer understands version 1 -
upgrade coffer", so an older binary cannot misread the new layout. What
still works with a format-1 container is everything that does not need to
write: info, check and backup. A read-only mount is refused with a
message naming the way out (mount it writable once), rather than failing
somewhere deeper down where the reason would be unclear. coffer backup
before the first writable mount is the way back, if a container has to
stay readable by an older installation. The integration suite covers all
of this against the 0.1.3 release - the last one on format 1, and the
upgrade real installations will do: the upgrade keeps file contents,
nested directories, symlinks and the extended attributes that the older
binary wrote (which is the sharp end of it, since rebuilding the inodes
table drops the xattrs_gc trigger and it has to come back), hard links
work on the upgraded container, and the old binary refuses it afterwards.
Permission enforcement
The mode, owner and group of everything inside a container are stored and
reported faithfully, so ls -l and tools that inspect permissions (ssh
refusing a world-readable key, say) behave normally. What does not
happen by default is the check: a file with mode 000 still opens,
because nothing between the caller and the data applies the Unix rules.
coffer mount --enforce-permissions (registry key
enforce_permissions, also settable at create --save and add time)
adds FUSE's default_permissions mount option. The kernel then applies
the ordinary rules to exactly what coffer reports - sticky bits and
supplementary groups included, which is why this belongs in the kernel
rather than in a hand-written access().
It is off by default on purpose, and the reason is not performance:
- Foreign owners. Files put into a container by a root-run
rsync -afrom a system backup belong to uid 0, 33 and so on. Without enforcement you read them; with it you cannot, andchown-ing them back needs privileges you do not have inside the container either. - A different user id. The root inode carries the uid of whoever ran
create, with mode0700. Mount the same container on a second machine where you are uid 501 instead of 1000 - or off a USB stick - and enforcement refuses the root directory itself.
Neither case is a bug; both are what Unix permissions mean. They are just not what someone moving a personal container between machines expects, so the setting is opt-in. It changes nothing about secrecy: the container is a single-user thing, anyone with the password can mount it under their own id, and root is exempt from the check anyway. To get past a stored setting, mount by path rather than by alias - that path never reads the registry.
renameat2 flags
rename(2) replaces an existing target, but renameat2(2) lets the
caller ask for something else, and a filesystem that ignores those flags
quietly destroys data. RENAME_NOREPLACE - what mv -n uses - is
answered with EEXIST when the target exists. RENAME_EXCHANGE (an
atomic swap) and RENAME_WHITEOUT are not implemented and are refused
with EINVAL rather than silently doing something else. A directory can
only be replaced while it is empty (ENOTEMPTY); the kernel rules out
directory-over-file and file-over-directory itself, but leaves that one
to the filesystem, and getting it wrong orphans the target's whole
subtree inside the container.
Registered vaults (~/.coffer/config)
Typing the container path and the mountpoint on every mount gets old fast,
so coffer keeps a small per-user registry of file/mountpoint pairs, each
under an alias. Register a vault in whichever way fits the moment:
coffer add work ~/.coffer/work.coffer ~/vault # register without mounting
coffer mount ~/.coffer/work.coffer ~/vault --save work # register while mounting
coffer create ~/.coffer/work.coffer --save work --mountpoint ~/vault # register while creating
From then on the alias stands in for the file (and, for mount/umount,
the mountpoint too):
coffer mount work
coffer umount work
coffer info work # same for check, backup, passwd, compact
And with no argument at all, coffer mount and coffer umount do the
obvious thing: if exactly one vault is registered, mount mounts it; if
exactly one registered vault is currently mounted, umount unmounts it.
With several to choose from you get a numbered menu - alias, mountpoint,
file, size on disk, last modified, and whether it's mounted right now -
and type the number (or the alias). If there's no terminal to ask on (a
script, a cron job), that's an error telling you to name the alias instead,
never a guess.
coffer list prints the same table without asking anything, and coffer
remove work forgets an alias without touching the container file. Options
given to coffer add or alongside --save (--idle-timeout,
--compact-on-idle, --password-file) are stored with the entry and become
that alias's defaults, so coffer mount work can mean "mount it and
auto-unmount after 30 idle minutes" without repeating the flag - anything
passed on the command line still wins over the stored value.
The file itself is deliberately plain - one section per vault, the section
name being the alias - and safe to edit by hand: comments on their own line
survive coffer add/remove, and a leading ~ in a path means $HOME.
[work]
file = /home/me/.coffer/work.coffer
mountpoint = /home/me/vault
idle_timeout = 30m
[photos]
file = /data/photos.coffer
mountpoint = /media/photos
Two rules keep this predictable. An alias is a bare word (letters, digits,
-, _, ., no leading . or -), so an argument containing a / or
starting with . or ~ is always a path, never looked up - ./work means
the file even if an alias work exists. And a bare word that matches a
registered alias is the alias; if it matches nothing, it's tried as a path.
coffer add refuses a container file that doesn't exist (a typo should fail
right there, not at the next mount), stores both paths absolute, and
rewrites the file atomically with mode 0600 (a freshly created
~/.coffer gets 0700), since entries can name password files. A
different location can be pointed at with $COFFER_CONFIG. A broken
registry never gets in the way of the classic path-based forms: coffer
mount <file> <mountpoint> and coffer umount <mountpoint> don't read it.
NFS home directories
If $HOME is NFS-mounted with root_squash (common on shared workstations
and clusters), unmounting a container whose mountpoint lives under your home
directory can fail even though you're the one who mounted it: fusermount3's
setuid-root helper briefly runs as effective root to call umount2(), NFS
maps that squashed root down to nobody, and FUSE's owner check then
rejects it. (This is different from a plain "device or resource busy" -
coffer umount already retries those automatically with a lazy unmount, no
sudo needed; see Design notes below.) coffer umount prints a
sudo umount <path> fallback when the root_squash case above happens, but
it's simplest to just avoid the situation: create and mount the
container on a local, non-NFS filesystem instead, e.g. under /tmp, and
symlink it back into your home directory for convenience:
mkdir -p /tmp/vault/dev
coffer create /tmp/vault/dev/vault.coffer
coffer mount /tmp/vault/dev/vault.coffer /tmp/vault/dev/mnt
ln -sT /tmp/vault/dev ~/dev
~/dev now transparently resolves to the local working copy, but the
container and its mountpoint never touch NFS, so unmounting works normally
without sudo. Keep in mind /tmp is typically cleared on reboot, so if the
container itself (not just the mountpoint) needs to survive a reboot, put it
somewhere local but persistent instead.
Locking on network filesystems
SQLite normally takes and releases its fcntl() locks around every
transaction, and every FUSE call is at least one transaction. On a local
disk that's a few syscalls. On NFS each lock and unlock is a round trip to
the server, and the Linux client also drops its page cache for the file
whenever it takes a lock - so the next read goes to the server as well.
That cost stays hidden for a while: right after mount, the NFS server
usually grants the open file a delegation, and while it holds one the
client handles locks locally and keeps its cache. Once the server recalls
the delegation (measured: hours into a mount, overnight, with nobody
touching the file) every FUSE call costs four round trips, and the mount
stays that slow until it's remounted and gets a fresh delegation. On the
machine this was diagnosed on, git status in a small repository went from
0.03 s to 1.3 s; /proc/self/mountstats showed ~270 LOCK, LOCKU, GETATTR
and READ calls per git status.
So on a network filesystem coffer mount holds its locks for the whole
mount instead (--locking, registry key locking):
auto(default) - exclusive when the container is on NFS, SMB/CIFS, Ceph, 9p, AFS, GFS2, OCFS2, Lustre or a FUSE filesystem such as sshfs; normal everywhere else.exclusive- always. SQLite'slocking_mode=EXCLUSIVE, set before the first access, so the WAL index lives in the daemon's memory rather than an mmap()ed-shmfile: no locking left per operation at all.normal- SQLite's usual per-transaction locking, even on NFS.
What changes with exclusive locking: nothing else can open the container
while it's mounted. coffer backup then goes through the mount daemon,
which listens on a socket in /run/user/UID/coffer/ (or
/tmp/coffer-UID/) that only its owner can reach, checks the password
against the container, and copies 4 MiB at a time so the mount keeps
working during the backup, reporting its progress back after each step
(a client that hangs up, say on Ctrl+C, stops the copy). That socket is local, so the backup has to run
on the machine where the container is mounted; from any other host it is
refused like every other open (a backup across hosts was never safe
anyway - SQLite's WAL doesn't work across machines). coffer check and
coffer info say the container is mounted and ask for an unmount.
Read-only mounts always use normal locking (an exclusive WAL connection
needs a write lock, which a read-only file descriptor can't take).
Two details the implementation has to get right, both because fcntl()
locks belong to a process, not a file descriptor: the daemon's connection,
exclusive or not, is opened only after mount has daemonized (the
parent's locks would not survive the fork - with normal locking the one
lost would be the shared lock on the -shm file, and the next info,
check or backup would reset the WAL index under the running mount),
and the daemon never opens the container file a second
time (closing any descriptor for a file drops all the process's locks
on it - the password check reads page 1 through SQLite's own descriptor).
Auto-unmount on idle
coffer mount --idle-timeout 30m (accepts s/m/h/d suffixes, e.g.
45s, 2h) unmounts the container itself after it's seen no filesystem
activity for that long - no separate daemon, cron job, or systemd timer
needed. This is tracked inside the FUSE process: every handled call
(open, read, write, readdir, ...) refreshes a last-activity timestamp, and
a background thread in the same process polls it and shells out to
fusermount3 -u once the idle threshold is crossed. Since it's the mount's
own owner unmounting it, this doesn't hit the NFS/root_squash wrinkle
described above.
Off by default - pass --idle-timeout explicitly to opt in. Note that
any filesystem call counts as activity, including ones triggered by
something other than you directly (a backup tool or file indexer
periodically scanning the mount will keep resetting the timer).
Reclaiming disk space
Deleting files inside a container frees their rows in the underlying
SQLite database, but the .coffer file itself doesn't shrink on its own -
SQLite just adds that freed space to an internal free-list and reuses it
for future writes. That's normal SQLite behavior, not a bug, but it means
the file on disk can stay much bigger than what's actually inside it after
deleting something large (an old backup, a big video, a subtree you
cleaned up).
coffer info shows both numbers so you can tell if it's worth doing:
On-disk size: 14000000000 bytes
Logical data used: 2000000000 bytes
A big gap there is what coffer compact <file> (a VACUUM) reclaims, by
rewriting the file without the freed space. You'd generally only reach for
this after a large deletion, not as routine maintenance - day-to-day
writes reuse that freed space automatically, so compacting a container
that's just been growing steadily has nothing to gain. It needs up to
roughly twice the container's current size in free disk space while it
runs: VACUUM builds the compacted copy in a temporary database, which
coffer places next to the container (not in /tmp, which is often a
RAM-backed tmpfs, and not in memory - SQLite's bundled default would keep
it there, so a 10 GB container would have needed 10 GB of RAM). That
temporary copy is encrypted with the container's own key; SQLCipher keys
every database attached without an explicit key with the main database's
key, and that is exactly how VACUUM attaches it. compact refuses to
run against a mounted container - same reasoning as passwd, see
Design notes below.
If you'd rather not think about it at all, coffer mount --compact-on-idle
1h does this automatically while mounted: once the mount has been idle
that long, it checks for a meaningful gap (at least 64MB and at least
10% of the file) and only then runs VACUUM - most idle periods have
nothing worth reclaiming, so it stays a no-op most of the time rather than
rewriting the file on every idle tick. It keeps running afterward (unlike
--idle-timeout, which unmounts and stops), so a later deletion can be
reclaimed on a future idle period too. One real caveat, and it's bigger
than it sounds: fuser dispatches FUSE requests from a single thread by
default, so a VACUUM mid-run doesn't just block the next write - it
blocks everything (ls, stat, opening a file, all of it) for as long
as it takes, on a large container potentially minutes. It re-checks
right before starting that the mount is still idle (in case activity
resumed in the moment between deciding to compact and actually acquiring
the lock), which narrows but can't fully close that window. If that
tradeoff doesn't sit right for a container you use interactively, prefer
running coffer compact yourself while you're not using the mount instead
of --compact-on-idle.
Design notes
- Inode numbers are
AUTOINCREMENT(never reused), avoiding a FUSE inode-reuse hazard. - Every mutating FUSE call (write, mkdir, rename, ...) is wrapped in one explicit SQLite transaction and committed once, so a single filesystem operation is always all-or-nothing.
mountdaemonizes by default (returns control to the shell immediately); pass--foregroundto keep it attached for debugging.umount(and the idle-timeout watcher) automatically retries a failed unmount with a lazy unmount (fusermount3 -u -z) before giving up - this is what resolves the common "device or resource busy" case (e.g. a crashed mount daemon the kernel hasn't finished tearing down yet), entirely within the mounting user's own permissions, no sudo involved. The plain attempt's own error output is suppressed so a routine escalation doesn't look like a failure; only a genuine final failure prints anything.- A lazy unmount alone only detaches the mountpoint; the mount daemon
keeps running until the last process referencing the mount lets go - and
that can be never: a mountpoint under
/tmpis visible to everyone, and another user's desktop session (gvfs, file indexers) will happily hold a watch on it for days. Meanwhile the daemon still holds the container's exclusive lock, which on an NFS home is visible on every host - socoffer mountelsewhere fails with "already in use" althoughumountreported success. So after a lazy detach of one of its own mounts,umountalso aborts the FUSE connection (/sys/fs/fuse/connections/<id>/abort, owned by the mounting user): the daemon's request loop ends exactly as on a normal unmount, it exits cleanly and the lock is released immediately; whatever still had the mount open gets I/O errors. It prints one line saying so. The connection id is taken from/proc/self/mountinfobefore detaching - deliberately not viastat(), which on a FUSE mountpoint is itself a FUSE request and hangs if the daemon is wedged. - Every
cofferprocess marks itself non-dumpable (PR_SET_DUMPABLE): no core dumps, and noptracefrom other processes of the same user, so another program running under your account cannot read the password or the derived key out of a running mount. Root still can - a mounted container is plaintext to root by definition. Every buffer that holds a password is zeroed when it is dropped, so it does not linger in freed heap memory. Neither helps against a key that has been swapped out; encrypted swap is the system's job. - Password prompts mask input on a real terminal; if stdin isn't a TTY
(piping, scripting), it falls back to a visible plain-text read. Every
command that takes a password also accepts
--password-file <path>as an explicit alternative - mainly so the password never has to appear as a process argument or get piped through aprintf/echothat's briefly visible inps. A world/group-readable password file prints a warning (not a hard failure). mount,passwd, andcompacttake an exclusiveflock()on the container file before doing anything else, so two of them can never run against the same container at once - the actual risk this project cares about (two live writers).check,backup, andinfodeliberately don't lock: WAL mode already gives them a safe, consistent view alongside an active writer, whichbackupin particular depends on. (A mount with exclusive locking - see Locking on network filesystems - keeps them out instead;backupthen goes through the mount.) The lock is released by the kernel the instant every fd on it closes - including on a crash orkill -9- so unlike a PID file there's no stale-lock case to clean up; verified by killing a mount mid-session and confirmingpasswdcould immediately acquire the lock right after.mountacquires this lock before it even opens the database (not just before daemonizing) - otherwise a concurrentpasswdcould rekey the container in the window betweenmountopening its connection and taking the lock, leavingmountserving with a stale key against a file now encrypted under a different one. This lock is only ever as reliable asflock()is on whatever filesystem the container lives on - solid locally, but historically inconsistent over NFS depending on version/lockd config, so don't rely on it as a hard guarantee for a container shared over NFS from multiple machines.- Rust was chosen over C for the compiler's memory safety (removes an
entire class of leak/use-after-free/buffer-overflow bugs in the block-
storage code - not a risk worth taking for a tool whose whole point is
not corrupting your data), while
fuserandrusqlitegive ergonomic, well-maintained bindings for FUSE and SQLCipher respectively.
Verified while building this
Created a container, mounted it as a non-root user, wrote 1000 small files
plus a 20MB file (checksum-verified), unmounted and remounted to confirm
persistence, rejected a wrong password, ran check/backup/passwd
successfully, and hard-kill -9'd the mount process mid-write — the
container stayed structurally intact (check clean) with every
previously-written byte recoverable afterward.
Performance at scale (95,000 files, ~12GB)
Benchmarked end to end at a realistic scale (95,000 files, mixed sizes averaging ~126KB, ~12GB total) against a plain ext4 baseline for context:
| population (write) | find -type f \| wc -l |
|
|---|---|---|
| ext4 (baseline) | 23.6s (4027 files/s, 509MB/s) | 0.05s |
| Rust (before tuning) | 463.5s (205 files/s, 26MB/s) | 0.94s |
| Rust (tuned) | 365.3s (260 files/s, 33MB/s) | 0.94s |
Reading/listing was never the bottleneck at any scale tested. fuser
(this project's FUSE binding) negotiates a large max_write by default, so
large writes never get chunked into many small FUSE calls in the first
place. One real issue turned up while chasing write throughput at this
scale, since fixed: every FUSE call was re-parsing its SQL. src/fs.rs now
uses Connection::prepare_cached throughout instead of execute/prepare,
and PRAGMA cache_size is raised from SQLite's ~2MB default to 128MB
(SQLCipher has to re-decrypt+HMAC-verify a page every time it's evicted
from cache and re-read, so a bigger cache means less redundant crypto work
as the container grows). Together these cut the full 95,000-file/12GB run
from 463s to 365s (~27% faster).
Benchmark runs must be isolated to get repeatable numbers - run one mount at a time on an otherwise idle machine.
Known upstream SQLCipher bug (not ours, but worth knowing about)
While verifying integrity on the 12GB benchmark container, coffer check
reported hundreds of thousands of "corrupt" pages, all starting at exactly
page 1,048,577 - which, at 4096 bytes/page, is precisely the 4GB mark
(2^32 bytes). That's too precise to be real corruption, so it was run down:
- Reproduced with a 30-line program using nothing but
rusqlite+ SQLCipher - no FUSE, no coffer schema, just a table with a BLOB column, written to past 4GB and integrity-checked. Same failure, same exact page. - Reproduced identically across two independent SQLCipher builds:
Ubuntu's
libsqlcipher-devpackage, and a from-source build viabundled-sqlcipher-vendored-openssl. Both fail at the exact same page number. - Meanwhile
PRAGMA integrity_check- which actually walks and decrypts every page to verify the B-tree structure, rather than just recomputing HMACs - reportedokevery time. Files written well past the 4GB mark (including the very last file in a 12GB container) read back with correct, repeatable checksums.
Conclusion: PRAGMA cipher_integrity_check has a real bug in its own page-
iteration logic for databases past 4GB, independent of this project. The
data itself is fine. coffer check detects this specific pattern - a page
number past the 4GB boundary flagged by cipher_integrity_check while
integrity_check passes cleanly - and reports the container as healthy
with an explanatory note, while still failing loudly on genuine corruption
anywhere in the file (verified with a deliberate single-byte flip in a
small container: still caught, still exits non-zero).
Root cause and status: a 32-bit overflow in sqlcipher_codec_ctx_integrity_
check()'s page-offset calculation (src/crypto.c), which wraps exactly at
page 1,048,577 (4096-byte pages) - reported upstream as
sqlcipher/sqlcipher#604.
Confirmed by the maintainer as already fixed in SQLCipher 4.17.0. This
project vendors SQLCipher through rusqlite's
bundled-sqlcipher-vendored-openssl feature (libsqlite3-sys), which as
of writing still bundles 4.14.0 (predates the fix), so coffer check's
workaround above remains necessary until that crate updates its vendored
copy.
Known limitations (honest scope)
- Single mounter at a time. The FUSE loop is intentionally
single-threaded to keep the SQLite access pattern simple and correct.
Mounting (or running
passwd/compactagainst) an already-in-use container is rejected outright with a clear error - see the locking bullet in Design notes - rather than silently racing two writers. - Exclusive locking keeps everything else out. While a mount holds
its locks (
--locking, the default on network filesystems),checkandinfoneed an unmount, andbackupworks only on the machine the container is mounted on - see Locking on network filesystems. - No
default_permissionsenforcement. Whoever can supply the password gets full read/write access to everything inside; Unix permission bits are stored and reported but, unless--enforce-permissionsis given, not enforced. This matches the personal-container use case (VeraCrypt-style), not a multi-user shared filesystem. - Large files are fine, but not optimized for huge ones. Reads/writes go through per-128KiB-block SQL statements. Great for documents, photos, typical file collections; you would want a different design (e.g. a dedicated blob store) if you're routinely storing many multi-GB files.
- The hard-link format bump is one-way. Upgrading a container to
format 2 (see Hard links) is done in place on the first writable
mount and cannot be undone; coffer 0.1.x then refuses it. Take a
coffer backupfirst if an older installation still has to open it. - Deleted space isn't reclaimed automatically. See Reclaiming disk
space above -
coffer compacthandles this, but it's an occasional, manual step, not something that happens on its own. cipher_integrity_checkfalse positives past 4GB. See above -coffer checkalready works around this, but be aware if you ever run the rawPRAGMA cipher_integrity_checkyourself against a large container.
Packaging
Every package is built twice, for amd64/x86_64 and for arm64/aarch64. The release workflow runs the arm64 builds on GitHub's hosted ARM runners inside the arm64 variants of the same multi-arch container images, so nothing is cross-compiled or emulated and each arm64 package is verified exactly like its amd64 twin. The Debian arm64 packages are what Raspberry Pi OS (64-bit) installs. 32-bit ARM (armhf, for Pi Zero/1/2) is not built: it would need QEMU emulation in CI and the audience is small. The local scripts below build whatever architecture the host has.
packaging/build-deb.sh builds one .deb per target distro, each
natively inside that distro's own container, via
cargo-deb. Output goes to
dist/coffer_<version>_<debian12|debian13|ubuntu2404|ubuntu2604>_amd64.deb.
Every package also installs the coffer(1) man page
(packaging/coffer.1, gzipped by make man before cargo deb runs - see
the Makefile) to /usr/share/man/man1/.
packaging/build-deb.sh # -> dist/coffer_*_<id>_amd64.deb (all 4)
packaging/build-rpm.sh # -> dist/coffer-*-1.<dist>.x86_64.rpm (all 6, see below)
packaging/test-install.sh # installs each into a matching fresh
# container and runs a full create/mount/
# write/read/umount/check cycle
RPM targets (packaging/build-rpm.sh, via
cargo-generate-rpm)
follow the exact same per-distro pattern: Fedora 43 and 44, Enterprise
Linux 9 and 10 (built on AlmaLinux, binary-compatible with RHEL, Rocky and
Oracle), openSUSE Leap 16.0 and Tumbleweed. The distro id lands in the RPM
Release field (coffer-0.1.0-1.fedora44.x86_64.rpm), so the RPMs follow
the same spelled-out naming as the .deb files without a rename step -
RPM naming puts the Release field into the file name itself. el9/el10
is the one abbreviation kept, since those packages serve RHEL, AlmaLinux,
Rocky and Oracle alike. Tumbleweed being a rolling release, its RPM matches
Tumbleweed as of the build - the rolling latest prerelease (rebuilt on
every push to main) is the one to use there. The RPMs are not GPG-signed,
which dnf accepts for local files as is and zypper needs
--allow-unsigned-rpm for.
Runtime dependencies. Exactly two: the C library, and the fuse3
package for the fusermount3 helper binary that mount/umount shell
out to. fusermount3 is easy to miss since ldd only reports linked
libraries, not subprocesses - test-install.sh caught it by actually
exercising mount/umount rather than just checking that the install
succeeded. The .deb gets it from the explicit depends in Cargo.toml,
the RPMs from the explicit requires there; the C library dependency is
discovered automatically at build time by both.
There is deliberately no libfuse dependency. fuser is used with its
default, pure-Rust mount, which talks to fusermount3 directly and links
no libfuse3.so. The first releases were built with fuser's libfuse3
feature instead, and that turned out to be the one runtime library that
differs between the target distros: Debian 12, Ubuntu 24.04, EL9/EL10 and
Fedora 43 ship libfuse 3.10-3.16 as SONAME 3 (libfuse3-3), while Debian
13, Ubuntu 26.04, Fedora 44 and Tumbleweed have 3.17+ as SONAME 4
(libfuse3-4, with no libfuse3.so.3 compatibility symlink), and a binary
linked against one cannot load the other - test-install.sh caught a
Debian-12-built package whose Depends: libfuse3-3 wasn't even resolvable
on Debian 13. It also printed a spurious fuse: warning: library too old,
some operations may not work on every SONAME-3 distro, because fuser
hands fuse_session_new() an ops struct sized for libfuse 3.17. Dropping
the feature removed both problems at once.
Why still one package per distro. With libfuse gone, a package built
on the oldest target would in principle install everywhere (glibc is
forward-compatible; libc6 (>= 2.34) from a Debian 12 build is satisfied
by all newer targets). Building natively per distro is kept anyway: it
costs nothing but CI minutes, every package is verified on exactly the
distro it is meant for, and each one declares the C library version that
distro actually ships instead of an artificially old floor.
SQLCipher and OpenSSL are statically bundled into every build (rusqlite's
bundled-sqlcipher-vendored-openssl feature) rather than linked against
the distro's libsqlcipher-dev, for two reasons: it removes a runtime
dependency that would otherwise need separate version tracking across ten
distros, and it sidesteps the upstream 4GB bug above living in whichever
SQLCipher build happens to be in a given distro's archive at the time.
All packages pass the full test-install.sh cycle (install, create, mount,
write, read, unmount, check) on every target and both architectures.
crates.io. The crate is published as
cofferfs - coffer was already
taken there by an unrelated library. Only the crate name differs: [[bin]]
in Cargo.toml keeps the binary called coffer, and a name key in the
cargo-deb and cargo-generate-rpm metadata keeps the .deb and .rpm
called coffer too, so nothing a user sees changes. The demo animation,
the social-preview image and the CI workflows are excluded from the
crate; what remains is 88 KB.
Signatures. The release job writes SHA256SUMS over every package and
signs that file with minisign
(SHA256SUMS.minisig). A checksum file alone proves nothing - whoever can
replace a package on the download page can replace the checksums next to
it - so the signature is what to verify, against the public key in
minisign.pub at the repository root (and in the README). The signing
key is a plain minisign key stored only in the repository's Actions
secrets; the job verifies its own signature against the committed public
key before publishing, so a mismatch between the two fails the release
rather than shipping an unverifiable signature.
Source packages for external repositories. Two more definitions live
next to the binary packaging, for repositories that build from source on
their own infrastructure: packaging/aur/PKGBUILD for the Arch User
Repository and packaging/rpm/coffer.spec for COPR (Fedora, EL 9/10) or
any other rpmbuild-based service. Both build from the release tarball of a
pinned tag, hand build.rs the tag's commit through COFFER_GIT_HASH (there
is no .git in a tarball, and coffer --version should still name the
commit), and are built, installed and smoke-tested by the "Source
packages" workflow on Arch, Fedora 44, EL9 and EL10 whenever they change
and on every release tag. On a release, bump the version, the commit and
the checksum in both files in the same commit as Cargo.toml.
Files in this repo
src/— the FUSE filesystem + CLI implementationCargo.toml/Cargo.lock— dependencies and thecargo-debpackaging metadataMakefile—make build/make install/make manpackaging/— thecoffer(1)man page and the per-distro.deband.rpmbuild scripts (see Packaging above).github/workflows/release.yml— builds a.deband an.rpmper target distro, smoke-tests each one, and publishes them to GitHub Releases
Source of this page: REFERENCE.md in the cofferFS repository.