mirror of
https://github.com/freebsd/freebsd-src
synced 2024-09-06 09:10:28 +00:00
1687d77197
Filesystem manual pages describe drivers, not formats; except for fs, which describes the structures of ffs/ufs, not how to use it in the system. Reported by: emaste Reviewed by: des, imp, meena (previous version) Pull Request: https://github.com/freebsd/freebsd-src/pull/1077
127 lines
3.9 KiB
Groff
127 lines
3.9 KiB
Groff
.\"-
|
|
.\" 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
|
|
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.
|