1MKSQUASHFS(1) User Commands MKSQUASHFS(1)
2
6 mksquashfs - tool to create and append to squashfs filesystems
7
9 mksquashfs source1 source2 ... FILESYSTEM [OPTIONS] [-e list of ex‐
10 clude dirs/files]
11
13 Squashfs is a highly compressed read-only filesystem for Linux. It
14 uses either gzip/xz/lzo/lz4/zstd compression to compress both files,
15 inodes and directories. Inodes in the system are very small and all
16 blocks are packed to minimise data overhead. Block sizes greater than
17 4K are supported up to a maximum of 1Mbytes (default block size 128K).
18 Squashfs is intended for general read-only filesystem use, for archival
20 use (i.e. in cases where a .tar.gz file may be used), and in con‐
21 strained block device/memory systems (e.g. embedded systems) where low
22 overhead is needed.
23
25 Filesystem compression options:
26 -b BLOCK_SIZE
27 set data block to BLOCK_SIZE. Default 128 Kbytes. Optionally a
28 suffix of K or M can be given to specify Kbytes or Mbytes re‐
29 spectively.
30 -comp COMP
32 select COMP compression. Compressors available: gzip (default),
33 lzo, lz4, xz, zstd, lzma.
34 -noI do not compress inode table.
36 -noId do not compress the uid/gid table (implied by -noI).
38 -noD do not compress data blocks.
40 -noF do not compress fragment blocks.
42 -noX do not compress extended attributes.
44 -no-compression
46 do not compress any of the data or metadata. This is equivalent
47 to specifying -noI -noD -noF and -noX.
48 Filesystem build options:
50 -tar read uncompressed tar file from standard in (stdin).
51 -no-strip
53 act like tar, and do not strip leading directories from source
54 files.
55 -tarstyle
57 alternative name for -no-strip.
58 -cpiostyle
60 act like cpio, and read file pathnames from standard in (stdin).
61 -cpiostyle0
63 like -cpiostyle, but filenames are null terminated. Can be used
64 with find -print0 action.
65 -reproducible
67 build filesystems that are reproducible (default).
68 -not-reproducible
70 build filesystems that are not reproducible.
71 -mkfs-time TIME
73 set filesystem creation timestamp to TIME. TIME can be an un‐
74 signed 32-bit int indicating seconds since the epoch
75 (1970-01-01) or a string value which is passed to the "date"
76 command to parse. Any string value which the date command recog‐
77 nises can be used such as "now", "last week", or "Wed Feb 15
78 21:02:39 GMT 2023".
79 -all-time TIME
81 set all file timestamps to TIME. TIME can be an unsigned 32-bit
82 int indicating seconds since the epoch (1970-01-01) or a string
83 value which is passed to the "date" command to parse. Any string
84 value which the date command recognises can be used such as
85 "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023".
86 -root-time TIME
88 set root directory time to TIME. TIME can be an unsigned 32-bit
89 int indicating seconds since the epoch (1970-01-01) or a string
90 value which is passed to the "date" command to parse. Any string
91 value which the date command recognises can be used such as
92 "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023".
93 -root-mode MODE
95 set root directory permissions to octal MODE.
96 -root-uid VALUE
98 set root directory owner to specified VALUE, VALUE can be either
99 an integer uid or user name.
100 -root-gid VALUE
102 set root directory group to specified VALUE, VALUE can be either
103 an integer gid or group name.
104 -all-root
106 make all files owned by root.
107 -force-uid VALUE
109 set all file uids to specified VALUE, VALUE can be either an in‐
110 teger uid or user name.
111 -force-gid VALUE
113 set all file gids to specified VALUE, VALUE can be either an in‐
114 teger gid or group name.
115 -pseudo-override
117 make pseudo file uids and gids override -all-root, -force-uid
118 and -force-gid options.
119 -no-exports
121 do not make filesystem exportable via NFS (-tar default).
122 -exports
124 make filesystem exportable via NFS (default).
125 -no-sparse
127 do not detect sparse files.
128 -no-tailends
130 do not pack tail ends into fragments (default).
131 -tailends
133 pack tail ends into fragments.
134 -no-fragments
136 do not use fragments.
137 -no-duplicates
139 do not perform duplicate checking.
140 -no-hardlinks
142 do not hardlink files, instead store duplicates.
143 -keep-as-directory
145 if one source directory is specified, create a root directory
146 containing that directory, rather than the contents of the di‐
147 rectory.
148 Filesystem filter options:
150 -p PSEUDO-DEFINITION
151 add pseudo file definition. The definition should be quoted.
152 -pf PSEUDO-FILE
154 add list of pseudo file definitions from PSEUDO-FILE, use - for
155 stdin. Pseudo file definitions should not be quoted.
156 -sort SORT_FILE
158 sort files according to priorities in SORT_FILE. One file or
159 dir with priority per line. Priority -32768 to 32767, default
160 priority 0.
161 -ef EXCLUDE_FILE
163 list of exclude dirs/files. One per line.
164 -wildcards
166 allow extended shell wildcards (globbing) to be used in exclude
167 dirs/files.
168 -regex allow POSIX regular expressions to be used in exclude
170 dirs/files.
171 -max-depth LEVELS
173 descend at most LEVELS of directories when scanning filesystem.
174 -one-file-system
176 do not cross filesystem boundaries. If a directory crosses the
177 boundary, create an empty directory for each mount point. If a
178 file crosses the boundary ignore it.
179 -one-file-system-x
181 do not cross filesystem boundaries. Like -one-file-system option
182 except directories are also ignored if they cross the boundary.
183 Filesystem extended attribute (xattrs) options:
185 -no-xattrs
186 do not store extended attributes.
187 -xattrs
189 store extended attributes (default).
190 -xattrs-exclude REGEX
192 exclude any xattr names matching REGEX. REGEX is a POSIX regu‐
193 lar expression, e.g. -xattrs-exclude '^user.' excludes xattrs
194 from the user namespace.
195 -xattrs-include REGEX
197 include any xattr names matching REGEX. REGEX is a POSIX regu‐
198 lar expression, e.g. -xattrs-include '^user.' includes xattrs
199 from the user namespace.
200 -xattrs-add NAME=VAL
202 add the xattr NAME with VAL to files. If an user xattr it will
203 be added to regular files and directories (see man 7 xattr).
204 Otherwise it will be added to all files. VAL by default will be
205 treated as binary (i.e. an uninterpreted byte sequence), but it
206 can be prefixed with 0s, where it will be treated as base64 en‐
207 coded, or prefixed with 0x, where val will be treated as hex‐
208 idecimal. Additionally it can be prefixed with 0t where this
209 encoding is similar to binary encoding, except backslashes are
210 specially treated, and a backslash followed by 3 octal digits
211 can be used to encode any ASCII character, which obviously can
212 be used to encode control codes. The option can be repeated
213 multiple times to add multiple xattrs.
214 Mksquashfs runtime options:
216 -version
217 print version, licence and copyright message.
218 -exit-on-error
220 treat normally ignored errors as fatal.
221 -quiet no verbose output.
223 -info print files written to filesystem.
225 -no-progress
227 do not display the progress bar.
228 -progress
230 display progress bar when using the -info option.
231 -percentage
233 display a percentage rather than the full progress bar. Can be
234 used with dialog --gauge etc.
235 -throttle PERCENTAGE
237 throttle the I/O input rate by the given percentage. This can be
238 used to reduce the I/O and CPU consumption of Mksquashfs.
239 -limit PERCENTAGE
241 limit the I/O input rate to the given percentage. This can be
242 used to reduce the I/O and CPU consumption of Mksquashfs (alter‐
243 native to -throttle).
244 -processors NUMBER
246 use NUMBER processors. By default will use number of processors
247 available.
248 -mem SIZE
250 use SIZE physical memory for caches. Use K, M or G to specify
251 Kbytes, Mbytes or Gbytes respectively.
252 -mem-percent PERCENT
254 use PERCENT physical memory for caches. Default 25%.
255 -mem-default
257 print default memory usage in Mbytes.
258 Filesystem append options:
260 -noappend
261 do not append to existing filesystem.
262 -root-becomes NAME
264 when appending source files/directories, make the original root
265 become a subdirectory in the new root called NAME, rather than
266 adding the new source items to the original root.
267 -no-recovery
269 do not generate a recovery file.
270 -recovery-path NAME
272 use NAME as the directory to store the recovery file.
273 -recover NAME
275 recover filesystem data using recovery file NAME.
276 Filesystem actions options:
278 -action ACTION@EXPRESSION
279 evaluate EXPRESSION on every file, and execute ACTION if it re‐
280 turns TRUE.
281 -log-action ACTION@EXPRESSION
283 as above, but log expression evaluation results and actions per‐
284 formed.
285 -true-action ACTION@EXPRESSION
287 as above, but only log expressions which return TRUE.
288 -false-action ACTION@EXPRESSION
290 as above, but only log expressions which return FALSE.
291 -action-file FILE
293 as action, but read actions from FILE.
294 -log-action-file FILE
296 as -log-action, but read actions from FILE.
297 -true-action-file FILE
299 as -true-action, but read actions from FILE.
300 -false-action-file FILE
302 as -false-action, but read actions from FILE.
303 Tar file only options:
305 -default-mode MODE
306 tar files often do not store permissions for intermediate direc‐
307 tories. This option sets the default directory permissions to
308 octal MODE, rather than 0755. This also sets the root inode
309 mode.
310 -default-uid UID
312 tar files often do not store uids for intermediate directories.
313 This option sets the default directory owner to UID, rather than
314 the user running Mksquashfs. This also sets the root inode uid.
315 -default-gid GID
317 tar files often do not store gids for intermediate directories.
318 This option sets the default directory group to GID, rather than
319 the group of the user running Mksquashfs. This also sets the
320 root inode gid.
321 -ignore-zeros
323 allow tar files to be concatenated together and fed to Mk‐
324 squashfs. Normally a tarfile has two consecutive 512 byte
325 blocks filled with zeros which means EOF and Mksquashfs will
326 stop reading after the first tar file on encountering them. This
327 option makes Mksquashfs ignore the zero filled blocks.
328 Expert options (these may make the filesystem unmountable):
330 -nopad do not pad filesystem to a multiple of 4K.
331 -offset OFFSET
333 skip OFFSET bytes at the beginning of FILESYSTEM. Optionally a
334 suffix of K, M or G can be given to specify Kbytes, Mbytes or
335 Gbytes respectively. Default 0 bytes.
336 -o OFFSET
338 synonym for -offset.
339 Miscellaneous options:
341 -fstime TIME
342 alternative name for -mkfs-time.
343 -always-use-fragments
345 alternative name for -tailends.
346 -root-owned
348 alternative name for -all-root.
349 -noInodeCompression
351 alternative name for -noI.
352 -noIdTableCompression
354 alternative name for -noId.
355 -noDataCompression
357 alternative name for -noD.
358 -noFragmentCompression
360 alternative name for -noF.
361 -noXattrCompression
363 alternative name for -noX.
364 -help output this options text to stdout.
366 -h output this options text to stdout.
368 -Xhelp print compressor options for selected compressor.
370
372 -p "filename d mode uid gid"
373 create a directory.
374 -p "filename m mode uid gid"
376 modify filename.
377 -p "filename b mode uid gid major minor"
379 create a block device.
380 -p "filename c mode uid gid major minor"
382 create a character device.
383 -p "filename f mode uid gid command"
385 create file from stdout of command.
386 -p "filename s mode uid gid symlink"
388 create a symbolic link.
389 -p "filename i mode uid gid [s|f]"
391 create a socket (s) or FIFO (f).
392 -p "filename x name=val"
394 create an extended attribute.
395 -p "filename l linkname"
397 create a hard-link to linkname.
398 -p "filename L pseudo_filename"
400 same, but link to pseudo file.
401 -p "filename D time mode uid gid"
403 create a directory with timestamp time.
404 -p "filename M time mode uid gid"
406 modify a file with timestamp time.
407 -p "filename B time mode uid gid major minor"
409 create block device with timestamp time.
410 -p "filename C time mode uid gid major minor"
412 create char device with timestamp time.
413 -p "filename F time mode uid gid command"
415 create file with timestamp time.
416 -p "filename S time mode uid gid symlink"
418 create symlink with timestamp time.
419 -p "filename I time mode uid gid [s|f]"
421 create socket/fifo with timestamp time.
422
424 gzip (default):
425 -Xcompression-level COMPRESSION-LEVEL
426 COMPRESSION-LEVEL should be 1 .. 9 (default 9).
427 -Xwindow-size WINDOW-SIZE
429 WINDOW-SIZE should be 8 .. 15 (default 15).
430 -Xstrategy strategy1,strategy2,...,strategyN
432 Compress using strategy1,strategy2,...,strategyN in turn and
433 choose the best compression. Available strategies: default, fil‐
434 tered, huffman_only, run_length_encoded and fixed.
435 lzo:
437 -Xalgorithm ALGORITHM
438 Where ALGORITHM is one of: lzo1x_1, lzo1x_1_11, lzo1x_1_12,
439 lzo1x_1_15, lzo1x_999 (default).
440 -Xcompression-level COMPRESSION-LEVEL
442 COMPRESSION-LEVEL should be 1 .. 9 (default 8) Only applies to
443 lzo1x_999 algorithm.
444 lz4:
446 -Xhc Compress using LZ4 High Compression.
447 xz:
449 -Xbcj filter1,filter2,...,filterN
450 Compress using filter1,filter2,...,filterN in turn (in addition
451 to no filter), and choose the best compression. Available fil‐
452 ters: x86, arm, armthumb, powerpc, sparc, ia64.
453 -Xdict-size DICT-SIZE
455 Use DICT-SIZE as the XZ dictionary size. The dictionary size
456 can be specified as a percentage of the block size, or as an ab‐
457 solute value. The dictionary size must be less than or equal to
458 the block size and 8192 bytes or larger. It must also be
459 storable in the xz header as either 2^n or as 2^n+2^(n+1). Exam‐
460 ple dict-sizes are 75%, 50%, 37.5%, 25%, or 32K, 16K, 8K etc.
461 zstd:
463 -Xcompression-level COMPRESSION-LEVEL
464 COMPRESSION-LEVEL should be 1 .. 22 (default 15).
465 lzma:
467 (no options) (deprecated - no kernel support)
468
470 SOURCE_DATE_EPOCH
471 If set, this is used as the filesystem creation timestamp. Also
472 any file timestamps which are after SOURCE_DATE_EPOCH will be
473 clamped to SOURCE_DATE_EPOCH. See https://repro‐
474 ducible-builds.org/docs/source-date-epoch/ for more information.
475
477 mksquashfs DIRECTORY IMAGE.SQFS
478 Create a Squashfs filesystem from the contents of DIRECTORY,
479 writing the output to IMAGE.SQSH. Mksquashfs will use the de‐
480 fault compressor (normally gzip), and block size of 128 Kbytes.
481 mksquashfs DIRECTORY FILE1 FILE2 IMAGE.SQFS
483 Create a Squashfs filesystem containing DIRECTORY and FILE1 and
484 FILE2. If multiple sources are specified on the command line
485 they will be combined into a single directory.
486 mksquashfs DIRECTORY IMAGE.SQFS -b 1M -comp zstd
488 Use a block size of 1 Mbyte and Zstandard compression to create
489 the filesystem.
490 mksquashfs DIRECTORY IMAGE.SQFS -e file1 file2
492 Exclude file1 and file2 from DIRECTORY when creating filesystem.
493 No wildcard matching of files.
494 mksquashfs DIRECTORY IMAGE.SQFS -wildcards -e "*.gz"
496 Exclude anything in DIRECTORY which matches the wildcard pattern
497 "*.gz".
498 mksquashfs DIRECTORY IMAGE.SQFS -wildcards -e "... *.gz"
500 Exclude files which match the wildcard pattern "*.gz" anywhere
501 within DIRECTORY and its sub-directories. The initial "..." in‐
502 dicates the wildcard pattern is "non-anchored" and will match
503 anywhere.
504 Note: when passing wildcarded names to Mksquashfs, they should be
506 quoted (as in the above examples), to ensure that they are not pro‐
507 cessed by the shell.
508 Using pseudo file definitions
511 mksquashfs DIRECTORY IMAGE.SQFS -p "build_dir d 0644 0 0"
512 Create a directory called "build_dir" in the output filesystem.
513 mksquashfs DIRECTORY IMAGE.SQFS -p "version.txt l /tmp/build/version"
515 Create a reference called "version.txt" to a file outside DIREC‐
516 TORY, which acts as if the file "/tmp/build/version" was copied
517 or hard-linked into DIRECTORY before calling Mksquashfs.
518 mksquashfs DIRECTORY IMAGE.SQFS -p "date.txt f 0644 0 0 date"
520 Create a file called "date.txt" which holds the output (stdout)
521 from running the "date" command.
522 mksquashfs DIRECTORY IMAGE.SQFS -p "\"hello world\" f 0644 0 0 date"
524 As above, but, showing that filenames can have spaces, if they
525 are quoted. The quotes need to be blackslashed to protect them
526 from the shell.
527 mksquashfs - IMAGE.SQFS -p "input f 0644 root root dd if=/dev/sda1
529 bs=1024" -p "/ d 0644 0 0"
530 Create a file containing the contents of partition /dev/sda1".
531 Ordinarily Mksquashfs given a device, fifo, or named socket will
532 place that special file within the Squashfs filesystem, the
533 above allows input from these special files to be captured and
534 placed in the Squashfs filesystem. Note there are no other
535 sources than the pseudo file, and so the command line source is
536 "-". If there are no other sources than pseudo files, the root
537 (/) directory must be defined too, as seen in this example.
538 unsquashfs -pf - IMAGE.SQFS | mksquashfs - NEW.SQFS -pf -
540 Transcode IMAGE.SQFS to NEW.SQFS by piping the pseudo file out‐
541 put from Unsquashfs to Mksquashfs using stdout and stdin. This
542 can convert from earlier Squashfs filesystems or change compres‐
543 sion algorithm, block size etc. without needing to unpack into
544 an intermediate directory or file.
545 Note: pseudo file definitions should be quoted (as in the above exam‐
547 ples), to ensure that they are passed to Mksquashfs as a single argu‐
548 ment, and to ensure that they are not processed by the shell.
549 Using extended attribute options
552 mksquashfs DIRECTORY IMAGE.SQFS -no-xattrs
553 Do not store any extended attributes in the Squashfs filesystem.
554 Any extended attributes in the source files will be ignored.
555 mksquashfs DIRECTORY IMAGE.SQFS -xattrs-include "^user."
557 Filter the extended attributes in the source files, and only
558 store extended attributes in the user namespace in the Squashfs
559 filesystem.
560 mksquashfs DIRECTORY IMAGE.SQFS -xattrs-exclude "^user."
562 Filter the extended attributes in the source files, and don't
563 store any extended attributes in the user namespace in the
564 Squashfs filesystem.
565 mksquashfs DIRECTORY IMAGE.SQFS -xattrs-add "user.comment=hello world"
567 Add the extended attribute called "user.comment" with the con‐
568 tent "hello world" to all files and directories in the Squashfs
569 filesystem.
570 mksquashfs DIRECTORY IMAGE.SQFS -xattrs-add "user.comment=0thello
572 world\012"
573 Add the extended attribute called "user.comment" to all files
574 and directories, but in this case the contents of the extended
575 attribute will be "hello world" with a trailing newline charac‐
576 ter (012 octal).
577 mksquashfs DIRECTORY IMAGE.SQFS -xattrs-add "user.com‐
579 ment=0saGVsbG8gd29ybGQ="
580 Add the extended attribute called "user.comment" to all files
581 and directories, where the value is given in base64 encoding,
582 representing "hello world".
583 mksquashfs DIRECTORY IMAGE.SQFS -action "-xattrs-include(^user.) @
585 type(f)"
586 Filter the extended attributes but only in regular files (type
587 f), and only store extended attributes in the user namespace.
588 mksquashfs DIRECTORY IMAGE.SQFS -p "hello_world x user.comment=0tsalve
590 mundi\012"
591 Add the extended attribute called "user.comment" to the file
592 called "hello_world", with the contents of the extended attri‐
593 bute being "salve mundi" with a trailing newline character (012
594 octal).
595 Using Actions to not compress, change attributes etc.
598 mksquashfs DIRECTORY IMAGE.SQSH -action "uncompressed @ (name(*.jpg) ||
599 name(*.mpg) ) || (name(*.img) && filesize(+1G))"
600 Specify that any files matching the wildcards "*.jpg" and
601 "*.mpg" should not be compressed. Additionally, it also speci‐
602 fies any files matching the wildcard "*.img" and are larger than
603 1 Gigabyte should be uncompressed too. This shows test opera‐
604 tors can be combined with logical expressions.
605 mksquashfs DIRECTORY IMAGE.SQSH -action "chmod(o+r)@! perm(o+r)"
607 If any files within DIRECTORY are not readable by "others", then
608 make them readable by others in the Squashfs filesystem.
609 mksquashfs DIRECTORY IMAGE.SQSH -action "uid(phillip)@! perm(o+r)"
611 As previous, match on any files which are not readable by "oth‐
612 ers", but, in this case change the owner of the file to
613 "phillip" in the Squashfs filesystem.
614 mksquashfs DIRECTORY IMAGE.SQSH -action "prune @ type(l) && ! exists"
616 Delete any symbolic link within DIRECTORY which points outside
617 of DIRECTORY, i.e. will be unresolvable in the Squashfs filesys‐
618 tem.
619 mksquashfs DIRECTORY IMAGE.SQSH -action "exclude @ depth(3)"
621 Create a Squashfs filesystem containing the two top most levels
622 (contents of DIRECTORY and immediate sub-directories), and ex‐
623 clude anything at level 3 or below.
624 mksquashfs DIRECTORY IMAGE.SQFS -action "-xattrs-include(^user.) @
626 type(f)"
627 Filter the extended attributes but only in regular files (type
628 f), and only store extended attributes in the user namespace.
629 Note: actions should be quoted (as in the above examples), to ensure
631 that they are passed to Mksquashfs as a single argument, and to ensure
632 that they are not processed by the shell.
633
635 Written by Phillip Lougher <phillip@squashfs.org.uk>
636
638 Copyright © 2023 Phillip Lougher <phillip@squashfs.org.uk>
639 This program is free software; you can redistribute it and/or modify it
641 under the terms of the GNU General Public License as published by the
642 Free Software Foundation; either version 2, or (at your option) any
643 later version.
644 This program is distributed in the hope that it will be useful, but
646 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
647 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
648 Public License for more details.
649
651 unsquashfs(1), sqfstar(1), sqfscat(1)
652 The README for the Squashfs-tools 4.6.1 release, describing the new
654 features can be read here
655 https://github.com/plougher/squashfs-tools/blob/master/README-4.6.1
656 The Squashfs-tools USAGE guide can be read here
658 https://github.com/plougher/squashfs-tools/blob/master/USAGE-4.6
659 The ACTIONS-README file describing how to use the new actions feature
661 can be read here https://github.com/plougher/squashfs-tools/blob/mas‐
662 ter/ACTIONS-README
663mksquashfs version 4.6.1 July 2023 MKSQUASHFS(1)