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
-nosplit 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>.