mksquashfsimg

Syntax:

mksquashfsimg [-?] [-D] [-d] [-f path] [-h] [-l inputline] [-n[n...]]
              [-o directory] [-p patchfile] [-r rootdir] [-v[v...]]
              [buildfile] [directory] [outputfile]
mkxfs -t squash [-?] [-D] [-d] [-f path] [-h] [-l inputline] [-n[n...]]
                [-o directory] [-p patchfile] [-r rootdir] [-v[v...]]
                [buildfile] [directory] [outputfile]

Runs on:

Linux, Microsoft Windows

Options:

-?

Display a usage message.

-D

Throw errors for undeclared intermediate directories.

-d

Display warnings for undeclared intermediate directories.

-f path

Output a list of all elements in the target filesystem to the specified path. Each line has the form:

target-path uid:gid mode(octal) size [SHA256]

-h

Import hard links from the host filesystem as hard links. The default behavior is to create copies of the linked files.

-l inputline

Prefix inputline to the buildfile. The input line should be quoted to prevent interpretation by the shell (as input lines often contain spaces). Multiple -l options are processed in the order specified. No default. This option is especially useful for setting global attributes when the input is a directory only.

-n[n...]

Don't use timestamps. This allows for identical binary-formatted images. One -n strips timestamps from files that vary from run to run. More than one -n strips ALL time information, which is necessary on Windows NTFS with daylight savings time.

-o directory

Use the specified directory for all permanent build artifacts other than the output image itself.

-p patchfile

Apply patching instructions from this file. (See "Patchfiles", below.)

-r rootdir

Add the standard search paths for binaries under rootdir to the MKIFS_PATH environment variable. To make mksquashfsimg behave like mkifs when searching for files, you must add [search=${MKIFS_PATH}] near the beginning of your buildfile, and define the PROCESSOR and PROCESSOR_BASE environment variables.

-v[v...]

Operate verbosely. Specifying additional -v options increases verbosity. Default is quiet operation.

Description:

The mksquashfsimg utility reads a text buildfile and/or a specified directory and produces a binary image file containing a SquashFS filesystem created from the given input. You can copy this file to target media at a later stage.

Input and output are specified on the command line:

buildfile: The filename of the buildfile that describes the contents of the SquashFS filesystem; use a hyphen (-) to specify standard input (the default).
directory: The root of a directory hierarchy to be appended to the file list specified in buildfile (if any). The default is no directory.
outputfile: The filename of the image file containing the SquashFS filesystem; use a hyphen (-) to specify standard output (the default). Note that you can specify the outputfile only if you specified either a buildfile or a directory.

If you don't specify either a buildfile or a directory, a buildfile is expected as input from standard input. The output is always an image file; if you don't specify outputfile, image-file data is produced on standard output.

Buildfiles

The mksquashfsimg utility uses the same buildfile grammar as mkifs, but supports a different set of attributes. The buildfile is basically a list of files that you want to be included in the filesystem image file when it is built by mksquashfsimg. In addition to the files to include, you can specify various attributes that set filesystem parameters. For example, you can specify the filesystem block size, or the user and group IDs of the individual files.

You can use a backslash (\) to break long lines into smaller ones.

In a buildfile, a pound sign (#) indicates a comment; anything between it and the end of the line is ignored. There must be a space between a buildfile command and the pound sign.

Each line is in the form:

[attributes] file_specification

where the attributes (with the enclosing square brackets) and the file specification are both optional. The specified attributes apply to every item in the buildfile unless a specific filename is also given for file_specification.

Attributes provide information about the file following the attribute. They are enclosed in square brackets; when combining attributes (e.g., to specify both the user ID and the group ID), enclose both attribute tokens in the same pair of square brackets. For example:

# correct way
[uid=5 gid=5] filename

# incorrect way
[uid=5] [gid=5] filename

There are two types of attributes:

boolean attributes: Those prefixed with a plus (+) or minus (-) sign.
value attributes: Those ending with an equals sign (=) followed by a value. Don't put any spaces around the equals sign.

A question mark (?) before an attribute makes the setting conditional. The attribute is set only if it hasn't already been set. For example, ?+dupignore sets the +dupignore attribute only if +dupignore or -dupignore hasn't already been set. You can find the attribute descriptions under Attributes, after Patchfiles.

The file_specification that follows the attributes takes one of these forms:

path: The path is the same on the host as in the image.
target_path=host_path: The specified file or contents of the specified directory are fetched from the host filesystem and placed into the image at the specified target location.
target_path={contents}: An inline definition. The contents of the file are listed within the buildfile itself, enclosed in braces ({ }); the file doesn't exist on the host system anywhere. The contents of the inline file can't be on the same line as the opening or closing brace.; The mksquashfsimg utility doesn't parse the contents of an inline file for anything but the closing brace. For example, mksquashfsimg doesn't interpret a pound sign (#) in an inline file as the beginning of a comment. The syntax of the inline file depends on what it's used for on the target system. Closing braces (}) and backslashes (\) in an inline file must be escaped with a backslash.

If the value of file_specification includes spaces or unusual characters, you can enclose it in double quotes ("").

Patchfiles

Patchfiles allow you to override the user ID, group ID, and permissions of certain files, depending on their location and filename pattern. Since patches are applied after all files have been collected (from the buildfile and/or the specified directory), patchfiles can override settings specified in the buildfile.

Patchfiles must only contain lines of the form:

#comment

or:

type:path:pattern:uid:gid:perms

In comment lines, a pound sign (#) must be the very first character. The entire line is regarded as a comment and is ignored.

The type is either d or f, optionally followed by r. Type d patches are applied only to directories, and type f patches are applied only to files. If you improperly specify a path (e.g., you provide a directory entry but with an f type), the patching isn't done for that path. An r indicates that the patch should be applied recursively within path; without r, the patch is applied to path only.

The pattern is a filename pattern that specifies which files to apply the patch to. The user ID and group ID must be decimal numbers, while perms must be an octal number (see chmod). Note that it isn't possible to set only the user ID, group ID, or permissions; for each match, all three are affected.

Attributes

The mksquashfsimg command supports the following attributes:

The following attributes are recognized, but ignored by mksquashfsimg:

mountperms=perm_spec

An OR-bar indicates that either the first element or the second element must be present, but not both (e.g., +|-dupignore means either +dupignore or -dupignore, but not +-dupignore).

blksize attribute

blksize=size_spec

Set the filesystem's block size. The block size must be a power of two in the range of 4k to 1M. The default value is 128k. You can specify this value as a number with one of the following suffixes: k, K, m, M.

cd attribute

cd=path

Set the current working directory to the specified pathname before attempting to open the host file. Default is the directory from which mksquashfsimg was invoked.

compressor attribute

compressor=compressor_spec

For compressor, specify one of the following values:

none
gzip[,compression_level[,window_size[,strategy...]]]
lzo[,algorithm[,level]]
lz4[,compression_level]
xz[,dictionary_size[,executable_filter...]]
zstd[,compression_level]

Currently supported values are none, gzip, lzo, lz4, xz and zstd. The default is xz.

The compressor options listed below can also be specified along with its compressor value.

The none option is only intended for debugging and testing purposes; it is not supported by the SquashFS filesystem. Because of this, none acts like a ZSTD compression for which none of the blocks could be compressed.

Supported compressor options:

none

No options available.

gzip

The compression_level value must be in the range [1..9]. The default is 9.

The window_size value must be in the range [8..15]. The default is 15.

The strategy value must be one or more of:

dflt = Default
fltr = Filtered
huff = Huffman only
rle = Run Length Encoded
fix = Fixed

If multiple strategies are specified, mksquashfsimg tries each one of them and chooses the one with the smallest output.

lzo

The algorithm value must be one of:

1 (LZO1X_1)
11 (LZO1X_1_11)
12 (LZO1X_1_12)
15 (LZO1X_1_15)
999 (LZO1X_999)

Default is 999.

The compression level is level. It is only valid for 999 and must be in the range of 0 to 9. The default is 8.

lz4

If set, compression_level indicates the use of High Compression (HC) mode. The value must be in the range of 3 to 12.

xz

The dictionary_size value is the size of the LZMA2 dictionary to use. Larger dictionaries generally yield better sizes. The value must be in the range [8k..blksize].

The executable_filter value must be one or more of:

x86 = Intel X86
ppc = PowerPC
ia64 = Intel Itanium Architecture
arm = ARM
thumb = ARM Thumb
sparc = Sparc

All specified filters are applied to each data block; the one yielding the smallest output is selected.

zstd

The compression_level value must be in the range of 1 to 22. The default is 3.

compress_data attribute

+|-compress_data

If set, mksquashfsimg compresses file data. Default is +compress_data.

compress_frags attribute

+|-compress_frags

If set, mksquashfsimg compresses fragment metadata. Default is +compress_frags.

compress_ids attribute

+|-compress_ids

If set, mksquashfsimg compresses user ID and group ID metadata. Default is +compress_ids.

compress_inodes attribute

+|-compress_inodes

If set, mksquashfsimg compresses inodes metadata. Default is +compress_inodes.

compress_xattr attribute

+|-compress_xattr

If set, mksquashfsimg compresses extended attributes metadata. Default is +compress_xattr.

dperms attribute

dperms=dperms_spec

Set the access permissions of the directory. The dperms_spec value can be one of the following:

a number (just as with the chmod command)
an asterisk (*) to use the host directory's permissions; for an inline directory, the permissions are 0755 (rwxr-xr-x)

a symbolic mode string to delete, add, or set permissions. This string is similar (but not identical) to chmod's and is as follows (with spaces added for clarity):

[who] operator permissions[, ...]

The components are as follows:

who

Either none of or a combination of the following:


Character	Meaning
u	User
g	Group
o	Others
a	All (the default if you don't specify `who`)

operator

One of the following:


Character	Meaning
-	Delete the specified permissions
=	Explicitly set the permissions
+	Add the specified permissions

permissions

A combination of one or more of the following:


Character	Meaning
r	Read permission
w	Write permission
x	Execute permission, or search permission for directories
s	When executed, set the user ID
g	When executed, set the group ID
t	Sticky bit

You can include multiple symbolic mode strings, separating them with commas (,).

The default dperms_spec is an asterisk (*).

Note:

When running on a Windows host, mksquashfsimg might guess at the permissions, so you should use the dperms attribute to specify them explicitly. You might also have to use the uid and gid attributes to set the ownership correctly.

dupignore attribute

+|-dupignore

Specify whether mksquashfsimg should ignore duplicate file entries. When buildfiles are defined from templates by external tools, or when the content is split across multiple files that are then combined with the include attribute, there might be multiple entries defining the same target path. Enabling this attribute (+dupignore) allows you to continue using your buildfile structures when you can't change some parts of the image specification and might have to handle duplicate file entries.

If this attribute is undefined for a file entry, the default value is disabled (-dupignore).

If a file entry is found to have the same target path as another, already parsed entry, then:

if both entries have -dupignore (either because it's explicitly set or the default value is used), mksquashfsimg reports an error and exits
if only one of the entries has +dupignore, mksquashfsimg ignores it and includes the other entry in building the image
if both entries have +dupignore, the entry defined earlier in the buildfile is included and the entry defined later is ignored

When an entry is ignored, mksquashfsimg reports it if the verbosity level is greater than one (e.g., if -vv is used).

For file entries to be considered duplicates, the target path is the only thing that must match. Other attributes that affect files, such as uid, gid, and perms can differ, but the dupignore settings in effect for any entries containing a given target path determine which entry gets included in the image. It's up to the buildfile writer or systems integrator who generates the target image to ensure that what's included at a given target path has all the appropriate attribute settings.

You can use this attribute to override any default file entry for a particular target path. Suppose you generate a buildfile by using a utility such as mkqnximage, which enables dupignore globally at the beginning of the buildfile. You can manually specify an entry for the target path of interest with this attribute disabled, as follows:

[-dupignore] sshd = path/to/sshd

Because it's only this sshd entry that doesn't allow duplicates, this file will be taken irrespective of where it's listed in the buildfile.

This attribute is handy also if you're using an existing buildfile that defines dupignore for specific files but not globally, and you want to prepend some entries to its files list (e.g., to keep all the entries you manually added in one place, for readability). Suppose the file enables this attribute, and defines others, for a particular target path:

[+dupignore, uid=0] xyz = /etc/abc

If you want to leave the existing content intact but use a different host file with different ownership settings for the same target path, you can add the following entry early in the buildfile, above the existing files list:

[+dupignore, uid=1] xyz = /vars/def

Because both entries for the target path xyz have dupignore enabled, the earlier entry is included in the image. In this case, the file will be the one taken from the host location of /vars/def and its uid will be 1.

In this last example, the two host files specified for the common target location are not identical, but again, the target path is the only thing that determines whether their entries are duplicates.

exportable attribute

+|-exportable

If set, mksquashfsimg adds an inode mapping table to the image that makes the filesystem exportable via NFS. Default is -exportable.

followlink attribute

[+|-followlink] target_path=host_path

If you specify +followlink or omit it, mksquashfsimg follows any links and makes target_path a copy of host_path. If you specify -followlink, mksquashfsimg creates a symbolic link called target_path that points to whatever host_path points at. It's up to you to make sure that the file pointed to is available in the target path name space.

fragments attribute

+|-fragments

If set, mksquashfsimg stores files smaller than a filesystem block and partial blocks at the end of files in so-called "fragment" blocks. Using this mechanism does not necessarily reduce the size of the image or improve access speed. The default is +fragments.

gid attribute

gid=id_spec

Set the group ID number for the file. The value of this attribute may be either a number or an asterisk (*). If it's an asterisk, the group ID is taken from the host file; for an inline file, the group ID is the group of the user running mksquashfsimg. The default value for this attribute is an asterisk (*).

include attribute (boolean)

+|-include

Include files as part of the buildfile being processed. You can apply this attribute to a single file:

[+include] buildfile_path

or as a global attribute:

[+include]
buildfile_path_1
buildfile_path_2
...
buildfile_path_n
[-include]

You can specify variables in the attribute's value. For information on how they're expanded (i.e., evaluated to a value used in their place), see the mkxfs section on processing variables.

Each buildfile_path can be an absolute or a relative path. If buildfile_path starts with a slash (/) on a Linux development host, or a disk volume label followed by a backslash (\) on a Windows host, it's absolute and mksquashfsimg searches for the file in that exact host location. For more details on specifying absolute paths, see the buildfile path description above. If the path starts with another character sequence, it's a relative path, and mksquashfsimg searches the following directories (in this order):

the current directory
all paths specified by search attributes
the boot/build directory under the current root (specified with the -r command-line option)
the boot/build directory under ${QNX_TARGET}/${PROCESSOR}

Note that you can't use the target=host notation for the paths.

If an include file can't be found, the result depends on the optional attribute. If +optional is set, the missing file is skipped; otherwise, mksquashfsimg terminates with an error.

Buildfiles are processed top-down, and buildfile inclusion happens in place: when an include attribute is found, the included buildfile is loaded and processed; when processing is completed, mksquashfsimg returns to the including buildfile.

You can nest buildfile inclusions, but any circular inclusion is treated as an error. For example, the inclusion hierarchy A(B(D),C(E,F)) is valid, but A(A) and A(B(C(B))) aren't. If you include a buildfile more than once (which could easily happen with nested include files), the repeated inclusion is ignored, and mksquashfsimg issues a diagnostic message.

Note:

The top buildfile together with its included buildfiles effectively form one large buildfile stream that's processed as a single buildfile would be. This means that all attribute settings in effect before an inclusion remain in effect inside the included files, and everything set in an included file is carried over into the parent buildfile.

The default is -include, which causes files (if found) to be added to the filesystem, not to the buildfile.

index attribute

+|-index

If set, mksquashfsimg generates additional directory indexes for large directories. Though these indexes take up additional space, they improve the time required to access directory entries on the target system. The default is true.

mountperms attribute

Originally supposed to set the access permissions for the filesystem mountpoint, this attribute is silently disregarded. To achieve the desired effect, set permissions directly on the filesystem's root directory instead.

mtime attribute

mtime=time_spec

Set the timestamps of the files or directories to the specified time. The time_spec must be either:

a single asterisk (*), meaning that the host file's timestamp should be used (the default behavior),
or
in a format based on ISO8601:
```
YYYY-MM-DD-HH:MM:SS
```
You must provide all six elements. The time is always interpreted as UTC.

Timestamps specified with the mtime attribute aren't affected by the -n option.

optional attribute (boolean)

+|-optional

When the host file can't be found, apply the following action:

If enabled (i.e. +optional), then output a warning and continue building the embedded filesystem.
If disabled (i.e. -optional), then output an error and exit. This is the default setting.

This attribute applies only to those items explicitly included in the buildfile.

Note:

When both [-optional] and [+followlink] apply, and a broken symbolic link is implicitly included from a directory, mksquashfsimg returns an error and exits. This is because when followlink is enabled, symbolic links should never be imported into the image.

pad attribute

pad=size

Zero-pad the output image file to an integer multiple of the given size. Default is 4k; 0 means "don't pad".

perms attribute

perms=perms_spec

Set the access permissions of the file. The perms_spec can be one of the following:

a number (just as with the chmod command)
an asterisk (*) to use the host file's permissions (or 0666 for inline files)

a symbolic mode string to delete, add, or set permissions. This string is similar (but not identical) to chmod's and is as follows (with spaces added for clarity):

[who] operator permissions[, ...]

The components are as follows:

who

A combination of zero or more of the following:


Character	Meaning
u	User
g	Group
o	Others
a	All (the default if you don't specify `who`)

operator

One of the following:


Character	Meaning
-	Delete the specified permissions
=	Explicitly set the permissions
+	Add the specified permissions

permissions

A combination of one or more of the following:


Character	Meaning
r	Read permission
w	Write permission
x	Execute permission, or search permission for directories
s	When executed, set the user ID
g	When executed, set the group ID
t	Sticky bit

You can include multiple symbolic mode strings, separating them with commas (,).

The default perms_spec is an asterisk (*).

Note:

When running on a Windows host, mksquashfsimg can't get the execute x, setuid (set user ID), or setgid (set group ID) permissions from the file. The mksquashfsimg utility might guess at the read, write, and execute permissions, so you should use the perms attribute to specify the permissions explicitly. You might also have to use the uid and gid attributes to set the ownership correctly. To determine whether or not a utility needs to have the setuid or setgid permission set, see its entry in the Utilities Reference.

prefix attribute

prefix=path

Set the prefix on the target file names. The default is an empty string.

search attribute

search=path_list

This attribute specifies that mksquashfsimg should search for the file in the named locations on the host system. The search directory portion of the host file name isn't included in the name that's stored in the SquashFS filesystem. Colon separators and forward slashes in the paths are the standard Unix conventions, but for Windows searches, you must use the standard Windows conventions, such as semicolon separators and backslashes in the paths.

Note:

To ensure that your search paths work without modification on all supported host OSs, you can use:

forward slashes (/), which are now recognized by Windows as well as Linux; it is strongly recommended to use forward slashes as directory delimiters, because backslashes may adversely affect the functionality of your buildfile.
the PFS environment variable instead of ; or : to separate multiple paths in path lists (see PFS under Environment variables below).

sparse attribute

+|-sparse

If set, mksquashfsimg detects and omits all-zero blocks in files. Default is -sparse.

store_xattr attribute

+|-store_xattr

If set, mksquashfsimg also stores files' extended attributes. Default is +store_xattr. See the description of the xattr attribute to specify extended attributes.

Note:

Currently, extended attributes are not imported from the build host, so they must be specified explicitly where required.

Note:

QNX OS doesn't currently support extended attributes, so storing them is only relevant if you plan to mount the generated filesystem under Linux.

type attribute

type=file_type

Sets the type of the files being created in the SquashFS filesystem. Allowed types are:

hlink — a hard link (see below)
link — a symbolic link
file — a regular, everyday file (the default)
dir — a directory.

Specifying [type=dir] tells mksquashfsimg to make the named file a directory; you don't need to specify the type when you're copying the contents of a directory. For example, this command:

[type=dir] /usr/bin=/usr/nto/x86/bin

marks all the contents of /usr/bin as directories. To copy /usr/nto/x86/bin to /usr/bin, you just need to specify:

/usr/bin=/usr/nto/x86/bin

Hard links must always be specified using commands of the form:

[type=hlink] link_path=target_path

where link-path is the new link to be created and target-path refers to an existing path in the SquashFS filesystem that's being created. Note that it is not possible to specify attributes like user ID, group ID, or permissions for hard links. If any of these attributes are defined together with the [type=hlink] attribute, they are silently ignored. Also, the hard link's target must not be a directory. Trying to create hard links to directories results in an error.

uid attribute

uid=id_spec

Set the user ID number for the file. The value of this attribute may be either a number or an asterisk (*). If it's an asterisk, the user ID is taken from the host file; for an inline file, the user ID is the user running mksquashfsimg. The default value for this attribute is an asterisk (*).

xattr attribute

xattr=xattr_spec[;xattr_spec...]

Specify extended attributes for a file, directory, symbolic link, or FIFO special file. Each xattr_spec takes the form

key:value

where key is a period-delimited multi-level key identifier, and value is an arbitrary string. For SquashFS, the key must begin with user., trusted., or security..

Characters in the xattr_spec list can be escaped with a backslash (\).

Example:

xattr=user.foo.bar:fizz;user.doodle:buzz

Examples:

Here's a sample buildfile, my_squashfs.bld:

  # A sample buildfile for mksquashfsimg
  [blksize=4k uid=1 gid=2]
  [type=dir] /foo=${QNX_TARGET}/usr/include

This example specifies a non-standard block_size of 4k. The files and subdirectories from the ${QNX_TARGET}/usr/include directory on the host system are recursively copied into the target directory /foo in the generated squash file system; all files and directories are owned by user 1, group 2.

To create a SquashFS image file using the above buildfile, invoke mksquashfsimg as follows:

mksquashfsimg my_squashfs.bld my_squashfs.sqi

This command creates the my_squashfs.sqi file containing a SquashFS filesystem, which can then be copied to the target system.

Environment variables:

PFS

Specifies the Path Field Separator (PFS). The mksquashfsimg utility automatically sets this variable to the character used to separate paths in path lists. That is, mksquashfsimg sets the variable to ; on a Windows host and to : on a Linux host.

To keep buildfiles host OS-independent, use this environment variable instead of the OS-specific characters; for example, instead of writing:

[search=/a/b:/x/y/z]

write:

[search=/a/b${PFS}/x/y/z]

The mksquashfsimg utility will set the environment variable to the path separator appropriate for the host platform.

Exit status:

0: Successful completion.
1: An error occurred.