FreeBSD Manual Pages
MKUZIP(8) System Manager's Manual MKUZIP(8) 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 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 al- lows 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. 2. The resulting set of compressed clusters is written to the output file. In addition, a "table of contents" header is written which al- lows for efficient seeking. 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. The zstd algorithm provides better compression levels than zlib on the same data set. It also has faster compression and decompres- sion speed than zlib. In the very high compression "level" set- tings, it does not offer quite as high a compression ratio as lzma. However, its decompression speed does not suffer at high compres- sion "levels". -C compression_level Select the integer compression level used to parameterize the cho- sen compression algorithm. For any given algorithm, a lesser number selects a faster compres- sion mode. A greater number selects a slower compression mode. Typically, for the same algorithm, a greater compression_level pro- vides 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 occur- rence of such block with pointer to the very first one in the out- put. Setting this option results is moderate decrease of com- pressed image size, typically around 3-5% of a final size of the compressed image. -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. [-L] Legacy flag that indicates the same thing as "-A lzma". -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-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 com- presses 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. 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) algo- rithm in particular. Lzma and Zstd will continue to provide better compression ratios as cluster sizes are increased, at high enough compres- sion 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 re- quire any changes to on-disk compressed image format, however it did re- quire some matching changes to the geom_uzip(4) to handle resulting images correctly. 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 bi- nary 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), mdcon- fig(8), mount_cd9660(8) AUTHORS Maxim Sobolev <sobomax@FreeBSD.org> FreeBSD ports 15.quarterly August 9, 2019 MKUZIP(8)
NAME | SYNOPSIS | DESCRIPTION | IMPLEMENTATION NOTES | EXIT STATUS | EXAMPLES | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=mkuzip&sektion=8&manpath=FreeBSD+15.1-RELEASE+and+Ports.quarterly>