usr.bin/mkuzip/mkuzip.8

   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
  35 class
  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
  44 The
  45 .Nm
  46 utility compresses a disk image file so that the
  47 .Xr geom_uzip 4
  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
  51 time it is read.
  52 The
  53 .Nm
  54 utility
  55 works in two phases:
  56 .Bl -enum
  57 .It
  58 An
  59 .Ar infile
  60 image is split into clusters; each cluster is compressed using
  61 .Xr zlib 3
  62 or
  63 .Xr lzma 3 .
  64 .It
  65 The resulting set of compressed clusters along with headers that allow
  66 locating each individual cluster is written to the output file.
  67 .El
  68 .Pp
  69 The options are:
  70 .Bl -tag -width indent
  71 .It Fl j Ar compression_jobs
  72 Specify the number of compression jobs that
  73 .Nm
  74 runs in parallel to speed up compression.
  75 When option is not specified the number of jobs set to be equal
  76 to the value of
  77 .Va hw.ncpu
  78 .Xr sysctl 8
  79 variable.
  80 .It Fl d
  81 Enable de-duplication.
  82 When the option is enabled the
  83 .Nm
  84 detects identical blocks in the input and replaces each subsequent occurence
  85 of such block with pointer to the very first one in the output.
  86 Setting this option results is moderate decrease of compressed image size,
  87 typically around 3-5% of a final size of the compressed image.
  88 .It Fl L
  89 Use
  90 .Xr lzma 3
  91 compression algorithm instead of the default
  92 .Xr zlib 3 .
  93 The
  94 .Xr lzma 3
  95 provides noticeable better compression levels on the same data set
  96 at the expense of much slower compression speed (10-20x) and somewhat slower
  97 decompression (2-3x).
  98 .It Fl o Ar outfile
  99 Name of the output file
 100 .Ar outfile .
 101 The default is to use the input name with the suffix
 102 .Pa .uzip
 103 for the
 104 .Xr zlib 3
 105 compression or
 106 .Pa .ulzma
 107 for the
 108 .Xr lzma 3 .
 109 .It Fl S
 110 Print summary about the compression ratio as well as output
 111 file size after file has been processed.
 112 .It Fl s Ar cluster_size
 113 Split the image into clusters of
 114 .Ar cluster_size
 115 bytes, 16384 bytes by default.
 116 The
 117 .Ar cluster_size
 118 should be a multiple of 512 bytes.
 119 .It Fl v
 120 Display verbose messages.
 121 .It Fl Z
 122 Disable zero-blocks detection and elimination.
 123 When this option is set, the
 124 .Nm
 125 would compress empty blocks (i.e. clusters that consist of only zero bytes)
 126 just as it would any other block.
 127 When the option is not set, the
 128 .Nm
 129 detects such blocks and skips them from the output.
 130 Setting
 131 .Fl Z
 132 results is slight increase of compressed image size, typically less than 0.1%
 133 of a final size of the compressed image.
 134 .El
 135 .Sh NOTES
 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
 142 .Xr gzip 1 .
 143 However, it should be kept in mind that larger cluster
 144 sizes lead to higher overhead in the
 145 .Xr geom_uzip 4
 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.
 148 .Pp
 149 The
 150 .Nm
 151 utility
 152 inserts a short shell script at the beginning of the generated image,
 153 which makes it possible to
 154 .Dq run
 155 the image just like any other shell script.
 156 The script tries to load the
 157 .Xr geom_uzip 4
 158 class if it is not loaded, configure the image as an
 159 .Xr md 4
 160 disk device using
 161 .Xr mdconfig 8 ,
 162 and automatically mount it using
 163 .Xr mount_cd9660 8
 164 on the mount point provided as the first argument to the script.
 165 .Pp
 166 The de-duplication is a
 167 .Fx
 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
 170 .Xr geom_uzip 4
 171 to 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