Provided by: squashfs-tools-ng_1.2.0-1_amd64 
NAME
gensquashfs - generate squashfs images
SYNOPSIS
gensquashfs [OPTIONS] <squashfs-file>
DESCRIPTION
Generate a SquashFS image.
OPTIONS
--pack-file, -F <file>
Use a gen_init_cpio style description file. The file format is specified below. If --pack-dir is
used, input file paths are relative to the pack directory, otherwise they are relative to the
directory the pack file is in.
--pack-dir, -D <directory>
If --pack-file is used, this is the root path relative to which to read files. If no pack file is
specified, pack the contents of the given directory into a SquashFS image. The directory becomes
the root of the file system.
--sort-file, -S <file>
Specify a file that can override the order in which input files are packed, or affect packing
behaviour (e.g. disable compression or fragmentation for certain files).
--compressor, -c <name>
Select the compressor to use. Run gensquashfs --help to get a list of all available compressors
and the default selection.
--comp-extra, -X <options>
A comma separated list of extra options for the selected compressor. Specify help to get a list of
available options.
--num-jobs, -j <count>
If libsquashfs was compiled with a built in thread pool based, parallel data compressor, this
option can be used to set the number of compressor threads. If not set, the default is the number
of available CPU cores.
--queue-backlog, -Q <count>
Maximum number of data blocks in the thread worker queue before the packer starts waiting for the
block processors to catch up. Higher values result in higher memory consumption. Defaults to 10
times the number of workers.
--block-size, -b <size>
Block size to use for Squashfs image. Defaults to 131072.
--dev-block-size, -B <size>
Device block size to padd the image to. Defaults to 4096.
--keep-time, -k
When using --pack-dir only, use the timestamps from the input files instead of setting defaults on
all input paths. The root inode and the modification time on the SquashFS image itself will still
be set to defaults.
--one-file-system, -o
When using --pack-dir only, stay in the local filesystem and do not cross mount points.
--defaults, -d <options>
A comma separated list of default values for implicitly created directories. The following values
can be set:
┌───────────────┬────────────────────────────────────────┐
│ Option │ Default │
├───────────────┼────────────────────────────────────────┤
│ uid=<value> │ 0 │
├───────────────┼────────────────────────────────────────┤
│ gid=<value> │ 0 │
├───────────────┼────────────────────────────────────────┤
│ mode=<value> │ 0755 │
├───────────────┼────────────────────────────────────────┤
│ mtime=<value> │ $SOURCE_DATE_EPOCH if set, 0 otherwise │
└───────────────┴────────────────────────────────────────┘
--set-uid, -u <number>
Force the owners user ID for ALL inodes to this value, no matter what the pack file or directory
entries actually specify.
--set-gid, -g <number>
Force the owners group ID for ALL inodes to this value, no matter what the pack file or directory
entries actually specify.
--all-root
A short hand for `--set-uid 0 --set-gid 0`.
--selinux, -s <file>
If built with SELinux support, use the given SELinux label file to add context labels to the
elements packed into the SquashFS image.
--xattr-file, -A <file>
Read extended attributes from a file. The format for the file is identical to the output generated
by `getfattr --dump`.
--exportable, -e
Generate an export table for NFS support.
--no-tail-packing, -T
Do not perform tail end packing on files that are larger than the specified block size.
--force, -f
Overwrite the output file if it exists.
--quiet, -q
Do not print out progress reports.
--help, -h
Print help text and exit.
--version, -V
Print version information and exit.
PACK FILE FORMAT
The input file contains a simple, newline separated list that describe the files to be included in the
squashfs image:
# a comment
file <path> <mode> <uid> <gid> [<location>]
dir <path> <mode> <uid> <gid>
nod <path> <mode> <uid> <gid> <dev_type> <maj> <min>
slink <path> <mode> <uid> <gid> <target>
link <path> <dummy> <dummy> <dummy> <target>
pipe <path> <mode> <uid> <gid>
sock <path> <mode> <uid> <gid>
glob <path> <mode|*> <uid|*> <gid|*> [OPTIONS...] <location>
┌────────────┬────────────────────────────────────────┐
│ <path> │ Absolute path of the entry in the │
│ │ image. Can be put in quotes if some │
│ │ components contain spaces. │
├────────────┼────────────────────────────────────────┤
│ <location> │ Optional location of the input file. │
│ │ Can be specified relative to either │
│ │ the description file or the pack │
│ │ directory. If omitted, the image path │
│ │ is used as a relative path. │
├────────────┼────────────────────────────────────────┤
│ <target> │ Symlink or hardlink target. │
├────────────┼────────────────────────────────────────┤
│ <mode> │ Mode/permissions of the entry. │
├────────────┼────────────────────────────────────────┤
│ <uid> │ Numeric user id. │
├────────────┼────────────────────────────────────────┤
│ <gid> │ Numeric group id. │
├────────────┼────────────────────────────────────────┤
│ <dev_type> │ Device type (b=block, c=character). │
├────────────┼────────────────────────────────────────┤
│ <maj> │ Major number of a device special file. │
├────────────┼────────────────────────────────────────┤
│ <min> │ Minor number of a device special file. │
└────────────┴────────────────────────────────────────┘
File Globbing
The glob command requires an input location which is interpreted relative to the pack directory (or the
input file if no directory was specified). This location is scanned recursively and the contents are
added to the specified virtual path.
The specified mode, uid and gid are applied to all new entries added by the glob. They can alternatively
be set to the special value * to use the value from the input directory.
In front of the source location, several additional options can be specified to control the behavior of
the glob command:
┌─────────────────┬────────────────────────────────────────────────────┐
│ Option │ Description │
├─────────────────┼────────────────────────────────────────────────────┤
│ -type │ Followed by a single space and a single, lowercase │
│ │ character describing the inode type to accept. │
│ │ Works similar to the -type option of the find │
│ │ command. │
│ │ │
│ │ Possible values are b (block devices), c │
│ │ (character devices), d (directories), p (named │
│ │ pipes), f (regular files), l (symlinks) and s │
│ │ (sockets). │
│ │ │
│ │ If -type is not used, all are accepted. The first │
│ │ use clamps the selection down to a single type and │
│ │ subsequent uses allow additional types. │
├─────────────────┼────────────────────────────────────────────────────┤
│ -xdev │ Do not cross mount points during a recursive glob. │
├─────────────────┼────────────────────────────────────────────────────┤
│ -mount │ An alias for -xdev │
├─────────────────┼────────────────────────────────────────────────────┤
│ -keeptime │ Use the time stamps from the scanned files. │
├─────────────────┼────────────────────────────────────────────────────┤
│ -nonrecursive │ Do not descend into directories. │
│ │ │
│ │ Even if the type argument does not include │
│ │ directories, it is still possible to recursively │
│ │ scan a hierarchy. In that case, the scanning will │
│ │ not add new directory nodes, but still recurse │
│ │ into a directory if a coresponding node already │
│ │ exist in the virtual filesystem tree. │
│ │ │
│ │ So a typicall use case might be to first scan only │
│ │ the directories, and then do several narrower │
│ │ globs to fill them. │
├─────────────────┼────────────────────────────────────────────────────┤
│ -name <pattern> │ Only add entries if their name matches a shell │
│ │ glob pattern. │
│ │ │
│ │ If the pattern is supposed to contain spaces, it │
│ │ can be wrapped in quotation marks ("..." or │
│ │ '...'). │
├─────────────────┼────────────────────────────────────────────────────┤
│ -path <pattern> │ Only add entries if their full resulting path in │
│ │ the SquashFS image matches a shell glob pattern. │
│ │ Slashes in the path are only matched against │
│ │ slashes in the pattern and will never match a wild │
│ │ card character or a bracket expression containing │
│ │ a slash. │
│ │ │
│ │ The path is normalized, so it won't have a leading │
│ │ or trailing slash. │
└─────────────────┴────────────────────────────────────────────────────┘
Any other, unknown string starting with - will be rejected as unknown option. If the input path starts
with -, the sequence -- can be used to stop argument parsing, similar to many command line tools.
Example
# A simple squashfs image
dir /dev 0755 0 0
nod /dev/console 0600 0 0 c 5 1
dir /root 0700 0 0
dir /sbin 0755 0 0
# Add a file. Input is relative to pack dir or listing path
file /sbin/init 0755 0 0 ../init/sbin/init
# Read from ./bin/bash relative to pack dir or listing path
# /bin is created implicitly with default attributes.
file /bin/bash 0755 0 0
# file name with a space in it and a "special" name
file "/opt/my app/\"special\"/data" 0600 0 0
# collect the contents of ./lib and put it under /usr/lib
# mode and uid/gid are explictly set. First we collect the directory tree,
# then all so files, then all symlinks that don't end in ".so"
glob /usr/lib 0755 0 0 -type d ./lib
glob /usr/lib 0755 0 0 -type f -name "*.so.*" ./lib
glob /usr/lib 0777 0 0 -type l -name "*.so.*" ./lib
SORT FILE FORMAT
The sort file is has one entry per line, consisting of a numeric priority and a filename. The name and
the priority are separated by one or more space character (including tabs) and the line can be intended.
Any leeding or preceeding spaces are dropped.
The priority is a 64 bit number and can be negative. Files not listed in the sort file receive a default
priority of 0. After processing the sort file, before packing the input files, the file list is sorted by
priority, with lower values preceeding larger ones.
The given filename is matched against the actual path of the file in the SquashFS file in the resulting
image. It is not matched against the input path, which may differ. Any file is allowed to match only
once. The first match encountered in the sort file will be used.
Lines can be empty or contain a single line comment, started with #. Filenames can be wrapped can be
wrapped in quotation marks ("...") if necessary, with \ serving as an escape character for quotation
marks or itself.
To control the packing behavior, an optional list of flags can be inserted between the priority and the
filename. The flags are wrappe in brackets and comma separated, e.g. [flag1,flag2,...]. The following
flags are supported:
┌──────────────────┬───────────────────────────────────────┐
│ Flag │ Description │
├──────────────────┼───────────────────────────────────────┤
│ glob │ Interpret the filename as a shell │
│ │ glob pattern and match all files that │
│ │ the pattern applies to. This performs │
│ │ path globbing, i.e. a wild card │
│ │ character (* or ?) or a bracket range │
│ │ ([]) cannot match a path separator. A │
│ │ slash must always be matched by an │
│ │ explicit slash. │
├──────────────────┼───────────────────────────────────────┤
│ glob_no_path │ Same as glob, but disables path │
│ │ globbing. Wild cards are allowed to │
│ │ match slashes. │
├──────────────────┼───────────────────────────────────────┤
│ align │ Force device block alignment of the │
│ │ matched files, i.e. the compressed │
│ │ output always starts at a multiple of │
│ │ the device block size. Padding is │
│ │ inserted before and after. │
├──────────────────┼───────────────────────────────────────┤
│ dont_fragment │ Do not perform tail-end packing for │
│ │ the matched files, always generate a │
│ │ sequence of independent blocks. │
├──────────────────┼───────────────────────────────────────┤
│ dont_compress │ Do not compress the matched files. │
│ │ Note that if tail-end packing is │
│ │ performed, the entire fragment block │
│ │ is left uncompressed. │
├──────────────────┼───────────────────────────────────────┤
│ dont_deduplicate │ Do not perform deduplication on the │
│ │ matched files. If they are packed and │
│ │ the data blocks or the tail end │
│ │ happens to match a previously packed │
│ │ file, keep them anyway. │
├──────────────────┼───────────────────────────────────────┤
│ nosparse │ Do not perform sparse file detection. │
│ │ If a matched file contians block of │
│ │ zero bytes, pack them as-is. │
└──────────────────┴───────────────────────────────────────┘
Example
# Specify a packing order with file globbing
-8000 [glob] bin/*
-5000 [glob] lib/*
# glob_no_path means * is allowed to match /
-1000 [glob_no_path] share/*
# Our boot loader needs this
-100000 [dont_compress,dont_fragment,nosparse] boot/vmlinuz
# For demonstration, a quoted filename and no flags
1337 "usr/share/my \"special\" file "
XATTR FILE FORMAT
The format for xattr files tries to be identical to the output of getfattr.
Attributes are listed as key-value pairs with an = sign in between.
If a line starts with `# file: `, the rest of the line is interpreted as an absolute path that the
following xattrs are applied to.
Plain text values are wrapped in quotation marks ("...") and support some escape sequences. Currently
supported are \", \\ and \0<octal-sequence>.
Raw binary values can encoded as hexadecimal or base64, by starting the value with a 0x or 0s prefix
respectively.
Example
# file: dev/
security.selinux="system_u:object_r:device_t:s0"
user.beverage_preference=0xCAFECAFEDECAFBAD
# file: dev/rfkill
security.selinux="system_u:object_r:wireless_device_t:s0"
system.posix_acl_access=0sSGVsbG8gdGhlcmUgOi0pCg==
ENVIRONMENT
If the command line switch --defaults is not used or no default mtime is specified, the value of the
environment variable SOURCE_DATE_EPOCH is used for all file and filesystem timestamps.
If SOURCE_DATE_EPOCH is not set, not a parsable number or it is out of range, the timestamps default to
0.
Environment variables are only used if no explicit command line switches are set. Explicit command line
switches are always preferred over the environment variables.
SEE ALSO
rdsquashfs(1), tar2sqfs(1)
AUTHOR
Written by David Oberhollenzer.
COPYRIGHT
Copyright © 2019 David Oberhollenzer License GPLv3+: GNU GPL version 3 or later
<https://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent
permitted by law.
generate squashfs images November 2021 GENSQUASHFS(1)