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
39 .Op Fl A Ar compression_algorithm
40 .Op Fl C Ar compression_level
41 .Op Fl j Ar compression_jobs
43 .Op Fl s Ar cluster_size
48 utility compresses a disk image file so that the
50 class will be able to decompress the resulting image at run-time.
51 This allows for a significant reduction of size of disk image at
52 the expense of some CPU time required to decompress the data each
62 image is split into clusters; each cluster is compressed.
64 The resulting set of compressed clusters is written to the output file.
67 header is written which allows for efficient seeking.
71 .Bl -tag -width indent
72 .It Fl A Op Ar lzma | Ar zlib | Ar zstd
73 Select a specific compression algorithm.
74 If this option is not provided, the default is
79 algorithm provides noticeable better compression levels than zlib on the same
81 It has vastly slower compression speed and moderately slower decompression
86 algorithm provides better compression levels than zlib on the same data set.
87 It also has faster compression and decompression speed than zlib.
88 In the very high compression
90 settings, it does not offer quite as high a compression ratio as
92 However, its decompression speed does not suffer at high compression
94 .It Fl C Ar compression_level
95 Select the integer compression level used to parameterize the chosen
96 compression algorithm.
98 For any given algorithm, a lesser number selects a faster compression mode.
99 A greater number selects a slower compression mode.
100 Typically, for the same algorithm, a greater
101 .Ar compression_level
102 provides better final compression ratio.
106 the range of valid compression levels is
115 the range of valid compression levels is
124 the range of valid compression levels is currently
131 Enable de-duplication.
132 When the option is enabled
134 detects identical blocks in the input and replaces each subsequent occurrence
135 of such block with pointer to the very first one in the output.
136 Setting this option results is moderate decrease of compressed image size,
137 typically around 3-5% of a final size of the compressed image.
138 .It Fl j Ar compression_jobs
139 Specify the number of compression jobs that
141 runs in parallel to speed up compression.
142 When option is not specified the number of jobs set to be equal
148 Legacy flag that indicates the same thing as
151 Name of the output file
153 The default is to use the input name with the suffix
162 Print summary about the compression ratio as well as output
163 file size after file has been processed.
164 .It Fl s Ar cluster_size
165 Split the image into clusters of
167 bytes, 16384 bytes by default.
170 should be a multiple of 512 bytes.
172 Display verbose messages.
174 Disable zero-block detection and elimination.
175 When this option is set,
177 compresses blocks of zero bytes just as it would any other block.
178 When the option is not set,
180 detects and compresses zero blocks in a space-efficient way.
183 increases compressed image sizes slightly, typically less than 0.1%.
185 .Sh IMPLEMENTATION NOTES
186 The compression ratio largely depends on the compression algorithm, level, and
188 For large cluster sizes (16kB and higher), typical overall image compression
191 are only 1-2% less than those achieved with
193 over the entire image.
194 However, it should be kept in mind that larger cluster sizes lead to higher
197 class, as the class has to decompress the whole cluster even if
198 only a few bytes from that cluster have to be read.
200 Additionally, the threshold at 16-32 kB where a larger cluster size does not
201 benefit overall compression ratio is an artifact of the
203 algorithm in particular.
206 .Ar Zstd will continue to provide better compression ratios as cluster sizes
207 are increased, at high enough compression levels.
208 The same tradeoff continues to apply: reads in
210 become more expensive the greater the cluster size.
215 inserts a short shell script at the beginning of the generated image,
216 which makes it possible to
218 the image just like any other shell script.
219 The script tries to load the
221 class if it is not loaded, configure the image as an
225 and automatically mount it using
227 on the mount point provided as the first argument to the script.
229 The de-duplication is a
231 specific feature and while it does not require any changes to on-disk
232 compressed image format, however it did require some matching changes to the
234 to handle resulting images correctly.
239 images, the kernel must be configured with
241 It is enabled by default in many
243 kernels provided as binary distributions by
245 The status on any particular system can be verified by checking
247 .Dv kern.features.geom_uzip_zstd
263 .An Maxim Sobolev Aq Mt sobomax@FreeBSD.org