xref: /aosp_15_r20/external/squashfs-tools/RELEASE-READMEs/README-4.1 (revision 79398b2563bcbbbab54656397863972d8fa68df1)

	SQUASHFS 4.1 - A squashed read-only filesystem for Linux

	Copyright 2002-2010 Phillip Lougher <[email protected]>

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

Welcome to Squashfs 4.1.  This is a tools only release, support for Squashfs
file systems is in mainline (2.6.29 and later).

New features in Squashfs-tools 4.1
----------------------------------

  1. Support for extended attributes
  2. Support for LZMA and LZO compression
  3. New pseudo file features

Compatiblity
------------

Mksquashfs 4.1 generates 4.0 filesystems.  These filesystems are fully
compatible/interchangable with filesystems generated by Mksquashfs 4.0 and are
mountable on 2.6.29 and later kernels.

Extended attributes (xattrs)
----------------------------

Squashfs file systems now have extended attribute support.  The
extended attribute implementation has the following features:

1. Layout can store up to 2^48 bytes of compressed xattr data.
2. Number of xattrs per inode unlimited.
3. Total size of xattr data per inode 2^48 bytes of compressed data.
4. Up to 4 Gbytes of data per xattr value.
5. Inline and out-of-line xattr values supported for higher performance
   in xattr scanning (listxattr & getxattr), and to allow xattr value
   de-duplication.
6. Both whole inode xattr duplicate detection and individual xattr value
   duplicate detection supported.  These can obviously nest, file C's
   xattrs can be a complete duplicate of file B, and file B's xattrs
   can be a partial duplicate of file A.
7. Xattr name prefix types stored, allowing the redundant "user.", "trusted."
   etc. characters to be eliminated and more concisely stored.
8. Support for files, directories, symbolic links, device nodes, fifos
   and sockets.

Extended attribute support is in 2.6.35 and later kernels.  File systems
with extended attributes can be mounted on 2.6.29 and later kernels, the
extended attributes will be ignored with a warning.

LZMA and LZO compression
------------------------

Squashfs now supports LZMA and LZO compression.

LZO support is in 2.6.36 and newer kernels.  LZMA is not yet in mainline.

New Mksquashfs options
----------------------

-comp <comp>

    Select <comp> compression.

    The compression algorithms supported by the build of Mksquashfs can be
    found by typing mksquashfs without any arguments.  The compressors available
    are displayed at the end of the help message, e.g.

    Compressors available:
	gzip (default)
	lzma
	lzo

    The default compression used when -comp isn't specified on the command line
    is indicated by "(default)".

-no-xattrs
    Don't store extended attributes

-xattrs
    Store extended attributes

    The default behaviour of Mksquashfs with respect to extended attribute
    storage is build time selectable.  The Mksquashfs help message indicates
    whether extended attributes are stored or not, e.g.

	-no-xattrs		don't store extended attributes
	-xattrs			store extended attributes (default)

    shows that extended attributes are stored by default, and can be disabled
    by the -no-xattrs option.

	-no-xattrs		don't store extended attributes (default)
	-xattrs			store extended attributes

    shows that extended attributes are not stored by default, storage can be
    enabled by the -xattrs option.


-noX
-noXattrCompression
    Don't compress extended attributes


New Unsquashfs options
----------------------

-n[o-xattrs]
    Don't extract xattrs in filesystem

-x[attrs]
    Extract xattrs in filesystem

    The default behaviour of Unsquashfs with respect to extended attributes
    is build time selectable.  The Unsquashfs help message indicates whether
    extended attributes are stored or not, e.g.

	-no[-xattrs]		don't extract xattrs in file system
	-x[attrs]		extract xattrs in file system (default)

    shows that xattrs are extracted by default.

	-no[-xattrs]		don't extract xattrs in file system (default)
	-x[attrs]		extract xattrs in file system

    shows that xattrs are not extracted by default.


New pseudo file support
-----------------------

Mksquashfs supports pseudo files, these allow fake files, directories, character
and block devices to be specified and added to the Squashfs filesystem being
built, rather than requiring them to be present in the source directories.
This, for example, allows device nodes to be added to the filesystem without
requiring root access.

Mksquashfs 4.1 adds support for "dynamic pseudo files" and a modify operation.
Dynamic pseudo files allow files to be dynamically created when Mksquashfs
is run, their contents being the result of running a command or piece of
shell script.  The modifiy operation allows the mode/uid/gid of an existing
file in the source filesystem to be modified.

Two Mksquashfs options are supported, -p allows one pseudo file to be specified
on the command line, and -pf allows a pseudo file to be specified containing a
list of pseduo definitions, one per line.

Pseudo operations
-----------------

1. Creating a dynamic file
--------------------------

Pseudo definition

Filename f mode uid gid command

mode is the octal mode specifier, similar to that expected by chmod.

uid and gid can be either specified as a decimal number, or by name.

command can be an executable or a piece of shell script, and it is executed
by running "/bin/sh -c command".   The stdout becomes the contents of
"Filename".

Examples:

Running a basic command
-----------------------

/somedir/dmesg f 444 root root dmesg

creates a file "/somedir/dmesg" containing the output from dmesg.

Executing shell script
----------------------

RELEASE f 444 root root \
		if [ ! -e /tmp/ver ]; then \
			echo 0 > /tmp/ver; \
		fi; \
                ver=`cat /tmp/ver`; \
                ver=$((ver +1)); \
                echo $ver > /tmp/ver; \
                echo -n `cat /tmp/release`; \
                echo "-dev #"$ver `date` "Build host" `hostname`

Creates a file RELEASE containing the release name, date, build host, and
an incrementing version number.  The incrementing version is a side-effect
of executing the shell script, and ensures every time Mksquashfs is run a
new version number is used without requiring any other shell scripting.

The above example also shows that commands can be split across multiple lines
using "\".  Obviously as the script will be presented to the shell as a single
line, a semicolon is need to separate individual shell commands within the
shell script.

Reading from a device (or fifo/named socket)
--------------------------------------------

input f 444 root root dd if=/dev/sda1 bs=1024 count=10

Copies 10K from the device /dev/sda1 into the file input.  Ordinarily Mksquashfs
given a device, fifo, or named socket will place that special file within the
Squashfs filesystem, the above allows input from these special files to be
captured and placed in the Squashfs filesystem.

2. Creating a block or character device
---------------------------------------

Pseudo definition

Filename type mode uid gid major minor

Where type is either
	b - for block devices, and
	c - for character devices

mode is the octal mode specifier, similar to that expected by chmod.

uid and gid can be either specified as a decimal number, or by name.

For example:

/dev/chr_dev c 666 root root 100 1
/dev/blk_dev b 666 0 0 200 200

creates a character device "/dev/chr_dev" with major:minor 100:1 and
a block device "/dev/blk_dev" with major:minor 200:200, both with root
uid/gid and a mode of rw-rw-rw.

3. Creating a directory
-----------------------

Pseudo definition

Filename d mode uid gid

mode is the octal mode specifier, similar to that expected by chmod.

uid and gid can be either specified as a decimal number, or by name.

For example:

/pseudo_dir d 666 root root

creates a directory "/pseudo_dir" with root uid/gid and mode of rw-rw-rw.

4. Modifying attributes of an existing file
-------------------------------------------

Pseudo definition

Filename m mode uid gid

mode is the octal mode specifier, similar to that expected by chmod.

uid and gid can be either specified as a decimal number, or by name.

For example:

dmesg m 666 root root

Changes the attributes of the file "dmesg" in the filesystem to have
root uid/gid and a mode of rw-rw-rw, overriding the attributes obtained
from the source filesystem.