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 February 26, 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 GEOM_UZIP"
  41 .Ed
  42 .Pp
  43 Alternatively, to load the driver as a
  44 module at boot time, place the following line in
  45 .Xr loader.conf 5 :
  46 .Bd -literal -offset indent
  47 geom_uzip_load="YES"
  48 .Ed
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 framework provides support for compressed read-only
  53 disk images.
  54 This allows significant storage savings at the expense of
  55 a some CPU time on each read.
  56 Data written in the GEOM label area allows
  57 .Nm
  58 to detect compressed images which have been created with
  59 .Xr mkuzip 8
  60 and presented to the kernel as a logical disk device via
  61 .Xr md 4 .
  62 .Nm
  63 creates a unique
  64 .Pa md#.uzip
  65 device for each image.
  66 .Pp
  67 .Nm
  68 is not limited to supporting only
  69 .Xr md 4
  70 images.
  71 The image can also reside on a block device.
  72 .Pq For example, a disk, USB flash drive,  DVD-ROM, etc.
  73 The appropriate device node will appear with the
  74 .Pa .uzip
  75 suffix.
  76 .Bd -literal -offset indent
  77 # gpart show da0
  78 =>      0  7833600  da0  BSD  (3.7G)
  79         0  2097152    1  freebsd-ufs  (1.0G)
  80   2097152  5736448       - free -  (2.7G)
  81 # gpart add -t freebsd-ufs -s 1G da0
  82 da0b added
  83 # dd if=/tmp/20160217_dcomp_zcomp.uzip bs=256k of=/dev/da0b
  84 3190+1 records in
  85 3190+1 records out
  86 836331008 bytes transferred in 111.021489 secs (7533055 bytes/sec)
  87 # fsck -t ffs /dev/da0b.uzip
  88 ** /dev/da0b.uzip (NO WRITE)
  89 ** Last Mounted on /mnt
  90 ** Phase 1 - Check Blocks and Sizes
  91 ** Phase 2 - Check Pathnames
  92 ** Phase 3 - Check Connectivity
  93 ** Phase 4 - Check Reference Counts
  94 ** Phase 5 - Check Cyl groups
  95 97455 files, 604242 used, 184741 free (2349 frags, 22799 blocks,
  96    0.3% fragmentation)
  97 # mount -o ro /dev/da0b.uzip /mnt
  98 # df /dev/da0b.uzip
  99 Filesystem     1K-blocks    Used  Avail Capacity  Mounted on
 100 /dev/da0b.uzip   3155932 2416968 738964    77%    /mnt
 101 .Ed
 102 .Pp
 103 The
 104 .Nm
 105 device is subsequently used by
 106 .Fx
 107 kernel to access the uncompressed data.
 108 The
 109 .Nm
 110 driver does not allow write operations to the underlying disk image.
 111 To check which
 112 .Dq providers
 113 match a given
 114 .Nm
 115 device:
 116 .Bd -literal -offset indent
 117 # geom uzip list
 118 Geom name: md1.uzip
 119 Providers:
 120 1. Name: md1.uzip
 121    Mediasize: 22003712 (21M)
 122    Sectorsize: 512
 123 Consumers:
 124 1. Name: md1
 125    Mediasize: 9563648 (9.1M)
 126    Sectorsize: 512
 127
 128 Geom name: da0b.uzip
 129 Providers:
 130 1. Name: da0b.uzip
 131    Mediasize: 3355443200 (3.1G)
 132    Sectorsize: 512
 133 Consumers:
 134 1. Name: da0b
 135    Mediasize: 1073741824 (1.0G)
 136    Sectorsize: 512
 137 .Ed
 138 .Pp
 139 .Nm
 140 allows mounting the root file system from a compressed disk partition by
 141 setting the
 142 .Dv vfs.root.mountfrom
 143 tunable.
 144 See
 145 .Xr loader.conf 5
 146 for details.
 147 .Sh DIAGNOSTICS
 148 Several flags are provided for tracing
 149 .Nm
 150 I/O operations and TOC parsing via the following sysctls.
 151 .Bl -tag -width indent
 152 .It Va kern.geom.uzip.debug
 153 Log level.
 154 Zero disables logging.
 155 Higher values enable more verbose debug logging for
 156 .Nm .
 157 Supported levels are from 0 (no logging) to 4 (maximum amount of logging).
 158 .It Va kern.geom.uzip.debug_block
 159 Log operations involving compressed cluster number.
 160 .El
 161 .Sh SEE ALSO
 162 .Xr GEOM 4 ,
 163 .Xr md 4 ,
 164 .Xr geom 8 ,
 165 .Xr mkuzip 8
 166 .Sh AUTHORS
 167 .An -nosplit
 168 The
 169 .Nm
 170 driver was written by
 171 .An Max Khon Aq Mt fjoe@FreeBSD.org .
 172 The block de-duplication code as well as some
 173 .Nm
 174 driver optimizations have been contributed by
 175 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org .
 176 The LZMA decompression support and CLOOP 3.0 support have been added by
 177 .An Aleksandr Rybalko Aq Mt ray@FreeBSD.org .
 178 .Pp
 179 This manual page was written by
 180 .An Ceri Davies Aq Mt ceri@FreeBSD.org .