MKUZIP(8)

🦋 MKUZIP(8) 🦋

okay bestie, welcome to mkuzip — the compress-disk-image-for-geom_uzip(4)-class girlie 💅

---

✨ NAME ✨

mkuzip — compress disk image for use with geom_uzip(4) class 💖

---

✨ SYNOPSIS ✨

mkuzip [-dSsvZ] [-A compression_algorithm] [-C compression_level]
       [-j compression_jobs] [-o outfile] [-s cluster_size] infile

---

✨ DESCRIPTION ✨

So mkuzip compresses a disk image file so that the geom_uzip(4) class can decompress the resulting image at run-time. It's giving "shrink the vibe, pay a little CPU tax later" — you get a significant reduction of size of disk image, at the expense of some CPU time required to decompress the data each time it is read 🔥

The mkuzip utility works in two phases, periodt:

1. An infile image is split into clusters; each cluster is compressed.
2. The resulting set of compressed clusters is written to the output file. In addition, a “table of contents” header is written which allows for efficient seeking. (iconic, ngl — that header is the whole reason seeking doesn't suck 💀)

🎀 The options are 🎀

• -A [lzma | zlib | zstd] — select a specific compression algorithm. If this option is not provided, the default is zlib.
  • The lzma algorithm provides noticeable better compression levels than zlib on the same data set. It has vastly slower compression speed and moderately slower decompression speed. (like, it's the overachiever who takes forever to get ready 😭)
  • The zstd algorithm provides better compression levels than zlib on the same data set. It also has faster compression and decompression speed than zlib. In the very high compression “level” settings, it does not offer quite as high a compression ratio as lzma. However, its decompression speed does not suffer at high compression “levels”. (main character energy fr fr 👑)
• -C compression_level — select the integer compression level used to parameterize the chosen compression algorithm.
  • For any given algorithm, a lesser number selects a faster compression mode. A greater number selects a slower compression mode. Typically, for the same algorithm, a greater compression_level provides better final compression ratio.
  • For lzma, the range of valid compression levels is 0-9. The mkuzip default for lzma is 6.
  • For zlib, the range of valid compression levels is 1-9. The mkuzip default for zlib is 9.
  • For zstd, the range of valid compression levels is currently 1-19. The mkuzip default for zstd is 9.
• -d — enable de-duplication. When the option is enabled mkuzip detects identical blocks in the input and replaces each subsequent occurrence of such block with pointer to the very first one in the output. Setting this option results is moderate decrease of compressed image size, typically around 3-5% of a final size of the compressed image. (free real estate, lowkey 🍓)
• -j compression_jobs — specify the number of compression jobs that mkuzip runs in parallel to speed up compression. When option is not specified the number of jobs set to be equal to the value of hw.ncpu sysctl(8) variable. (multi-tasking queen ✨)
• [-L] — legacy flag that indicates the same thing as “-A lzma”. (she's old but she still serves 🙈)
• -o outfile — name of the output file outfile. The default is to use the input name with the suffix .uzip for the zlib(3) compression or .ulzma for the lzma(3).
• -S — print summary about the compression ratio as well as output file size after file has been processed. (receipts! 💅)
• -s cluster_size — split the image into clusters of cluster_size bytes, 16384 bytes by default. The cluster_size should be a multiple of 512 bytes.
• -v — display verbose messages.
• -Z — disable zero-block detection and elimination. When this option is set, mkuzip compresses blocks of zero bytes just as it would any other block. When the option is not set, mkuzip detects and compresses zero blocks in a space-efficient way. Setting -Z increases compressed image sizes slightly, typically less than 0.1%.

---

✨ IMPLEMENTATION NOTES ✨

The compression ratio largely depends on the compression algorithm, level, and cluster size used. For large cluster sizes (16kB and higher), typical overall image compression ratios with zlib(3) are only 1-2% less than those achieved with gzip(1) over the entire image. However, it should be kept in mind that larger cluster sizes lead to higher overhead in the geom_uzip(4) class, as the class has to decompress the whole cluster even if only a few bytes from that cluster have to be read. (the way that whole-cluster decompress is doing the absolute most for a few bytes 😭)

Additionally, the threshold at 16-32 kB where a larger cluster size does not benefit overall compression ratio is an artifact of the zlib(3) algorithm in particular. Lzma and Zstd will continue to provide better compression ratios as cluster sizes are increased, at high enough compression levels. The same tradeoff continues to apply: reads in geom_uzip(4) become more expensive the greater the cluster size.

The de-duplication is a FreeBSD specific feature and while it does not require any changes to on-disk compressed image format, however it did require some matching changes to the geom_uzip(4) to handle resulting images correctly.

🫶 heads up bestie: to make use of zstd mkuzip images, the kernel must be configured with ZSTDIO. It is enabled by default in many GENERIC kernels provided as binary distributions by FreeBSD. The status on any particular system can be verified by checking sysctl(8) kern.features.geom_uzip_zstd for “1”.

---

✨ EXIT STATUS ✨

The mkuzip utility exits 0 on success, and >0 if an error occurs. ⭐

---

✨ EXAMPLES ✨

The following describes how to create and mount a uzip image.

Create a file system image:

makefs /src.img /usr/src

Create the uzip image, the output file will be named src.img.uzip:

mkuzip /src.img

Ensure geom_uzip is loaded:

kldload geom_uzip

Create an MD device backed by the uzip image:

mdconfig -f /src.img.uzip

Mount the uzip image:

mount -o ro /dev/md0.uzip /mnt

---

✨ SEE ALSO ✨

gzip(1), xz(1), zstd(1), zlib(3), geom(4), geom_uzip(4), md(4), mdconfig(8), mount_cd9660(8) 🌈

---

✨ AUTHORS ✨

Maxim Sobolev <sobomax@FreeBSD.org> 💜

---

okay that's the whole page, ily, go compress something 🧚 — with love from the Debian girlies, version vibes of August 9, 2019, page MKUZIP(8) 🎀💖✨