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 March 17, 2006 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 v 39.Op Fl o Ar outfile 40.Op Fl s Ar cluster_size 41.Op Fl j Ar compression_jobs 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 o Ar outfile 72Name of the output file 73.Ar outfile . 74The default is to use the input name with the suffix 75.Pa .uzip 76for the 77.Xr zlib 3 78compression or 79.Pa .ulzma 80for the 81.Xr lzma 3 . 82.It Fl L 83Use 84.Xr lzma 3 85compression algorithm instead of the default 86.Xr zlib 3 . 87The 88.Xr lzma 3 89provides noticeable better compression levels on the same data set 90at the expense of much slower compression speed (10-20x) and somewhat slower 91decompression (2-3x). 92.It Fl s Ar cluster_size 93Split the image into clusters of 94.Ar cluster_size 95bytes, 16384 bytes by default. 96The 97.Ar cluster_size 98should be a multiple of 512 bytes. 99.It Fl v 100Display verbose messages. 101.It Fl Z 102Disable zero-blocks detection and elimination. 103When this option is set, the 104.Nm 105would compress empty blocks (i.e. clusters that consist of only zero bytes) 106just as it would any other block. 107When the option is not set, the 108.Nm 109detects such blocks and skips them from the output. 110Setting 111.Fl Z 112results is slight increase of compressed image size, typically less than 0.1% 113of a final size of the compressed image. 114.It Fl d 115Enable de-duplication. 116When the option is enabled the 117.Nm 118detects identical blocks in the input and replaces each subsequent occurence 119of such block with pointer to the very first one in the output. 120Setting this option results is moderate decrease of compressed image size, 121typically around 3-5% of a final size of the compressed image. 122.It Fl S 123Print summary about the compression ratio as well as output 124file size after file has been processed. 125.It Fl j Ar compression_jobs 126Specify the number of compression jobs that 127.Nm 128runs in parallel to speed up compression. 129When option is not specified the number of jobs set to be equal 130to the value of 131.Va hw.ncpu 132.Xr sysctl 8 133variable. 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 zlib 3 , 178.Xr lzma 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