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