SQUASHFS/squashfs-tools-4.4/RELEASE-READMEs/README-4.3

   1         SQUASHFS 4.3 - A squashed read-only filesystem for Linux
   2
   3         Copyright 2002-2014 Phillip Lougher <phillip@lougher.demon.co.uk>
   4
   5         Released under the GPL licence (version 2 or later).
   6
   7 Welcome to Squashfs 4.3.  This is the first release in over 3 years, and
   8 there are substantial improvements to stability, new compression options
   9 and compressors, speed optimisations, and new options for Mksquashfs/Unsquashfs.
  10
  11 This is a tools only release, support for Squashfs filesystems is
  12 in mainline (2.6.29 and later).
  13
  14 Changes in Squashfs-tools 4.3
  15 -----------------------------
  16
  17 1. Stability improvements.  Better checking of user input for out of
  18    range/invalid values.  Better handling of corrupted Squashfs filesystems
  19    (Mksquashfs append mode, and Unsquashfs).  Better handling of buffer
  20    overflow/underflow.
  21
  22 2. GZIP compressor now supports compression options, allowing different
  23    compression levels to be used.
  24
  25 3. Rewritten LZO compressor with compression options, allowing different
  26    LZO algorithms and different compression levels to be used.
  27
  28 4. New LZ4 compressor (note not yet in mainline kernel)
  29
  30 5. Better default memory usage for Mksquashfs.  Mksquashfs by default now
  31    uses 25% of physical memory.
  32
  33 6. Duplicate checking in Mksquashfs further optimised.  With certain
  34    "problem filesystems" greater than 2x performance improvement.
  35    Filesystems with a lot of duplicates should see at least 10-20% speed
  36    improvement.
  37
  38 7. The -stat option in Unsquashfs now displays the compression options
  39    used to generate the original filesystem.  Previously -stat only displayed
  40    the compression algorithm used.
  41
  42 8. The file being compressed/uncompressed in Mksquashfs/Unsquashfs is now
  43    displayed if CTRL-\ (SIGQUIT from keyboard) typed.
  44
  45 9. The status of the internal queues/caches in Mksquashfs/Unsquashfs is
  46    now displayed if CTRL-\ (SIGQUIT from keyboard) is typed twice within
  47    one second.  Normally only useful for "power users", but it can be
  48    used to discover if there's any bottlenecks affecting performance
  49    (the bottleneck will normally be the compressors/fragment compressors).
  50
  51 10. Miscellaneous new options for Mksquashfs/Unsquashfs to fine tune behaviour.
  52
  53 11. Fixes for CVE-2012-4024 and CVE-2012-4025.
  54
  55 Compatiblity
  56 ------------
  57
  58 Mksquashfs 4.3 generates 4.0 filesystems.  These filesystems are fully
  59 compatible/interchangable with filesystems generated by Mksquashfs 4.0 and are
  60 mountable on 2.6.29 and later kernels.
  61
  62 Compressors
  63 -----------
  64
  65 New compression options and compressors are now supported.
  66
  67 The new options and compressors are:
  68
  69 1. gzip
  70           -Xcompression-level <compression-level>
  71                 <compression-level> should be 1 .. 9 (default 9)
  72           -Xwindow-size <window-size>
  73                 <window-size> should be 8 .. 15 (default 15)
  74           -Xstrategy strategy1,strategy2,...,strategyN
  75                 Compress using strategy1,strategy2,...,strategyN in turn
  76                 and choose the best compression.
  77                 Available strategies: default, filtered, huffman_only,
  78                 run_length_encoded and fixed
  79
  80 2. lzo
  81           -Xalgorithm <algorithm>
  82                 Where <algorithm> is one of:
  83                         lzo1x_1
  84                         lzo1x_1_11
  85                         lzo1x_1_12
  86                         lzo1x_1_15
  87                         lzo1x_999 (default)
  88           -Xcompression-level <compression-level>
  89                 <compression-level> should be 1 .. 9 (default 8)
  90                 Only applies to lzo1x_999 algorithm
  91
  92 3. lz4
  93           -Xhc
  94                 Compress using LZ4 High Compression
  95
  96 The compression specific options are, obviously, specific to the compressor
  97 in question, and you should read the compressor documentation and check
  98 their web sites to understand their behaviour.
  99
 100 In general the defaults used by Mksquashfs for each compressor are optimised
 101 to give the best performance for each compressor, where what constitutes
 102 best depends on the compressor.  For gzip/xz best means highest compression
 103 (trying multiple filters/strategies can improve compression, but this is
 104 extremely expensive computationally, and hence, not suitable for the defaults),
 105 for LZO/LZ4 best means a tradeoff between compression and (de)-compression
 106 overhead (LZO/LZ4 by definition are intended for weaker processors).
 107
 108 New Mksquashfs options
 109 ----------------------
 110
 111 1. -mem <size>
 112
 113   Set the amount of memory used by Mksquashfs to <size> bytes.  G/M and K
 114   post-fixes are supported.
 115
 116   By default Mksquashfs uses 25% of the physical memory.  Increasing
 117   this with the -mem option can increase performance (note it does not have
 118   any effect on compression).  Reducing it can prevent thrashing if the
 119   system is busy and there is not 25% of physical memory free (again, note
 120   it does not have any effect on compression).
 121
 122 2. -exit-on-error
 123
 124   By default Mksquashfs treats certain errors as benign, if these
 125   errors occur Mksquashfs prints the error on the console but continues.
 126   These errors are typically failure to read a file from the source filesystem.
 127   This is deliberate, in many cases users prefer Mksquashfs to flag
 128   the error but continue rather than abort what may be hours of compression.
 129
 130   But there are times where failure to read any file is considered critical,
 131   and users (especially in the case of automated scripts where the
 132   errors output to the console may be missed) prefer Mksquashfs to exit.
 133
 134   The new -exit-on-error option can be used in this scenario.  This option
 135   makes Mksquashfs treat all benign errors as fatal.
 136
 137 3. -progress
 138
 139   By default if -info is specified, the progress bar is disabled as it gets
 140   in the way.  Occasionally you might want the progress bar enabled whilst
 141   -info is enabled.  This option forces Mksquashfs to output the progress
 142   bar when -info is specified.
 143
 144 4. -Xhelp
 145
 146   Display the usage text for the currently selected compressor.
 147
 148 New Unsquashfs options
 149 ----------------------
 150
 151 1. -u[ser-xattrs]
 152
 153   Only write user xattrs.  This forces Unsquashfs to ignore system xattrs.
 154   This is useful when Unsquashing a filesystem as a non-root user, and the
 155   filesystem contains system xattrs which are only writable by root.
 156
 157 Major bugs fixed
 158 ----------------
 159
 160 1. If Mksquashfs ran out of space in the destination filesystem, this
 161    would not cause Mksquashfs to immediately abort, and Mksquashfs would
 162    continue to process the source filesystem.  Mksquashfs now immediately
 163    aborts on out of space in the destination filesystem.
 164
 165 2. Unsquashfs ignored the maximum number of open files limit, and if that
 166    was lower than the default limit for Linux, it would run out of file
 167    descriptors.  Unsquashfs now limits the number of open files to the
 168    limit currently in force (e.g. specified by setrlimit).
 169
 170 3. If huge numbers of dynamic pseudo files were specified, Mksquashfs
 171    could exceed the maximum number of open files limit.  This was because
 172    Mksquashfs created all the dynamic file processes up front before
 173    commencing source filesystem reading and compression.  Mksquashfs
 174    now creates the dynamic file processes on demand whilst reading
 175    and compressing the source filesystem, thus limiting the number of
 176    dynamic pseudo file processes in existence at any one time.
 177
 178 4. When outputting Unsquashfs used to set the permissions of directories
 179    as it recursively descended.  This in hindsight had an obvious oversight,
 180    if a directory had only read permission (or was otherwise restricted), then
 181    Unsquashfs would fail to write its contents when descending into it.  Fixed
 182    by setting directory permissions as Unsquashfs recursively unwinds.