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
7Welcome to Squashfs 4.1.  This is a tools only release, support for Squashfs
8file systems is in mainline (2.6.29 and later).
9
10New 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
17Compatiblity
18------------
19
20Mksquashfs 4.1 generates 4.0 filesystems.  These filesystems are fully
21compatible/interchangable with filesystems generated by Mksquashfs 4.0 and are
22mountable on 2.6.29 and later kernels.
23
24Extended attributes (xattrs)
25----------------------------
26
27Squashfs file systems now have extended attribute support.  The
28extended attribute implementation has the following features:
29
301. Layout can store up to 2^48 bytes of compressed xattr data.
312. Number of xattrs per inode unlimited.
323. Total size of xattr data per inode 2^48 bytes of compressed data.
334. Up to 4 Gbytes of data per xattr value.
345. 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.
376. 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.
417. Xattr name prefix types stored, allowing the redundant "user.", "trusted."
42   etc. characters to be eliminated and more concisely stored.
438. Support for files, directories, symbolic links, device nodes, fifos
44   and sockets.
45
46Extended attribute support is in 2.6.35 and later kernels.  File systems
47with extended attributes can be mounted on 2.6.29 and later kernels, the
48extended attributes will be ignored with a warning.
49
50LZMA and LZO compression
51------------------------
52
53Squashfs now supports LZMA and LZO compression.
54
55LZO support is in 2.6.36 and newer kernels.  LZMA is not yet in mainline.
56
57New 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
104New 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
128New pseudo file support
129-----------------------
130
131Mksquashfs supports pseudo files, these allow fake files, directories, character
132and block devices to be specified and added to the Squashfs filesystem being
133built, rather than requiring them to be present in the source directories.
134This, for example, allows device nodes to be added to the filesystem without
135requiring root access.
136
137Mksquashfs 4.1 adds support for "dynamic pseudo files" and a modify operation.
138Dynamic pseudo files allow files to be dynamically created when Mksquashfs
139is run, their contents being the result of running a command or piece of
140shell script.  The modifiy operation allows the mode/uid/gid of an existing
141file in the source filesystem to be modified.
142
143Two Mksquashfs options are supported, -p allows one pseudo file to be specified
144on the command line, and -pf allows a pseudo file to be specified containing a
145list of pseduo definitions, one per line.
146
147Pseudo operations
148-----------------
149
1501. Creating a dynamic file
151--------------------------
152
153Pseudo definition
154
155Filename f mode uid gid command
156
157mode is the octal mode specifier, similar to that expected by chmod.
158
159uid and gid can be either specified as a decimal number, or by name.
160
161command can be an executable or a piece of shell script, and it is executed
162by running "/bin/sh -c command".   The stdout becomes the contents of
163"Filename".
164
165Examples:
166
167Running a basic command
168-----------------------
169
170/somedir/dmesg f 444 root root dmesg
171
172creates a file "/somedir/dmesg" containing the output from dmesg.
173
174Executing shell script
175----------------------
176
177RELEASE 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
187Creates a file RELEASE containing the release name, date, build host, and
188an incrementing version number.  The incrementing version is a side-effect
189of executing the shell script, and ensures every time Mksquashfs is run a
190new version number is used without requiring any other shell scripting.
191
192The above example also shows that commands can be split across multiple lines
193using "\".  Obviously as the script will be presented to the shell as a single
194line, a semicolon is need to separate individual shell commands within the
195shell script.
196
197Reading from a device (or fifo/named socket)
198--------------------------------------------
199
200input f 444 root root dd if=/dev/sda1 bs=1024 count=10
201
202Copies 10K from the device /dev/sda1 into the file input.  Ordinarily Mksquashfs
203given a device, fifo, or named socket will place that special file within the
204Squashfs filesystem, the above allows input from these special files to be
205captured and placed in the Squashfs filesystem.
206
2072. Creating a block or character device
208---------------------------------------
209
210Pseudo definition
211
212Filename type mode uid gid major minor
213
214Where type is either
215	b - for block devices, and
216	c - for character devices
217
218mode is the octal mode specifier, similar to that expected by chmod.
219
220uid and gid can be either specified as a decimal number, or by name.
221
222For example:
223
224/dev/chr_dev c 666 root root 100 1
225/dev/blk_dev b 666 0 0 200 200
226
227creates a character device "/dev/chr_dev" with major:minor 100:1 and
228a block device "/dev/blk_dev" with major:minor 200:200, both with root
229uid/gid and a mode of rw-rw-rw.
230
2313. Creating a directory
232-----------------------
233
234Pseudo definition
235
236Filename d mode uid gid
237
238mode is the octal mode specifier, similar to that expected by chmod.
239
240uid and gid can be either specified as a decimal number, or by name.
241
242For example:
243
244/pseudo_dir d 666 root root
245
246creates a directory "/pseudo_dir" with root uid/gid and mode of rw-rw-rw.
247
2484. Modifying attributes of an existing file
249-------------------------------------------
250
251Pseudo definition
252
253Filename m mode uid gid
254
255mode is the octal mode specifier, similar to that expected by chmod.
256
257uid and gid can be either specified as a decimal number, or by name.
258
259For example:
260
261dmesg m 666 root root
262
263Changes the attributes of the file "dmesg" in the filesystem to have
264root uid/gid and a mode of rw-rw-rw, overriding the attributes obtained
265from the source filesystem.
266