MKSQUASHFS - Online Linux Manual Page

Section : 1
Updated : January 2023
Source : mksquashfs version 4.5.1
Note : User Commands

NAME

mksquashfs - tool to create and append to squashfs filesystems

SYNOPSIS

mksquashfs

source1 source2

...

FILESYSTEM

[

OPTIONS

]

[

-e list of exclude dirs/files

]

DESCRIPTION

Squashfs is a highly compressed read-only filesystem for Linux. It uses either gzip/xz/lzo/lz4/zstd 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.

OPTIONS

Filesystem build options:

−tar

read uncompressed tar file from standard in (stdin).

−no−strip

act like tar, and do not strip leading directories from source files.

−tarstyle

alternative name for −no−strip

−cpiostyle

act like cpio, and read files from standard in (stdin).

−cpiostyle0

like −cpiostyle

, but filenames are null terminated.

−comp

COMP

select COMP compression. Compressors available: gzip (default), lzo, lz4, xz, zstd, lzma.

−b

BLOCK_SIZE

set data block to BLOCK_SIZE. Default 128 Kbytes. Optionally a suffix of K or M can be given to specify Kbytes or Mbytes respectively.

−reproducible

build filesystems that are reproducible (default).

−not−reproducible

build filesystems that are not reproducible.

−mkfs−time

TIME

set filesystem creation timestamp to TIME, which is an unsigned 32−bit int indicating seconds since the epoch (1970−01−01).

−fstime

TIME

synonym for mkfs−time.

−all−time

TIME

set all file timestamps to TIME, which is an unsigned 32−bit int indicating seconds since the epoch (1970−01−01).

−no−exports

don't make filesystem exportable via NFS (

−tar

default).

−exports

make filesystem exportable via NFS (default).

−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.

−noId

do not compress the uid/gid table (implied by −noI

−noD

do not compress data blocks.

−noF

do not compress fragment blocks.

−noX

do not compress extended attributes.

−no−tailends

don't pack tail ends into fragments (default).

−tailends

pack tail ends into fragments.

−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.

−no−hardlinks

do not hardlink files, instead store duplicates.

−all−root

make all files owned by root.

−root−time

TIME

set root directory time to TIME.

−root−mode

MODE

set root directory permissions to octal MODE.

−root−uid

UID

set root directory owner to UID.

−root−gid

GID

set root directory group to GID.

−force−uid

UID

set all file uids to UID.

−force−gid

GID

set all file gids to GID.

−keep−as−directory

if one source directory is specified, create a root directory containing that directory, rather than the contents of the directory.

−action

ACTION@EXPRESSION

evaluate EXPRESSION on every file, and execute ACTION if it returns TRUE.

−log−action

ACTION@EXPRESSION

as above, but log expression evaluation results and actions performed.

−true−action

ACTION@EXPRESSION

as above, but only log expressions which return TRUE.

−false−action

ACTION@EXPRESSION

as above, but only log expressions which return FALSE.

−action−file

FILE

as action, but read actions from FILE.

−log−action−file

FILE

as −log−action

, but read actions from FILE.

−true−action−file

FILE

as −true−action

, but read actions from FILE.

−false−action−file

FILE

as −false−action

, but read actions from FILE.

Filesystem filter options:

−p

PSEUDO−DEFINITION

Add pseudo file definition. The definition should be quoted.

−pf

PSEUDO−FILE

Add list of pseudo file definitions. Pseudo file definitions in pseudo−files should not be quoted.

−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.

−one−file−system

Do not cross filesystem boundaries when scanning sources.

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.

−exit−on−error

treat normally ignored errors as fatal.

−recover

NAME

recover filesystem data using recovery file NAME.

−no−recovery

don't generate a recovery file.

−recovery−path

NAME

use NAME as the directory to store the recovery file.

−quiet

no verbose output.

−info

print files written to filesystem.

−no−progress

don't display the progress bar.

−progress

display progress bar when using the −info

option.

−throttle

PERCENTAGE

throttle the I/O input rate by the given percentage. This can be used to reduce the I/O and CPU consumption of Mksquashfs.

−limit

PERCENTAGE

limit the I/O input rate to the given percentage. This can be used to reduce the I/O and CPU consumption of Mksquashfs (alternative to −throttle

−processors

NUMBER

Use NUMBER processors. By default will use number of processors available.

−mem

SIZE

Use SIZE physical memory. Optionally a suffix of K, M or G can be given to specify Kbytes, Mbytes or Gbytes respectively.

Expert options (these may make the filesystem unmountable):

−nopad

do not pad filesystem to a multiple of 4K.

−offset

OFFSET

Skip OFFSET bytes at the beginning of FILESYSTEM. Optionally a suffix of K, M or G can be given to specify Kbytes, Mbytes or Gbytes respectively. Default 0 bytes.

−o

OFFSET

synonym for −offset

Miscellaneous options:

−root−owned

alternative name for −all−root

−noInodeCompression

alternative name for −noI

−noIdTableCompression

alternative name for −noId

−noDataCompression

alternative name for −noD

−noFragmentCompression

alternative name for −noF

−noXattrCompression

alternative name for −noX

−help

output this options text to stdout.

−h

output this options text to stdout.

−Xhelp

print compressor options for selected compressor.

PSEUDO FILE DEFINITION FORMAT

−p

"filename d mode uid gid"

create a directory.

−p

"filename m mode uid gid"

modify filename.

−p

"filename b mode uid gid major minor"

create a block device.

−p

"filename c mode uid gid major minor"

create a character device.

−p

"filename f mode uid gid command"

create file from stdout of command.

−p

"filename s mode uid gid symlink"

create a symbolic link.

−p

"filename i mode uid gid [s|f]

create a socket (s) or FIFO (f).

−p

"filename l linkname"

create a hard−link to linkname.

−p

"filename L pseudo_filename"

same, but link to pseudo file.

−p

"filename D time mode uid gid"

create a directory with timestamp time.

−p

"filename M time mode uid gid"

modify a file with timestamp time.

−p

"filename B time mode uid gid major minor"

create block device with timestamp time.

−p

"filename C time mode uid gid major minor"

create char device with timestamp time.

−p

"filename F time mode uid gid command"

create file with timestamp time.

−p

"filename S time mode uid gid symlink"

create symlink with timestamp time.

−p

"filename I time mode uid gid [s|f]

create socket/fifo with timestamp time.

COMPRESSORS AVAILABLE AND COMPRESSOR SPECIFIC OPTIONS

gzip (default):

−Xcompression−level

COMPRESSION−LEVEL

COMPRESSION−LEVEL should be 1 .. 9 (default 9).

−Xwindow−size

WINDOW−SIZE

WINDOW−SIZE should be 8 .. 15 (default 15).

−Xstrategy

strategy1,strategy2,...,strategyN

Compress using strategy1,strategy2,...,strategyN in turn and choose the best compression. Available strategies: default, filtered, huffman_only, run_length_encoded and fixed.

lzo:

−Xalgorithm

ALGORITHM

Where ALGORITHM is one of: lzo1x_1, lzo1x_1_11, lzo1x_1_12, lzo1x_1_15, lzo1x_999 (default).

−Xcompression−level

COMPRESSION−LEVEL

COMPRESSION−LEVEL should be 1 .. 9 (default 8) Only applies to lzo1x_999 algorithm.

lz4:

−Xhc

Compress using LZ4 High Compression.

xz:

−Xbcj

filter1,filter2,...,filterN

Compress using filter1,filter2,...,filterN in turn (in addition to no filter), and choose the best compression. Available filters: x86, arm, armthumb, powerpc, sparc, ia64.

−Xdict−size

DICT−SIZE

Use DICT−SIZE as the XZ dictionary size. The dictionary size can be specified as a percentage of the block size, or as an absolute value. The dictionary size must be less than or equal to the block size and 8192 bytes or larger. It must also be storable in the xz header as either 2^n or as 2^n+2^(n+1). Example dict−sizes are 75%, 50%, 37.5%, 25%, or 32K, 16K, 8K etc.

zstd:

−Xcompression−level

COMPRESSION−LEVEL

COMPRESSION−LEVEL should be 1 .. 22 (default 15).

lzma:

(no options) (deprecated − no kernel support)

ENVIRONMENT

SOURCE_DATE_EPOCH If set, this is used as the filesystem creation timestamp. Also any file timestamps which are after SOURCE_DATE_EPOCH will be clamped to SOURCE_DATE_EPOCH. See https://reproducible−builds.org/docs/source−date−epoch/ for more information.

EXAMPLES

mksquashfs DIRECTORY IMAGE.SQFS Create a Squashfs filesystem from the contents of DIRECTORY, writing the output to IMAGE.SQSH. Mksquashfs will use the default compressor (normally gzip), and block size of 128 Kbytes.

mksquashfs DIRECTORY FILE1 FILE2 IMAGE.SQFS Create a Squashfs filesystem containing DIRECTORY and FILE1 and FILE2. If multiple sources are specified on the command line they will be combined into a single directory.

mksquashfs DIRECTORY IMAGE.SQFS -b 1M -comp zstd Use a block size of 1 Mbyte and Zstandard compression to create the filesystem.

mksquashfs DIRECTORY IMAGE.SQFS -e file1 file2 Exclude file1 and file2 from DIRECTORY when creating filesystem. No wildcard matching of files.

mksquashfs DIRECTORY IMAGE.SQFS -wildcards -e "*.gz" Exclude anything in DIRECTORY which matches the wildcard pattern "*.gz".

mksquashfs DIRECTORY IMAGE.SQFS -wildcards -e "... *.gz" Exclude files which match the wildcard pattern "*.gz" anywhere within DIRECTORY and its sub-directories. The initial "..." indicates the wildcard pattern is "non-anchored" and will match anywhere.

Note: when passing wildcarded names to Mksquashfs, they should be quoted (as in the above examples), to ensure that they are not processed by the shell.

Using pseudo file definitions

mksquashfs DIRECTORY IMAGE.SQFS -p "build_dir d 0644 0 0" Create a directory called "build_dir" in the output filesystem.

mksquashfs DIRECTORY IMAGE.SQFS -p "version.txt l /tmp/build/version" Create a reference called "version.txt" to a file outside DIRECTORY, which acts as if the file "/tmp/build/version" was copied or hard-linked into DIRECTORY before calling Mksquashfs.

mksquashfs DIRECTORY IMAGE.SQFS -p "date.txt f 0644 0 0 date" Create a file called "date.txt" which holds the output (stdout) from running the "date" command.

mksquashfs DIRECTORY IMAGE.SQFS -p "\"hello world\\" f 0644 0 0 date" As above, but, showing that filenames can have spaces, if they are quoted. The quotes need to be blackslashed to protect them from the shell.

mksquashfs - IMAGE.SQFS -p "input f 0644 root root dd if=/dev/sda1 bs=1024" -p "/ d 0644 0 0" Create a file containing the contents of partition /dev/sda1". 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. Note there are no other sources than the pseudo file, and so the command line source is "-". If there are no other sources than pseudo files, the root (/) directory must be defined too, as seen in this example.

Note: pseudo file definitions should be quoted (as in the above examples), to ensure that they are passed to Mksquashfs as a single argument, and to ensure that they are not processed by the shell.

Using Actions to not compress, change attributes etc.

mksquashfs DIRECTORY IMAGE.SQSH -action "uncompressed @ (name(*.jpg) || name(*.mpg) ) || (name(*.img) && filesize(+1G)

)

Specify that any files matching the wildcards "*.jpg" and "*.mpg" should not be compressed. Additionally, it also specifies any files matching the wildcard "*.img" and are larger than 1 Gigabyte should be uncompressed too. This shows test operators can be combined with logical expressions.

mksquashfs DIRECTORY IMAGE.SQSH -action "chmod(o+r)@! perm(o+r)

If any files within DIRECTORY are not readable by "others", then make them readable by others in the Squashfs filesystem.

mksquashfs DIRECTORY IMAGE.SQSH -action "uid(phillip)@! perm(o+r)

As previous, match on any files which are not readable by "others", but, in this case change the owner of the file to "phillip" in the Squashfs filesystem.

mksquashfs DIRECTORY IMAGE.SQSH -action "prune @ type(l) && ! exists" Delete any symbolic link within DIRECTORY which points outside of DIRECTORY, i.e. will be unresolvable in the Squashfs filesystem.

mksquashfs DIRECTORY IMAGE.SQSH -action "exclude @ depth(3)

Create a Squashfs filesystem containing the two top most levels (contents of DIRECTORY and immediate sub-directories), and exclude anything at level 3 or below.

Note: actions should be quoted (as in the above examples), to ensure that they are passed to Mksquashfs as a single argument, and to ensure that they are not processed by the shell.

AUTHOR

Written by Phillip Lougher <phillip@squashfs.org.uk>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.