	SQUASHFS 4.1 - A squashed read-only filesystem for Linux

	Copyright 2002-2010 Phillip Lougher <phillip@lougher.demon.co.uk>

	Released under the GPL licence (version 2 or later).

Welcome to Squashfs version 4.1.  Please read the README-4.1 and CHANGES files
for details of changes.

Squashfs is a highly compressed read-only filesystem for Linux.
It uses zlib compression to compress both files, inodes and directories.
Inodes in the system are very small and all blocks are packed to minimise
data overhead. Block sizes greater than 4K are supported up to a maximum
of 1Mbytes (default block size 128K).

Squashfs is intended for general read-only filesystem use, for archival
use (i.e. in cases where a .tar.gz file may be used), and in constrained
block device/memory systems (e.g. embedded systems) where low overhead is
needed.

1. SQUASHFS OVERVIEW
--------------------

1. Data, inodes and directories are compressed.

2. Squashfs stores full uid/gids (32 bits), and file creation time.

3. In theory files up to 2^64 bytes are supported.  In theory filesystems can
   be up to 2^64 bytes.

4. Inode and directory data are highly compacted, and packed on byte
   boundaries.  Each compressed inode is on average 8 bytes in length
   (the exact length varies on file type, i.e. regular file, directory,
   symbolic link, and block/char device inodes have different sizes).

5. Squashfs can use block sizes up to 1Mbyte (the default size is 128K).
   Using 128K blocks achieves greater compression ratios than the normal
   4K block size.

6. File duplicates are detected and removed.

7. Both big and little endian architectures are supported.  Squashfs can
   mount filesystems created on different byte order machines.


2. USING SQUASHFS
-----------------

Squashfs filesystems should be mounted with 'mount' with the filesystem type
'squashfs'.  If the filesystem is on a block device, the filesystem can be
mounted directly, e.g.

%mount -t squashfs /dev/sda1 /mnt

Will mount the squashfs filesystem on "/dev/sda1" under the directory "/mnt".

If the squashfs filesystem has been written to a file, the loopback device
can be used to mount it (loopback support must be in the kernel), e.g.

%mount -t squashfs image /mnt -o loop

Will mount the squashfs filesystem in the file "image" under
the directory "/mnt".


3. MKSQUASHFS
-------------

3.1 Mksquashfs options and overview.
------------------------------------

As squashfs is a read-only filesystem, the mksquashfs program must be used to
create populated squashfs filesystems.

SYNTAX:mksquashfs source1 source2 ...  dest [options] [-e list of exclude
dirs/files]

Filesystem build options:
-comp <comp>		select <comp> compression
			Compressors available:
				gzip (default)
				lzma
				lzo
-b <block_size>		set data block to <block_size>.  Default 131072 bytes
-no-exports		don't make the filesystem exportable via NFS
-no-sparse		don't detect sparse files
-no-xattrs		don't store extended attributes
-xattrs			store extended attributes (default)
-noI			do not compress inode table
-noD			do not compress data blocks
-noF			do not compress fragment blocks
-noX			do not compress extended attributes
-no-fragments		do not use fragments
-always-use-fragments	use fragment blocks for files larger than block size
-no-duplicates		do not perform duplicate checking
-all-root		make all files owned by root
-force-uid uid		set all file uids to uid
-force-gid gid		set all file gids to gid
-nopad			do not pad filesystem to a multiple of 4K
-keep-as-directory	if one source directory is specified, create a root
			directory containing that directory, rather than the
			contents of the directory

Filesystem filter options:
-p <pseudo-definition>	Add pseudo file definition
-pf <pseudo-file>	Add list of pseudo file definitions
-sort <sort_file>	sort files according to priorities in <sort_file>.  One
			file or dir with priority per line.  Priority -32768 to
			32767, default priority 0
-ef <exclude_file>	list of exclude dirs/files.  One per line
-wildcards		Allow extended shell wildcards (globbing) to be used in
			exclude dirs/files
-regex			Allow POSIX regular expressions to be used in exclude
			dirs/files

Filesystem append options:
-noappend		do not append to existing filesystem
-root-becomes <name>	when appending source files/directories, make the
			original root become a subdirectory in the new root
			called <name>, rather than adding the new source items
			to the original root

Mksquashfs runtime options:
-version		print version, licence and copyright message
-recover <name>		recover filesystem data using recovery file <name>
-no-recovery		don't generate a recovery file
-info			print files written to filesystem
-no-progress		don't display the progress bar
-processors <number>	Use <number> processors.  By default will use number of
			processors available
-read-queue <size>	Set input queue to <size> Mbytes.  Default 64 Mbytes
-write-queue <size>	Set output queue to <size> Mbytes.  Default 512 Mbytes
-fragment-queue <size>	Set fagment queue to <size> Mbytes.  Default 64 Mbytes

Miscellaneous options:
-root-owned		alternative name for -all-root
-noInodeCompression	alternative name for -noI
-noDataCompression	alternative name for -noD
-noFragmentCompression	alternative name for -noF
-noXattrCompression	alternative name for -noX

Compressors available:
	gzip (default)
	lzma
	lzo


Source1 source2 ... are the source directories/files containing the
files/directories that will form the squashfs filesystem.  If a single
directory is specified (i.e. mksquashfs source output_fs) the squashfs
filesystem will consist of that directory, with the top-level root
directory corresponding to the source directory.

If multiple source directories or files are specified, mksquashfs will merge
the specified sources into a single filesystem, with the root directory
containing each of the source files/directories.  The name of each directory
entry will be the basename of the source path.   If more than one source
entry maps to the same name, the conflicts are named xxx_1, xxx_2, etc. where
xxx is the original name.

To make this clear, take two example directories.  Source directory
"/home/phillip/test" contains  "file1", "file2" and "dir1".
Source directory "goodies" contains "goodies1", "goodies2" and "goodies3".

usage example 1:

%mksquashfs /home/phillip/test output_fs

This will generate a squashfs filesystem with root entries
"file1", "file2" and "dir1".

example 2:

%mksquashfs /home/phillip/test goodies output_fs

This will create a squashfs filesystem with the root containing
entries "test" and "goodies" corresponding to the source
directories "/home/phillip/test" and "goodies".

example 3:

%mksquashfs /home/phillip/test goodies test output_fs

This is the same as the previous example, except a third
source directory "test" has been specified.  This conflicts
with the first directory named "test" and will be renamed "test_1".

Multiple sources allow filesystems to be generated without needing to
copy all source files into a common directory.  This simplifies creating
filesystems.

The -keep-as-directory option can be used when only one source directory
is specified, and you wish the root to contain that directory, rather than
the contents of the directory.  For example:

example 4:

%mksquashfs /home/phillip/test output_fs -keep-as-directory

This is the same as example 1, except for -keep-as-directory.
This will generate a root directory containing directory "test",
rather than the "test" directory contents "file1", "file2" and "dir1".

The Dest argument is the destination where the squashfs filesystem will be
written.  This can either be a conventional file or a block device.  If the file
doesn't exist it will be created, if it does exist and a squashfs
filesystem exists on it, mksquashfs will append.  The -noappend option will
write a new filesystem irrespective of whether an existing filesystem is
present.

3.2 Changing compression defaults used in mksquashfs
----------------------------------------------------

There are a large number of options that can be used to control the 
compression in mksquashfs.  By and large the defaults are the most
optimum settings and should only be changed in exceptional circumstances!

The -noI, -noD and -noF options (also -noInodeCompression, -noDataCompression
and -noFragmentCompression) can be used to force mksquashfs to not compress
inodes/directories, data and fragments respectively.  Giving all options
generates an uncompressed filesystem.

The -no-fragments tells mksquashfs to not generate fragment blocks, and rather
generate a filesystem similar to a Squashfs 1.x filesystem.  It will of course
still be a Squashfs 3.1 filesystem but without fragments, and so it won't be
mountable on a Squashfs 1.x system.

The -always-use-fragments option tells mksquashfs to always generate
fragments for files irrespective of the file length.  By default only small
files less than the block size are packed into fragment blocks.  The ends of
files which do not fit fully into a block, are NOT by default packed into
fragments.  To illustrate this, a 100K file has an initial 64K block and a 36K
remainder.  This 36K remainder is not packed into a fragment by default.  This
is because to do so leads to a 10 - 20% drop in sequential I/O performance, as a
disk head seek is needed to seek to the initial file data and another disk seek
is need to seek to the fragment block.  Specify this option if you want file
remainders to be packed into fragment blocks.  Doing so may increase the
compression obtained BUT at the expense of I/O speed.

The -no-duplicates option tells mksquashfs to not check the files being
added to the filesystem for duplicates.  This can result in quicker filesystem
generation and appending although obviously compression will suffer badly if
there is a lot of duplicate files.

The -b option allows the block size to be selected, both "K" and "M" postfixes
are supported, this can be either 4K, 8K, 16K, 32K, 64K, 128K, 256K, 512K or
1M bytes.

3.3 Specifying the UIDs/GIDs used in the filesystem
---------------------------------------------------

By default files in the generated filesystem inherit the UID and GID ownership
of the original file.  However,  mksquashfs provides a number of options which
can be used to override the ownership.

The options -all-root and -root-owned (both do exactly the same thing) force all
file uids/gids in the generated Squashfs filesystem to be root.  This allows
root owned filesystems to be built without root access on the host machine.

The "-force-uid uid"  option forces all files in the generated Squashfs
filesystem to be owned by the specified uid.  The uid can be specified either by
name (i.e. "root") or by number.

The "-force-gid gid" option forces all files in the generated Squashfs
filesystem to be group owned by the specified gid.  The gid can be specified
either by name (i.e. "root") or by number.

3.4 Excluding files from the filesystem
---------------------------------------

The -e and -ef options allow files/directories to be specified which are
excluded from the output filesystem.  The -e option takes the exclude
files/directories from the command line, the -ef option takes the
exlude files/directories from the specified exclude file, one file/directory
per line.

Two styles of exclude file matching are supported: basic exclude matching, and
extended wildcard matching.  Basic exclude matching is a legacy feature
retained for backwards compatibility with earlier versions of Mksquashfs.
Extended wildcard matching should be used in preference.

3.4.1 Basic exclude matching

Each exclude file is treated as an exact match of a file/directory in
the source directories.  If an exclude file/directory is absolute (i.e.
prefixed with /, ../, or ./) the entry is treated as absolute, however, if an
exclude file/directory is relative, it is treated as being relative to each of
the sources in turn, i.e.

%mksquashfs /tmp/source1 source2  output_fs -e ex1 /tmp/source1/ex2 out/ex3

Will generate exclude files /tmp/source1/ex2, /tmp/source1/ex1, source2/ex1,
/tmp/source1/out/ex3 and source2/out/ex3.

3.4.2 Extended exclude file handling

Extended exclude file matching treats each exclude file as a wildcard or
regex expression.  To enable wildcard matching specify the -wildcards
option, and to enable regex matching specify the -regex opt                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              