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.Ar infile 42.Sh DESCRIPTION 43The 44.Nm 45utility compresses a disk image file so that the 46.Xr geom_uzip 4 47class will be able to decompress the resulting image at run-time. 48This allows for a significant reduction of size of disk image at 49the expense of some CPU time required to decompress the data each 50time it is read. 51The 52.Nm 53utility 54works in two phases: 55.Bl -enum 56.It 57An 58.Ar infile 59image is split into clusters; each cluster is compressed using 60.Xr zlib 3 61or 62.Xr lzma 3 . 63.It 64The resulting set of compressed clusters along with headers that allow 65locating each individual cluster is written to the output file. 66.El 67.Pp 68The options are: 69.Bl -tag -width indent 70.It Fl o Ar outfile 71Name of the output file 72.Ar outfile . 73The default is to use the input name with the suffix 74.Pa .uzip 75for the 76.Xr zlib 3 77compression or 78.Pa .ulzma 79for the 80.Xr lzma 3 . 81.It Fl L 82Use 83.Xr lzma 3 84compression algorithm instead of the default 85.Xr zlib 3 . 86The 87.Xr lzma 3 88provides noticeable better compression levels on the same data set 89at the expense of much slower compression speed (10-20x) and somewhat slower 90decompression (2-3x). 91.It Fl s Ar cluster_size 92Split the image into clusters of 93.Ar cluster_size 94bytes, 16384 bytes by default. 95The 96.Ar cluster_size 97should be a multiple of 512 bytes. 98.It Fl v 99Display verbose messages. 100.It Fl Z 101Disable zero-blocks detection and elimination. 102When this option is set, the 103.Nm 104would compress empty blocks (i.e. clusters that consist of only zero bytes) 105just as it would any other block. 106When the option is not set, the 107.Nm 108detects such blocks and skips them from the output. 109Setting 110.Fl Z 111results is slight increase of compressed image size, typically less than 0.1% 112of a final size of the compressed image. 113.It Fl d 114Enable de-duplication. 115When the option is enabled the 116.Nm 117detects identical blocks in the input and replaces each subsequent occurence 118of such block with pointer to the very first one in the output. 119Setting this option results is moderate decrease of compressed image size, 120typically around 3-5% of a final size of the compressed image. 121.It Fl S 122Print summary about the compression ratio as well as output 123file size after file has been processed. 124.El 125.Sh NOTES 126The compression ratio largely depends on the cluster size used. 127.\" The following two sentences are unclear: how can gzip(1) be 128.\" used in a comparable fashion, and wouldn't a gzip-compressed 129.\" image suffer from larger cluster sizes as well? 130For large cluster sizes (16K and higher), typical compression ratios 131are only 1-2% less than those achieved with 132.Xr gzip 1 . 133However, it should be kept in mind that larger cluster 134sizes lead to higher overhead in the 135.Xr geom_uzip 4 136class, as the class has to decompress the whole cluster even if 137only a few bytes from that cluster have to be read. 138.Pp 139The 140.Nm 141utility 142inserts a short shell script at the beginning of the generated image, 143which makes it possible to 144.Dq run 145the image just like any other shell script. 146The script tries to load the 147.Xr geom_uzip 4 148class if it is not loaded, configure the image as an 149.Xr md 4 150disk device using 151.Xr mdconfig 8 , 152and automatically mount it using 153.Xr mount_cd9660 8 154on the mount point provided as the first argument to the script. 155.Pp 156The de-duplication is a 157.Fx 158specific feature and while it does not require any changes to on-disk 159compressed image format, however it did require some matching changes to the 160.Xr geom_uzip 4 161to handle resulting images correctly. 162.Sh EXIT STATUS 163.Ex -std 164.Sh SEE ALSO 165.Xr gzip 1 , 166.Xr xz 1 , 167.Xr zlib 3 , 168.Xr lzma 3 , 169.Xr geom 4 , 170.Xr geom_uzip 4 , 171.Xr md 4 , 172.Xr mdconfig 8 , 173.Xr mount_cd9660 8 174.Sh AUTHORS 175.An Maxim Sobolev Aq Mt sobomax@FreeBSD.org 176