GEOM_UZIP(4)           FreeBSD Kernel Interfaces Manual           GEOM_UZIP(4)

NAME
     geom_uzip - GEOM based compressed disk images and partitions

SYNOPSIS
     To compile this driver into the kernel, place the following line in your
     kernel configuration file:

           device xz
           options zstd
           options GEOM_UZIP

     Alternatively, to load the driver as a module at boot time, place the
     following line in loader.conf(5):

           geom_uzip_load="YES"

DESCRIPTION
     The geom_uzip framework provides support for compressed read-only disk
     images.  This allows significant storage savings at the expense of some
     CPU time on each read.  Data written in the GEOM label area allows
     geom_uzip to detect compressed images which have been created with
     mkuzip(8) and presented to the kernel as a logical disk device via md(4).
     geom_uzip creates a unique md#.uzip device for each image.

     geom_uzip is not limited to supporting only md(4) images.  The image can
     also reside on a block device.  (For example, a disk, USB flash drive,
     DVD-ROM, etc).  The appropriate device node will appear with the .uzip
     suffix.

           # gpart show da0
           =>      0  7833600  da0  BSD  (3.7G)
                   0  2097152    1  freebsd-ufs  (1.0G)
             2097152  5736448       - free -  (2.7G)
           # gpart add -t freebsd-ufs -s 1G da0
           da0b added
           # dd if=/tmp/20160217_dcomp_zcomp.uzip bs=256k of=/dev/da0b
           3190+1 records in
           3190+1 records out
           836331008 bytes transferred in 111.021489 secs (7533055 bytes/sec)
           # fsck -t ffs /dev/da0b.uzip
           ** /dev/da0b.uzip (NO WRITE)
           ** Last Mounted on /mnt
           ** Phase 1 - Check Blocks and Sizes
           ** Phase 2 - Check Pathnames
           ** Phase 3 - Check Connectivity
           ** Phase 4 - Check Reference Counts
           ** Phase 5 - Check Cyl groups
           97455 files, 604242 used, 184741 free (2349 frags, 22799 blocks,
              0.3% fragmentation)
           # mount -o ro /dev/da0b.uzip /mnt
           # df /dev/da0b.uzip
           Filesystem     1K-blocks    Used  Avail Capacity  Mounted on
           /dev/da0b.uzip   3155932 2416968 738964    77%    /mnt

     The geom_uzip device is subsequently used by FreeBSD kernel to access the
     uncompressed data.  The geom_uzip driver does not allow write operations
     to the underlying disk image.  To check which "providers" match a given
     geom_uzip device:

           # geom uzip list
           Geom name: md1.uzip
           Providers:
           1. Name: md1.uzip
              Mediasize: 22003712 (21M)
              Sectorsize: 512
           Consumers:
           1. Name: md1
              Mediasize: 9563648 (9.1M)
              Sectorsize: 512

           Geom name: da0b.uzip
           Providers:
           1. Name: da0b.uzip
              Mediasize: 3355443200 (3.1G)
              Sectorsize: 512
           Consumers:
           1. Name: da0b
              Mediasize: 1073741824 (1.0G)
              Sectorsize: 512

     geom_uzip allows mounting the root file system from a compressed disk
     partition by setting the vfs.root.mountfrom tunable.  See loader.conf(5)
     for details.

DIAGNOSTICS
     Several flags are provided for tracing geom_uzip I/O operations and TOC
     parsing via the following sysctls.

     kern.geom.uzip.debug
             Log level.  Zero disables logging.  Higher values enable more
             verbose debug logging for geom_uzip.  Supported levels are from 0
             (no logging) to 4 (maximum amount of logging).

     kern.geom.uzip.debug_block
             Log operations involving compressed cluster number.

SEE ALSO
     GEOM(4), md(4), geom(8), mkuzip(8)

HISTORY
     Zstd support was added in FreeBSD 13.0.

AUTHORS
     The geom_uzip driver was written by Max Khon <fjoe@FreeBSD.org>.  The
     block de-duplication code as well as some geom_uzip driver optimizations
     have been contributed by Maxim Sobolev <sobomax@FreeBSD.org>.  The LZMA
     decompression support and CLOOP 3.0 support have been added by Aleksandr
     Rybalko <ray@FreeBSD.org>.

     This manual page was written by Ceri Davies <ceri@FreeBSD.org>.

FreeBSD 13.1-RELEASE-p6         April 28, 2021         FreeBSD 13.1-RELEASE-p6