share/man/man5/tarfs.5

   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 5
  29 .Os
  30 .Sh NAME
  31 .Nm tarfs
  32 .Nd tarball filesystem
  33 .Sh SYNOPSIS
  34 To compile this driver into the kernel, place the following line in
  35 your kernel configuration file:
  36 .Bd -ragged -offset indent
  37 .Cd "options TARFS"
  38 .Ed
  39 .Pp
  40 Alternatively, to load the driver as a module at boot time, place the
  41 following line in
  42 .Xr loader.conf 5 :
  43 .Bd -literal -offset indent
  44 tarfs_load="YES"
  45 .Ed
  46 .Sh DESCRIPTION
  47 The
  48 .Nm
  49 driver implements a read-only filesystem backed by a
  50 .Xr tar 5
  51 file.
  52 Currently, only POSIX archives, optionally compressed with
  53 .Xr zstd 1 ,
  54 are supported.
  55 .Pp
  56 The preferred I/O size for
  57 .Nm
  58 filesystems can be adjusted using the
  59 .Va vfs.tarfs.ioshift
  60 sysctl setting and tunable.
  61 Setting it to 0 will reset it to its default value.
  62 Note that changes to this setting only apply to filesystems mounted
  63 after the change.
  64 .Sh DIAGNOSTICS
  65 If enabled by the
  66 .Dv TARFS_DEBUG
  67 kernel option, the
  68 .Va vfs.tarfs.debug
  69 sysctl setting can be used to control debugging output from the
  70 .Nm
  71 driver.
  72 Debugging output for individual sections of the driver can be enabled
  73 by adding together the relevant values from the table below.
  74 .Bl -column Value Description
  75 .It 0x01 Ta Memory allocations
  76 .It 0x02 Ta Checksum calculations
  77 .It 0x04 Ta Filesystem operations (vfsops)
  78 .It 0x08 Ta Path lookups
  79 .It 0x10 Ta File operations (vnops)
  80 .It 0x20 Ta General I/O
  81 .It 0x40 Ta Decompression
  82 .It 0x80 Ta Decompression index
  83 .It 0x100 Ta Sparse file mapping
  84 .It 0x200 Ta Bounce buffer usage
  85 .El
  86 .Sh SEE ALSO
  87 .Xr tar 1 ,
  88 .Xr zstd 1 ,
  89 .Xr fstab 5 ,
  90 .Xr tar 5 ,
  91 .Xr mount 8 ,
  92 .Xr sysctl 8
  93 .Sh HISTORY
  94 .An -nosplit
  95 The
  96 .Nm
  97 driver was developed by
  98 .An Stephen J. Kiernan Aq Mt stevek@FreeBSD.org
  99 and
 100 .An Dag-Erling Smørgrav Aq Mt des@FreeBSD.org
 101 for Juniper Networks and Klara Systems.
 102 This manual page was written by
 103 .An Dag-Erling Smørgrav Aq Mt des@FreeBSD.org
 104 for Juniper Networks and Klara Systems.