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 35To compile this driver into the kernel, 36place the following line in your 37kernel configuration file: 38.Bd -ragged -offset indent 39.Cd "device xz" 40.Cd "options GEOM_UZIP" 41.Ed 42.Pp 43Alternatively, to load the driver as a 44module at boot time, place the following line in 45.Xr loader.conf 5 : 46.Bd -literal -offset indent 47geom_uzip_load="YES" 48.Ed 49.Sh DESCRIPTION 50The 51.Nm 52framework provides support for compressed read-only 53disk images. 54This allows significant storage savings at the expense of 55a some CPU time on each read. 56Data written in the GEOM label area allows 57.Nm 58to detect compressed images which have been created with 59.Xr mkuzip 8 60and presented to the kernel as a logical disk device via 61.Xr md 4 . 62.Nm 63creates a unique 64.Pa md#.uzip 65device for each image. 66.Pp 67.Nm 68is not limited to supporting only 69.Xr md 4 70images. 71The image can also reside on a block device. 72.Pq For example, a disk, USB flash drive, DVD-ROM, etc. 73The appropriate device node will appear with the 74.Pa .uzip 75suffix. 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 82da0b added 83# dd if=/tmp/20160217_dcomp_zcomp.uzip bs=256k of=/dev/da0b 843190+1 records in 853190+1 records out 86836331008 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 9597455 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 99Filesystem 1K-blocks Used Avail Capacity Mounted on 100/dev/da0b.uzip 3155932 2416968 738964 77% /mnt 101.Ed 102.Pp 103The 104.Nm 105device is subsequently used by 106.Fx 107kernel to access the uncompressed data. 108The 109.Nm 110driver does not allow write operations to the underlying disk image. 111To check which 112.Dq providers 113match a given 114.Nm 115device: 116.Bd -literal -offset indent 117# geom uzip list 118Geom name: md1.uzip 119Providers: 1201. Name: md1.uzip 121 Mediasize: 22003712 (21M) 122 Sectorsize: 512 123Consumers: 1241. Name: md1 125 Mediasize: 9563648 (9.1M) 126 Sectorsize: 512 127 128Geom name: da0b.uzip 129Providers: 1301. Name: da0b.uzip 131 Mediasize: 3355443200 (3.1G) 132 Sectorsize: 512 133Consumers: 1341. Name: da0b 135 Mediasize: 1073741824 (1.0G) 136 Sectorsize: 512 137.Ed 138.Pp 139.Nm 140allows mounting the root file system from a compressed disk partition by 141setting the 142.Dv vfs.root.mountfrom 143tunable. 144See 145.Xr loader.conf 5 146for details. 147.Sh DIAGNOSTICS 148Several flags are provided for tracing 149.Nm 150I/O operations and TOC parsing via the following sysctls. 151.Bl -tag -width indent 152.It Va kern.geom.uzip.debug 153Log level. 154Zero disables logging. 155Higher values enable more verbose debug logging for 156.Nm . 157Supported levels are from 0 (no logging) to 4 (maximum amount of logging). 158.It Va kern.geom.uzip.debug_block 159Log 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 168The 169.Nm 170driver was written by 171.An Max Khon Aq Mt fjoe@FreeBSD.org . 172The block de-duplication code as well as some 173.Nm 174driver optimizations have been contributed by 175.An Maxim Sobolev Aq Mt sobomax@FreeBSD.org . 176The LZMA decompression support and CLOOP 3.0 support have been added by 177.An Aleksandr Rybalko Aq Mt ray@FreeBSD.org . 178.Pp 179This manual page was written by 180.An Ceri Davies Aq Mt ceri@FreeBSD.org . 181