GEOM_UZIP(4)

💾 GEOM_UZIP(4) — the compressed-disk-images girlies' manual 💖

okay bestie, welcome to geom_uzip, a kernel interfaces manual page, and honestly? it's giving storage magic. let's get into it. ✨

---

🌸 NAME 🌸

geom_uzip — GEOM based compressed disk images and partitions 🎀

---

✨ SYNOPSIS ✨

so like, you can bake this driver right into your kernel. if that's your vibe, drop these lines into your kernel config file:

device xz
options GEOM_UZIP

or, if you'd rather load it as a module at boot time (iconic, lowkey easier), put this line in loader.conf(5):

geom_uzip_load="YES"

---

🦋 DESCRIPTION 🦋

the geom_uzip framework provides support for compressed read-only disk images. the way it works is you get significant storage savings at the expense of a some CPU time on each read. worth it? that's for you to decide, but like… yes.

data written in the GEOM label area lets geom_uzip detect compressed images that were created with mkuzip(8) and presented to the kernel as a logical disk device via md(4). and then — slay — geom_uzip creates a unique md#.uzip device for each image. every single one gets its own little moment. 💅

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

# 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 the FreeBSD kernel to access the uncompressed data. 🔥

heads up though: the geom_uzip driver does not allow write operations to the underlying disk image. read-only, babe. no notes.

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

and the main-character move: 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 the details, iykyk. 🫶

---

🔍 DIAGNOSTICS 🔍

several flags are provided for tracing geom_uzip I/O operations and TOC parsing via the following sysctls. ngl these are so useful for vibe-checking what your kernel is actually doing. 💀

• 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). so like, turn it up. 📈
• kern.geom.uzip.debug_block — log operations involving compressed cluster number.

---

👀 SEE ALSO 👀

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

---

👑 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>. legends, all of them. 🫶

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

---

and that's the whole page, bestie 💜 this one came from the Debian folks, dated February 26, 2019, and it lives at GEOM_UZIP(4) in the Kernel Interfaces Manual. go compress something. slay. 💅✨