1.\"- 2.\" SPDX-License-Identifier: BSD-2-Clause 3.\" 4.\" Copyright (c) 2022 Klara, Inc. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd February 14, 2023 28.Dt TARFS 4 29.Os 30.Sh NAME 31.Nm tarfs 32.Nd tarball filesystem 33.Sh SYNOPSIS 34To compile this driver into the kernel, place the following line in 35your kernel configuration file: 36.Bd -ragged -offset indent 37.Cd "options TARFS" 38.Ed 39.Pp 40Alternatively, to load the driver as a module at boot time, place the 41following line in 42.Xr loader.conf 5 : 43.Bd -literal -offset indent 44tarfs_load="YES" 45.Ed 46.Sh DESCRIPTION 47The 48.Nm 49driver implements a read-only filesystem backed by a 50.Xr tar 5 51file. 52Currently, only POSIX archives, optionally compressed with 53.Xr zstd 1 , 54are supported. 55.Pp 56The preferred I/O size for 57.Nm 58filesystems can be adjusted using the 59.Va vfs.tarfs.ioshift 60sysctl setting and tunable. 61Setting it to 0 will reset it to its default value. 62Note that changes to this setting only apply to filesystems mounted 63after the change. 64.Pp 65When the backing tar file is compressed with 66.Xr zstd 1 , 67I/O performance can be improved by ensuring that compressed data is 68broken up into multiple frames. 69This helps minimize unnecessary decompression work. 70When using 71.Xr bsdtar 1 72to create the tar file, this can be achieved using the 73.Cm zstd:max-frame-size 74and 75.Cm zstd:frame-per-file 76options. 77Sensible frame sizes are powers of 2 between the system's base page size 78(see 79.Xr arch 7 ) 80and the value of the 81.Sy kern.maxphys 82sysctl. 83Smaller frames will generally yield a worse compression ratio and require extra 84kernel memory to maintain an index, and larger frames will on average require 85more CPU time to access data when performing random I/O. 86.Sh DIAGNOSTICS 87If enabled by the 88.Dv TARFS_DEBUG 89kernel option, the 90.Va vfs.tarfs.debug 91sysctl setting can be used to control debugging output from the 92.Nm 93driver. 94Debugging output for individual sections of the driver can be enabled 95by adding together the relevant values from the table below. 96.Bl -column Value Description 97.It 0x01 Ta Memory allocations 98.It 0x02 Ta Checksum calculations 99.It 0x04 Ta Filesystem operations (vfsops) 100.It 0x08 Ta Path lookups 101.It 0x10 Ta File operations (vnops) 102.It 0x20 Ta General I/O 103.It 0x40 Ta Decompression 104.It 0x80 Ta Decompression index 105.It 0x100 Ta Sparse file mapping 106.It 0x200 Ta Bounce buffer usage 107.El 108.Sh SEE ALSO 109.Xr tar 1 , 110.Xr zstd 1 , 111.Xr fstab 5 , 112.Xr tar 5 , 113.Xr mount 8 , 114.Xr sysctl 8 115.Sh HISTORY 116.An -nosplit 117The 118.Nm 119driver was developed by 120.An Stephen J. Kiernan Aq Mt stevek@FreeBSD.org 121and 122.An Dag-Erling Smørgrav Aq Mt des@FreeBSD.org 123for Juniper Networks and Klara Systems. 124This manual page was written by 125.An Dag-Erling Smørgrav Aq Mt des@FreeBSD.org 126for Juniper Networks and Klara Systems. 127