diff --git a/share/man/man5/tarfs.5 b/share/man/man5/tarfs.5 index 56c56ac43287..ed76d2b4b2b8 100644 --- a/share/man/man5/tarfs.5 +++ b/share/man/man5/tarfs.5 @@ -1,126 +1,126 @@ .\"- .\" SPDX-License-Identifier: BSD-2-Clause .\" .\" Copyright (c) 2022 Klara, Inc. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd February 14, 2023 .Dt TARFS 5 .Os .Sh NAME .Nm tarfs .Nd tarball filesystem .Sh SYNOPSIS To compile this driver into the kernel, place the following line in your kernel configuration file: .Bd -ragged -offset indent .Cd "options TARFS" .Ed .Pp Alternatively, to load the driver as a module at boot time, place the following line in .Xr loader.conf 5 : .Bd -literal -offset indent tarfs_load="YES" .Ed .Sh DESCRIPTION The .Nm driver implements a read-only filesystem backed by a .Xr tar 5 file. Currently, only POSIX archives, optionally compressed with .Xr zstd 1 , are supported. .Pp The preferred I/O size for .Nm filesystems can be adjusted using the .Va 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. .Pp When the backing tar file is compressed with .Xr 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 .Xr bsdtar 1 to create the tar file, this can be achieved using the .Cm zstd:max-frame-size and -.Cm ztsd:frame-per-file +.Cm zstd:frame-per-file options. Sensible frame sizes are powers of 2 between the system's base page size (see .Xr arch 7 ) and the value of the .Sy 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. .Sh DIAGNOSTICS If enabled by the .Dv TARFS_DEBUG kernel option, the .Va vfs.tarfs.debug sysctl setting can be used to control debugging output from the .Nm driver. Debugging output for individual sections of the driver can be enabled by adding together the relevant values from the table below. .Bl -column Value Description .It 0x01 Ta Memory allocations .It 0x02 Ta Checksum calculations .It 0x04 Ta Filesystem operations (vfsops) .It 0x08 Ta Path lookups .It 0x10 Ta File operations (vnops) .It 0x20 Ta General I/O .It 0x40 Ta Decompression .It 0x80 Ta Decompression index .It 0x100 Ta Sparse file mapping .It 0x200 Ta Bounce buffer usage .El .Sh SEE ALSO .Xr tar 1 , .Xr zstd 1 , .Xr fstab 5 , .Xr tar 5 , .Xr mount 8 , .Xr sysctl 8 .Sh HISTORY .An -nosplit The .Nm driver was developed by .An Stephen J. Kiernan Aq Mt stevek@FreeBSD.org and .An Dag-Erling Smørgrav Aq Mt des@FreeBSD.org for Juniper Networks and Klara Systems. This manual page was written by .An Dag-Erling Smørgrav Aq Mt des@FreeBSD.org for Juniper Networks and Klara Systems.