TARFS(4)               FreeBSD Kernel Interfaces Manual               TARFS(4)

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):

           tarfs_load="YES"

DESCRIPTION

     The tarfs driver implements a read-only filesystem backed by a tar(5)
     file.  Currently, only POSIX archives, optionally compressed with
     zstd(1), 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), 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) 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))
     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), zstd(1), fstab(5), tar(5), mount(8), sysctl(8)

HISTORY

     The tarfs driver was developed by Stephen J. Kiernan <stevek@FreeBSD.org>
     and Dag-Erling Smorgrav <des@FreeBSD.org> for Juniper Networks and Klara
     Systems.  This manual page was written by Dag-Erling Smorgrav
     <des@FreeBSD.org> for Juniper Networks and Klara Systems.

FreeBSD 15.1-STABLE-HBSD       February 14, 2023                      TARFS(4)