Manual Pages  — MKUZIP

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

The mkuzip utility compresses a disk image file so that the geom_uzip(4) class will be able to decompress the resulting image at run-time. This allows for 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:

1. An infile image is split into clusters; each cluster is compressed using zlib(3) or lzma(3).
2. The resulting set of compressed clusters along with headers that allow locating each individual cluster is written to the output file.

The options are:

-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.
-d
	Enable de-duplication. When the option is enabled the mkuzip detects identical blocks in the input and replaces each subsequent occurence 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.
-L
	Use lzma(3) compression algorithm instead of the default zlib(3). The lzma(3) provides noticeable better compression levels on the same data set at the expense of much slower compression speed (10-20x) and somewhat slower decompression (2-3x).
-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.
-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-blocks detection and elimination. When this option is set, the mkuzip would compress empty blocks (i.e. clusters that consist of only zero bytes) just as it would any other block. When the option is not set, the mkuzip detects such blocks and skips them from the output. Setting -Z results is slight increase of compressed image size, typically less than 0.1% of a final size of the compressed image.

The compression ratio largely depends on the cluster size used. For large cluster sizes (16K and higher), typical compression ratios are only 1-2% less than those achieved with gzip(1). 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 mkuzip utility inserts a short shell script at the beginning of the generated image, which makes it possible to "run" the image just like any other shell script. The script tries to load the geom_uzip(4) class if it is not loaded, configure the image as an md(4) disk device using mdconfig(8), and automatically mount it using mount_cd9660(8) on the mount point provided as the first argument to the script.

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.

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