TARFS(5)

💅 TARFS(5) — tarfs

okay so bestie, buckle up, because this one is the tarfs manual page from the File Formats Manual and it's genuinely so cool. it's a whole filesystem that lives inside a tarball. no cap. 🎀

---

✨ NAME ✨

tarfs — the tarball filesystem, aka the moment a .tar file said "i'm a filesystem now" and honestly? it ate. 💖

---

🌸 SYNOPSIS 🌸

so there's two ways to get this driver into your life, depending on the vibe you're going for.

option one: compile it straight into the kernel. drop this line into your kernel configuration file:

options TARFS

option two: load it as a module at boot time instead. put this in loader.conf(5):

tarfs_load="YES"

pick your fighter, both slay. ✨

---

🦋 DESCRIPTION 🦋

the tarfs driver implements a read-only filesystem backed by a tar(5) file. read-only means read-only, bestie, it's not gonna let you write anything, periodt. rn only POSIX archives are supported, optionally compressed with zstd(1). that's the whole guest list, iykyk. 🫶

the preferred I/O size for tarfs filesystems can be adjusted using the vfs.tarfs.ioshift sysctl setting and tunable. set it to 0 and it'll reset itself back to its default value. and listen — this is the important part — changes to this setting only apply to filesystems mounted after the change. so if you're sitting there wondering why your already-mounted fs isn't picking up the new number... that's why. sorry babe 💀

when the backing tar file is compressed with zstd(1), you can improve I/O performance by making sure the compressed data is broken up into multiple frames. this helps minimize unnecessary decompression work, which is exactly the kind of efficiency we stan. 👑

if you're using bsdtar(1) to create the tar file, you can pull this off with the zstd:max-frame-size and zstd:frame-per-file options. sensible frame sizes? powers of 2, sitting between the system's base page size (see arch(7)) and the value of the kern.maxphys sysctl. that's the sweet spot, no notes.

and here's the tradeoff tea, because there's always a tradeoff:

• smaller frames will generally give you a worse compression ratio and need extra kernel memory to maintain an index. not the vibe. 😭
• larger frames will on average need more CPU time to access data when you're doing random I/O. also not the vibe, just a different flavor of not the vibe.

---

🔥 DIAGNOSTICS 🔥

if it's enabled by the TARFS_DEBUG kernel option, the vfs.tarfs.debug sysctl setting controls debugging output from the tarfs driver. 🕵️‍♀️

want debugging output for individual sections of the driver? you enable them by adding together the relevant values from the table below. yes, adding. it's a bitmask situation, math girlies rise. 🧮✨

• 0x01 — memory allocations
• 0x02 — checksum calculations
• 0x04 — filesystem operations (vfsops)
• 0x08 — path lookups
• 0x10 — file operations (vnops)
• 0x20 — general I/O
• 0x40 — decompression
• 0x80 — decompression index
• 0x100 — sparse file mapping
• 0x200 — bounce buffer usage

---

👑 SEE ALSO 👑

tar(1), zstd(1), fstab(5), tar(5), mount(8), sysctl(8) — go read them, they're all icons in their own right. 💜

---

🌈 HISTORY 🌈

the tarfs driver was developed by Stephen J. Kiernan <stevek@FreeBSD.org> and Dag-Erling Smørgrav <des@FreeBSD.org> for Juniper Networks and Klara Systems. this manual page was written by Dag-Erling Smørgrav <des@FreeBSD.org> for Juniper Networks and Klara Systems. we love a credited author moment, absolute main character energy. ⭐

---

and that's the whole page bestie 💖 this one's from the Debian crew, dated February 14, 2023 — a whole Valentine's Day gift to us all 🎀✨💅