share/man/man4/geom_uzip.4

   1 .\"
   2 .\" Copyright (c) 2006 Ceri Davies
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd August 13, 2019
  29 .Dt GEOM_UZIP 4
  30 .Os
  31 .Sh NAME
  32 .Nm geom_uzip
  33 .Nd "GEOM based compressed disk images and partitions"
  34 .Sh SYNOPSIS
  35 To compile this driver into the kernel,
  36 place the following line in your
  37 kernel configuration file:
  38 .Bd -ragged -offset indent
  39 .Cd "device xz"
  40 .Cd "options zstd"
  41 .Cd "options GEOM_UZIP"
  42 .Ed
  43 .Pp
  44 Alternatively, to load the driver as a
  45 module at boot time, place the following line in
  46 .Xr loader.conf 5 :
  47 .Bd -literal -offset indent
  48 geom_uzip_load="YES"
  49 .Ed
  50 .Sh DESCRIPTION
  51 The
  52 .Nm
  53 framework provides support for compressed read-only
  54 disk images.
  55 This allows significant storage savings at the expense of
  56 a some CPU time on each read.
  57 Data written in the GEOM label area allows
  58 .Nm
  59 to detect compressed images which have been created with
  60 .Xr mkuzip 8
  61 and presented to the kernel as a logical disk device via
  62 .Xr md 4 .
  63 .Nm
  64 creates a unique
  65 .Pa md#.uzip
  66 device for each image.
  67 .Pp
  68 .Nm
  69 is not limited to supporting only
  70 .Xr md 4
  71 images.
  72 The image can also reside on a block device.
  73 .Pq For example, a disk, USB flash drive,  DVD-ROM, etc.
  74 The appropriate device node will appear with the
  75 .Pa .uzip
  76 suffix.
  77 .Bd -literal -offset indent
  78 # gpart show da0
  79 =>      0  7833600  da0  BSD  (3.7G)
  80         0  2097152    1  freebsd-ufs  (1.0G)
  81   2097152  5736448       - free -  (2.7G)
  82 # gpart add -t freebsd-ufs -s 1G da0
  83 da0b added
  84 # dd if=/tmp/20160217_dcomp_zcomp.uzip bs=256k of=/dev/da0b
  85 3190+1 records in
  86 3190+1 records out
  87 836331008 bytes transferred in 111.021489 secs (7533055 bytes/sec)
  88 # fsck -t ffs /dev/da0b.uzip
  89 ** /dev/da0b.uzip (NO WRITE)
  90 ** Last Mounted on /mnt
  91 ** Phase 1 - Check Blocks and Sizes
  92 ** Phase 2 - Check Pathnames
  93 ** Phase 3 - Check Connectivity
  94 ** Phase 4 - Check Reference Counts
  95 ** Phase 5 - Check Cyl groups
  96 97455 files, 604242 used, 184741 free (2349 frags, 22799 blocks,
  97    0.3% fragmentation)
  98 # mount -o ro /dev/da0b.uzip /mnt
  99 # df /dev/da0b.uzip
 100 Filesystem     1K-blocks    Used  Avail Capacity  Mounted on
 101 /dev/da0b.uzip   3155932 2416968 738964    77%    /mnt
 102 .Ed
 103 .Pp
 104 The
 105 .Nm
 106 device is subsequently used by
 107 .Fx
 108 kernel to access the uncompressed data.
 109 The
 110 .Nm
 111 driver does not allow write operations to the underlying disk image.
 112 To check which
 113 .Dq providers
 114 match a given
 115 .Nm
 116 device:
 117 .Bd -literal -offset indent
 118 # geom uzip list
 119 Geom name: md1.uzip
 120 Providers:
 121 1. Name: md1.uzip
 122    Mediasize: 22003712 (21M)
 123    Sectorsize: 512
 124 Consumers:
 125 1. Name: md1
 126    Mediasize: 9563648 (9.1M)
 127    Sectorsize: 512
 128
 129 Geom name: da0b.uzip
 130 Providers:
 131 1. Name: da0b.uzip
 132    Mediasize: 3355443200 (3.1G)
 133    Sectorsize: 512
 134 Consumers:
 135 1. Name: da0b
 136    Mediasize: 1073741824 (1.0G)
 137    Sectorsize: 512
 138 .Ed
 139 .Pp
 140 .Nm
 141 allows mounting the root file system from a compressed disk partition by
 142 setting the
 143 .Dv vfs.root.mountfrom
 144 tunable.
 145 See
 146 .Xr loader.conf 5
 147 for details.
 148 .Sh DIAGNOSTICS
 149 Several flags are provided for tracing
 150 .Nm
 151 I/O operations and TOC parsing via the following sysctls.
 152 .Bl -tag -width indent
 153 .It Va kern.geom.uzip.debug
 154 Log level.
 155 Zero disables logging.
 156 Higher values enable more verbose debug logging for
 157 .Nm .
 158 Supported levels are from 0 (no logging) to 4 (maximum amount of logging).
 159 .It Va kern.geom.uzip.debug_block
 160 Log operations involving compressed cluster number.
 161 .El
 162 .Sh SEE ALSO
 163 .Xr GEOM 4 ,
 164 .Xr md 4 ,
 165 .Xr geom 8 ,
 166 .Xr mkuzip 8
 167 .Sh HISTORY
 168 Zstd support was added in
 169 .Fx 13.0 .
 170 .Sh AUTHORS
 171 .An -nosplit
 172 The
 173 .Nm
 174 driver was written by
 175 .An Max Khon Aq Mt fjoe@FreeBSD.org .
 176 The block de-duplication code as well as some
 177 .Nm
 178 driver optimizations have been contributed by
 179 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org .
 180 The LZMA decompression support and CLOOP 3.0 support have been added by
 181 .An Aleksandr Rybalko Aq Mt ray@FreeBSD.org .
 182 .Pp
 183 This manual page was written by
 184 .An Ceri Davies Aq Mt ceri@FreeBSD.org .