2 .\" Copyright (c) 2004-2016 Maxim Sobolev <sobomax@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
33 .Nd compress disk image for use with
40 .Op Fl s Ar cluster_size
41 .Op Fl j Ar compression_jobs
46 utility compresses a disk image file so that the
48 class will be able to decompress the resulting image at run-time.
49 This allows for a significant reduction of size of disk image at
50 the expense of some CPU time required to decompress the data each
60 image is split into clusters; each cluster is compressed using
65 The resulting set of compressed clusters along with headers that allow
66 locating each individual cluster is written to the output file.
70 .Bl -tag -width indent
72 Name of the output file
74 The default is to use the input name with the suffix
85 compression algorithm instead of the default
89 provides noticeable better compression levels on the same data set
90 at the expense of much slower compression speed (10-20x) and somewhat slower
92 .It Fl s Ar cluster_size
93 Split the image into clusters of
95 bytes, 16384 bytes by default.
98 should be a multiple of 512 bytes.
100 Display verbose messages.
102 Disable zero-blocks detection and elimination.
103 When this option is set, the
105 would compress empty blocks (i.e. clusters that consist of only zero bytes)
106 just as it would any other block.
107 When the option is not set, the
109 detects such blocks and skips them from the output.
112 results is slight increase of compressed image size, typically less than 0.1%
113 of a final size of the compressed image.
115 Enable de-duplication.
116 When the option is enabled the
118 detects identical blocks in the input and replaces each subsequent occurence
119 of such block with pointer to the very first one in the output.
120 Setting this option results is moderate decrease of compressed image size,
121 typically around 3-5% of a final size of the compressed image.
123 Print summary about the compression ratio as well as output
124 file size after file has been processed.
125 .It Fl j Ar compression_jobs
126 Specify the number of compression jobs that
128 runs in parallel to speed up compression.
129 When option is not specified the number of jobs set to be equal
136 The 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?
140 For large cluster sizes (16K and higher), typical compression ratios
141 are only 1-2% less than those achieved with
143 However, it should be kept in mind that larger cluster
144 sizes lead to higher overhead in the
146 class, as the class has to decompress the whole cluster even if
147 only a few bytes from that cluster have to be read.
152 inserts a short shell script at the beginning of the generated image,
153 which makes it possible to
155 the image just like any other shell script.
156 The script tries to load the
158 class if it is not loaded, configure the image as an
162 and automatically mount it using
164 on the mount point provided as the first argument to the script.
166 The de-duplication is a
168 specific feature and while it does not require any changes to on-disk
169 compressed image format, however it did require some matching changes to the
171 to handle resulting images correctly.
185 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org