1.\"- 2.\" Copyright (c) 2004-2016 Maxim Sobolev <sobomax@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd February 19, 2019 29.Dt MKUZIP 8 30.Os 31.Sh NAME 32.Nm mkuzip 33.Nd compress disk image for use with 34.Xr geom_uzip 4 35class 36.Sh SYNOPSIS 37.Nm 38.Op Fl dLSsvZ 39.Op Fl j Ar compression_jobs 40.Op Fl o Ar outfile 41.Op Fl s Ar cluster_size 42.Ar infile 43.Sh DESCRIPTION 44The 45.Nm 46utility compresses a disk image file so that the 47.Xr geom_uzip 4 48class will be able to decompress the resulting image at run-time. 49This allows for a significant reduction of size of disk image at 50the expense of some CPU time required to decompress the data each 51time it is read. 52The 53.Nm 54utility 55works in two phases: 56.Bl -enum 57.It 58An 59.Ar infile 60image is split into clusters; each cluster is compressed using 61.Xr zlib 3 62or 63.Xr lzma 3 . 64.It 65The resulting set of compressed clusters along with headers that allow 66locating each individual cluster is written to the output file. 67.El 68.Pp 69The options are: 70.Bl -tag -width indent 71.It Fl j Ar compression_jobs 72Specify the number of compression jobs that 73.Nm 74runs in parallel to speed up compression. 75When option is not specified the number of jobs set to be equal 76to the value of 77.Va hw.ncpu 78.Xr sysctl 8 79variable. 80.It Fl d 81Enable de-duplication. 82When the option is enabled the 83.Nm 84detects identical blocks in the input and replaces each subsequent occurence 85of such block with pointer to the very first one in the output. 86Setting this option results is moderate decrease of compressed image size, 87typically around 3-5% of a final size of the compressed image. 88.It Fl L 89Use 90.Xr lzma 3 91compression algorithm instead of the default 92.Xr zlib 3 . 93The 94.Xr lzma 3 95provides noticeable better compression levels on the same data set 96at the expense of much slower compression speed (10-20x) and somewhat slower 97decompression (2-3x). 98.It Fl o Ar outfile 99Name of the output file 100.Ar outfile . 101The default is to use the input name with the suffix 102.Pa .uzip 103for the 104.Xr zlib 3 105compression or 106.Pa .ulzma 107for the 108.Xr lzma 3 . 109.It Fl S 110Print summary about the compression ratio as well as output 111file size after file has been processed. 112.It Fl s Ar cluster_size 113Split the image into clusters of 114.Ar cluster_size 115bytes, 16384 bytes by default. 116The 117.Ar cluster_size 118should be a multiple of 512 bytes. 119.It Fl v 120Display verbose messages. 121.It Fl Z 122Disable zero-blocks detection and elimination. 123When this option is set, the 124.Nm 125would compress empty blocks (i.e. clusters that consist of only zero bytes) 126just as it would any other block. 127When the option is not set, the 128.Nm 129detects such blocks and skips them from the output. 130Setting 131.Fl Z 132results is slight increase of compressed image size, typically less than 0.1% 133of a final size of the compressed image. 134.El 135.Sh NOTES 136The compression ratio largely depends on the cluster size used. 137.\" The following two sentences are unclear: how can gzip(1) be 138.\" used in a comparable fashion, and wouldn't a gzip-compressed 139.\" image suffer from larger cluster sizes as well? 140For large cluster sizes (16K and higher), typical compression ratios 141are only 1-2% less than those achieved with 142.Xr gzip 1 . 143However, it should be kept in mind that larger cluster 144sizes lead to higher overhead in the 145.Xr geom_uzip 4 146class, as the class has to decompress the whole cluster even if 147only a few bytes from that cluster have to be read. 148.Pp 149The 150.Nm 151utility 152inserts a short shell script at the beginning of the generated image, 153which makes it possible to 154.Dq run 155the image just like any other shell script. 156The script tries to load the 157.Xr geom_uzip 4 158class if it is not loaded, configure the image as an 159.Xr md 4 160disk device using 161.Xr mdconfig 8 , 162and automatically mount it using 163.Xr mount_cd9660 8 164on the mount point provided as the first argument to the script. 165.Pp 166The de-duplication is a 167.Fx 168specific feature and while it does not require any changes to on-disk 169compressed image format, however it did require some matching changes to the 170.Xr geom_uzip 4 171to handle resulting images correctly. 172.Sh EXIT STATUS 173.Ex -std 174.Sh SEE ALSO 175.Xr gzip 1 , 176.Xr xz 1 , 177.Xr lzma 3 , 178.Xr zlib 3 , 179.Xr geom 4 , 180.Xr geom_uzip 4 , 181.Xr md 4 , 182.Xr mdconfig 8 , 183.Xr mount_cd9660 8 184.Sh AUTHORS 185.An Maxim Sobolev Aq Mt sobomax@FreeBSD.org 186