---
name: "tarfs"
section: "4"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/tarfs"
---

# tarfs(4)

tarball filesystem

## NAME

**tarfs** – tarball filesystem

## SYNOPSIS

To compile this driver into the kernel, place the following line in your kernel configuration file:

**options TARFS**

Alternatively, to load the driver as a module at boot time, place the following line in [loader.conf(5)](/loader.conf/5.md):

```
tarfs_load="YES"
```

## DESCRIPTION

The **tarfs** driver implements a read-only filesystem backed by a [tar(5)](/tar/5.md) file. Currently, only POSIX archives, optionally compressed with [zstd(1)](/zstd/1.md), are supported.

The preferred I/O size for **tarfs** filesystems can be adjusted using the *vfs.tarfs.ioshift* sysctl setting and tunable. Setting it to 0 will reset it to its default value. Note that changes to this setting only apply to filesystems mounted after the change.

When the backing tar file is compressed with [zstd(1)](/zstd/1.md), I/O performance can be improved by ensuring that compressed data is broken up into multiple frames. This helps minimize unnecessary decompression work. When using [bsdtar(1)](/bsdtar/1.md) to create the tar file, this can be achieved using the **zstd:max-frame-size** and **zstd:frame-per-file** options. Sensible frame sizes are powers of 2 between the system's base page size (see [arch(7)](/arch/7.md)) and the value of the **kern.maxphys** sysctl. Smaller frames will generally yield a worse compression ratio and require extra kernel memory to maintain an index, and larger frames will on average require more CPU time to access data when performing random I/O.

## DIAGNOSTICS

If enabled by the TARFS\_DEBUG kernel option, the *vfs.tarfs.debug* sysctl setting can be used to control debugging output from the **tarfs** driver. Debugging output for individual sections of the driver can be enabled by adding together the relevant values from the table below.

| | |
| --- | --- |
| 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)](/tar/1.md), [zstd(1)](/zstd/1.md), [fstab(5)](/fstab/5.md), [tar(5)](/tar/5.md), [mount(8)](/mount/8.md), [sysctl(8)](/sysctl/8.md)

## 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.