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

   1         SQUASHFS 4.1 - A squashed read-only filesystem for Linux
   2
   3         Copyright 2002-2010 Phillip Lougher <phillip@lougher.demon.co.uk>
   4
   5         Released under the GPL licence (version 2 or later).
   6
   7 Welcome to Squashfs 4.1.  This is a tools only release, support for Squashfs
   8 file systems is in mainline (2.6.29 and later).
   9
  10 New features in Squashfs-tools 4.1
  11 ----------------------------------
  12
  13   1. Support for extended attributes
  14   2. Support for LZMA and LZO compression
  15   3. New pseudo file features
  16
  17 Compatiblity
  18 ------------
  19
  20 Mksquashfs 4.1 generates 4.0 filesystems.  These filesystems are fully
  21 compatible/interchangable with filesystems generated by Mksquashfs 4.0 and are
  22 mountable on 2.6.29 and later kernels.
  23
  24 Extended attributes (xattrs)
  25 ----------------------------
  26
  27 Squashfs file systems now have extended attribute support.  The
  28 extended attribute implementation has the following features:
  29
  30 1. Layout can store up to 2^48 bytes of compressed xattr data.
  31 2. Number of xattrs per inode unlimited.
  32 3. Total size of xattr data per inode 2^48 bytes of compressed data.
  33 4. Up to 4 Gbytes of data per xattr value.
  34 5. Inline and out-of-line xattr values supported for higher performance
  35    in xattr scanning (listxattr & getxattr), and to allow xattr value
  36    de-duplication.
  37 6. Both whole inode xattr duplicate detection and individual xattr value
  38    duplicate detection supported.  These can obviously nest, file C's
  39    xattrs can be a complete duplicate of file B, and file B's xattrs
  40    can be a partial duplicate of file A.
  41 7. Xattr name prefix types stored, allowing the redundant "user.", "trusted."
  42    etc. characters to be eliminated and more concisely stored.
  43 8. Support for files, directories, symbolic links, device nodes, fifos
  44    and sockets.
  45
  46 Extended attribute support is in 2.6.35 and later kernels.  File systems
  47 with extended attributes can be mounted on 2.6.29 and later kernels, the
  48 extended attributes will be ignored with a warning.
  49
  50 LZMA and LZO compression
  51 ------------------------
  52
  53 Squashfs now supports LZMA and LZO compression.
  54
  55 LZO support is in 2.6.36 and newer kernels.  LZMA is not yet in mainline.
  56
  57 New Mksquashfs options
  58 ----------------------
  59
  60 -comp <comp>
  61
  62     Select <comp> compression.
  63
  64     The compression algorithms supported by the build of Mksquashfs can be
  65     found by typing mksquashfs without any arguments.  The compressors available
  66     are displayed at the end of the help message, e.g.
  67
  68     Compressors available:
  69         gzip (default)
  70         lzma
  71         lzo
  72
  73     The default compression used when -comp isn't specified on the command line
  74     is indicated by "(default)".
  75
  76 -no-xattrs
  77     Don't store extended attributes
  78
  79 -xattrs
  80     Store extended attributes
  81
  82     The default behaviour of Mksquashfs with respect to extended attribute
  83     storage is build time selectable.  The Mksquashfs help message indicates
  84     whether extended attributes are stored or not, e.g.
  85
  86         -no-xattrs              don't store extended attributes
  87         -xattrs                 store extended attributes (default)
  88
  89     shows that extended attributes are stored by default, and can be disabled
  90     by the -no-xattrs option.
  91
  92         -no-xattrs              don't store extended attributes (default)
  93         -xattrs                 store extended attributes
  94
  95     shows that extended attributes are not stored by default, storage can be
  96     enabled by the -xattrs option.
  97
  98
  99 -noX
 100 -noXattrCompression
 101     Don't compress extended attributes
 102
 103
 104 New Unsquashfs options
 105 ----------------------
 106
 107 -n[o-xattrs]
 108     Don't extract xattrs in filesystem
 109
 110 -x[attrs]
 111     Extract xattrs in filesystem
 112
 113     The default behaviour of Unsquashfs with respect to extended attributes
 114     is build time selectable.  The Unsquashfs help message indicates whether
 115     extended attributes are stored or not, e.g.
 116
 117         -no[-xattrs]            don't extract xattrs in file system
 118         -x[attrs]               extract xattrs in file system (default)
 119
 120     shows that xattrs are extracted by default.
 121
 122         -no[-xattrs]            don't extract xattrs in file system (default)
 123         -x[attrs]               extract xattrs in file system
 124
 125     shows that xattrs are not extracted by default.
 126
 127
 128 New pseudo file support
 129 -----------------------
 130
 131 Mksquashfs supports pseudo files, these allow fake files, directories, character
 132 and block devices to be specified and added to the Squashfs filesystem being
 133 built, rather than requiring them to be present in the source directories.
 134 This, for example, allows device nodes to be added to the filesystem without
 135 requiring root access.
 136
 137 Mksquashfs 4.1 adds support for "dynamic pseudo files" and a modify operation.
 138 Dynamic pseudo files allow files to be dynamically created when Mksquashfs
 139 is run, their contents being the result of running a command or piece of
 140 shell script.  The modifiy operation allows the mode/uid/gid of an existing
 141 file in the source filesystem to be modified.
 142
 143 Two Mksquashfs options are supported, -p allows one pseudo file to be specified
 144 on the command line, and -pf allows a pseudo file to be specified containing a
 145 list of pseduo definitions, one per line.
 146
 147 Pseudo operations
 148 -----------------
 149
 150 1. Creating a dynamic file
 151 --------------------------
 152
 153 Pseudo definition
 154
 155 Filename f mode uid gid command
 156
 157 mode is the octal mode specifier, similar to that expected by chmod.
 158
 159 uid and gid can be either specified as a decimal number, or by name.
 160
 161 command can be an executable or a piece of shell script, and it is executed
 162 by running "/bin/sh -c command".   The stdout becomes the contents of
 163 "Filename".
 164
 165 Examples:
 166
 167 Running a basic command
 168 -----------------------
 169
 170 /somedir/dmesg f 444 root root dmesg
 171
 172 creates a file "/somedir/dmesg" containing the output from dmesg.
 173
 174 Executing shell script
 175 ----------------------
 176
 177 RELEASE f 444 root root \
 178                 if [ ! -e /tmp/ver ]; then \
 179                         echo 0 > /tmp/ver; \
 180                 fi; \
 181                 ver=`cat /tmp/ver`; \
 182                 ver=$((ver +1)); \
 183                 echo $ver > /tmp/ver; \
 184                 echo -n `cat /tmp/release`; \
 185                 echo "-dev #"$ver `date` "Build host" `hostname`
 186
 187 Creates a file RELEASE containing the release name, date, build host, and
 188 an incrementing version number.  The incrementing version is a side-effect
 189 of executing the shell script, and ensures every time Mksquashfs is run a
 190 new version number is used without requiring any other shell scripting.
 191
 192 The above example also shows that commands can be split across multiple lines
 193 using "\".  Obviously as the script will be presented to the shell as a single
 194 line, a semicolon is need to separate individual shell commands within the
 195 shell script.
 196
 197 Reading from a device (or fifo/named socket)
 198 --------------------------------------------
 199
 200 input f 444 root root dd if=/dev/sda1 bs=1024 count=10
 201
 202 Copies 10K from the device /dev/sda1 into the file input.  Ordinarily Mksquashfs
 203 given a device, fifo, or named socket will place that special file within the
 204 Squashfs filesystem, the above allows input from these special files to be
 205 captured and placed in the Squashfs filesystem.
 206
 207 2. Creating a block or character device
 208 ---------------------------------------
 209
 210 Pseudo definition
 211
 212 Filename type mode uid gid major minor
 213
 214 Where type is either
 215         b - for block devices, and
 216         c - for character devices
 217
 218 mode is the octal mode specifier, similar to that expected by chmod.
 219
 220 uid and gid can be either specified as a decimal number, or by name.
 221
 222 For example:
 223
 224 /dev/chr_dev c 666 root root 100 1
 225 /dev/blk_dev b 666 0 0 200 200
 226
 227 creates a character device "/dev/chr_dev" with major:minor 100:1 and
 228 a block device "/dev/blk_dev" with major:minor 200:200, both with root
 229 uid/gid and a mode of rw-rw-rw.
 230
 231 3. Creating a directory
 232 -----------------------
 233
 234 Pseudo definition
 235
 236 Filename d mode uid gid
 237
 238 mode is the octal mode specifier, similar to that expected by chmod.
 239
 240 uid and gid can be either specified as a decimal number, or by name.
 241
 242 For example:
 243
 244 /pseudo_dir d 666 root root
 245
 246 creates a directory "/pseudo_dir" with root uid/gid and mode of rw-rw-rw.
 247
 248 4. Modifying attributes of an existing file
 249 -------------------------------------------
 250
 251 Pseudo definition
 252
 253 Filename m mode uid gid
 254
 255 mode is the octal mode specifier, similar to that expected by chmod.
 256
 257 uid and gid can be either specified as a decimal number, or by name.
 258
 259 For example:
 260
 261 dmesg m 666 root root
 262
 263 Changes the attributes of the file "dmesg" in the filesystem to have
 264 root uid/gid and a mode of rw-rw-rw, overriding the attributes obtained
 265 from the source filesystem.