1SQFSTAR(1) User Commands SQFSTAR(1)
2
6 sqfstar - tool to create a squashfs filesystem from a tar archive
7
9 cat xxx.tar | sqfstar [OPTIONS] FILESYSTEM [exclude files]
10 zcat xxx.tgz | sqfstar [OPTIONS] FILESYSTEM [exclude files]
11 xzcat xxx.tar.xz | sqfstar [OPTIONS] FILESYSTEM [exclude files]
12 zstdcat xxx.tar.zst | sqfstar [OPTIONS] FILESYSTEM [exclude files]
13
15 Squashfs is a highly compressed read-only filesystem for Linux. It
16 uses either gzip/xz/lzo/lz4/zstd compression to compress both files,
17 inodes and directories. Inodes in the system are very small and all
18 blocks are packed to minimise data overhead. Block sizes greater than
19 4K are supported up to a maximum of 1Mbytes (default block size 128K).
20 Squashfs is intended for general read-only filesystem use, for archival
22 use (i.e. in cases where a .tar.gz file may be used), and in con‐
23 strained block device/memory systems (e.g. embedded systems) where low
24 overhead is needed.
25
27 Filesystem compression options:
28 -b BLOCK_SIZE
29 set data block to BLOCK_SIZE. Default 128 Kbytes. Optionally a
30 suffix of K or M can be given to specify Kbytes or Mbytes re‐
31 spectively.
32 -comp COMP
34 select COMP compression. Compressors available: gzip (default),
35 lzo, lz4, xz, zstd, lzma.
36 -noI do not compress inode table.
38 -noId do not compress the uid/gid table (implied by -noI).
40 -noD do not compress data blocks.
42 -noF do not compress fragment blocks.
44 -noX do not compress extended attributes.
46 -no-compression
48 do not compress any of the data or metadata. This is equivalent
49 to specifying -noI -noD -noF and -noX.
50 Filesystem build options:
52 -reproducible
53 build filesystems that are reproducible (default).
54 -not-reproducible
56 build filesystems that are not reproducible.
57 -mkfs-time TIME
59 set filesystem creation timestamp to TIME. TIME can be an un‐
60 signed 32-bit int indicating seconds since the epoch
61 (1970-01-01) or a string value which is passed to the "date"
62 command to parse. Any string value which the date command recog‐
63 nises can be used such as "now", "last week", or "Wed Feb 15
64 21:02:39 GMT 2023".
65 -all-time TIME
67 set all file timestamps to TIME. TIME can be an unsigned 32-bit
68 int indicating seconds since the epoch (1970-01-01) or a string
69 value which is passed to the "date" command to parse. Any string
70 value which the date command recognises can be used such as
71 "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023".
72 -root-time TIME
74 set root directory time to TIME. TIME can be an unsigned 32-bit
75 int indicating seconds since the epoch (1970-01-01) or a string
76 value which is passed to the "date" command to parse. Any string
77 value which the date command recognises can be used such as
78 "now", "last week", or "Wed Feb 15 21:02:39 GMT 2023".
79 -root-mode MODE
81 set root directory permissions to octal MODE.
82 -root-uid VALUE
84 set root directory owner to specified VALUE, VALUE can be either
85 an integer uid or user name.
86 -root-gid VALUE
88 set root directory group to specified VALUE, VALUE can be either
89 an integer gid or group name.
90 -all-root
92 make all files owned by root.
93 -force-uid VALUE
95 set all file uids to specified VALUE, VALUE can be either an in‐
96 teger uid or user name.
97 -force-gid VALUE
99 set all file gids to specified VALUE, VALUE can be either an in‐
100 teger gid or group name.
101 -default-mode MODE
103 tar files often do not store permissions for intermediate direc‐
104 tories. This option sets the default directory permissions to
105 octal MODE, rather than 0755. This also sets the root inode
106 mode.
107 -default-uid UID
109 tar files often do not store uids for intermediate directories.
110 This option sets the default directory owner to UID, rather than
111 the user running Sqfstar. This also sets the root inode uid.
112 -default-gid GID
114 tar files often do not store gids for intermediate directories.
115 This option sets the default directory group to GID, rather than
116 the group of the user running Sqfstar. This also sets the root
117 inode gid.
118 -pseudo-override
120 make pseudo file uids and gids override -all-root, -force-uid
121 and -force-gid options.
122 -exports
124 make the filesystem exportable via NFS.
125 -no-sparse
127 do not detect sparse files.
128 -no-fragments
130 do not use fragments.
131 -no-tailends
133 do not pack tail ends into fragments.
134 -no-duplicates
136 do not perform duplicate checking.
137 -no-hardlinks
139 do not hardlink files, instead store duplicates.
140 Filesystem filter options:
142 -p PSEUDO-DEFINITION
143 add pseudo file definition. The definition should be quoted.
144 -pf PSEUDO-FILE
146 add list of pseudo file definitions. Pseudo file definitions in
147 pseudo-files should not be quoted.
148 -ef EXCLUDE_FILE
150 list of exclude dirs/files. One per line.
151 -regex allow POSIX regular expressions to be used in exclude
153 dirs/files.
154 -ignore-zeros
156 allow tar files to be concatenated together and fed to Sqfstar.
157 Normally a tarfile has two consecutive 512 byte blocks filled
158 with zeros which means EOF and Sqfstar will stop reading after
159 the first tar file on encountering them. This option makes Sqfs‐
160 tar ignore the zero filled blocks.
161 Filesystem extended attribute (xattrs) options:
163 -no-xattrs
164 do not store extended attributes.
165 -xattrs
167 store extended attributes (default).
168 -xattrs-exclude REGEX
170 exclude any xattr names matching REGEX. REGEX is a POSIX regu‐
171 lar expression, e.g. -xattrs-exclude '^user.' excludes xattrs
172 from the user namespace.
173 -xattrs-include REGEX
175 include any xattr names matching REGEX. REGEX is a POSIX regu‐
176 lar expression, e.g. -xattrs-include '^user.' includes xattrs
177 from the user namespace.
178 -xattrs-add NAME=VAL
180 add the xattr NAME with VAL to files. If an user xattr it will
181 be added to regular files and directories (see man 7 xattr).
182 Otherwise it will be added to all files. VAL by default will be
183 treated as binary (i.e. an uninterpreted byte sequence), but it
184 can be prefixed with 0s, where it will be treated as base64 en‐
185 coded, or prefixed with 0x, where val will be treated as hex‐
186 idecimal. Additionally it can be prefixed with 0t where this
187 encoding is similar to binary encoding, except backslashes are
188 specially treated, and a backslash followed by 3 octal digits
189 can be used to encode any ASCII character, which obviously can
190 be used to encode control codes. The option can be repeated
191 multiple times to add multiple xattrs.
192 Sqfstar runtime options:
194 -version
195 print version, licence and copyright message.
196 -force force Sqfstar to write to block device or file.
198 -exit-on-error
200 treat normally ignored errors as fatal.
201 -quiet no verbose output.
203 -info print files written to filesystem.
205 -no-progress
207 do not display the progress bar.
208 -progress
210 display progress bar when using the -info option.
211 -percentage
213 display a percentage rather than the full progress bar. Can be
214 used with dialog --gauge etc.
215 -throttle PERCENTAGE
217 throttle the I/O input rate by the given percentage. This can be
218 used to reduce the I/O and CPU consumption of Sqfstar.
219 -limit PERCENTAGE
221 limit the I/O input rate to the given percentage. This can be
222 used to reduce the I/O and CPU consumption of Sqfstar (alterna‐
223 tive to -throttle).
224 -processors NUMBER
226 use NUMBER processors. By default will use number of processors
227 available.
228 -mem SIZE
230 use SIZE physical memory for caches. Use K, M or G to specify
231 Kbytes, Mbytes or Gbytes respectively.
232 -mem-percent PERCENT
234 use PERCENT physical memory for caches. Default 25%.
235 -mem-default
237 print default memory usage in Mbytes.
238 Expert options (these may make the filesystem unmountable):
240 -nopad do not pad filesystem to a multiple of 4K.
241 -offset OFFSET
243 skip OFFSET bytes at the beginning of FILESYSTEM. Optionally a
244 suffix of K, M or G can be given to specify Kbytes, Mbytes or
245 Gbytes respectively. Default 0 bytes.
246 -o OFFSET
248 synonym for -offset.
249 Miscellaneous options:
251 -fstime TIME
252 alternative name for mkfs-time.
253 -root-owned
255 alternative name for -all-root.
256 -noInodeCompression
258 alternative name for -noI.
259 -noIdTableCompression
261 alternative name for -noId.
262 -noDataCompression
264 alternative name for -noD.
265 -noFragmentCompression
267 alternative name for -noF.
268 -noXattrCompression
270 alternative name for -noX.
271 -help output this options text to stdout.
273 -h output this options text to stdout.
275 -Xhelp print compressor options for selected compressor.
277
279 -p "filename d mode uid gid"
280 create a directory.
281 -p "filename m mode uid gid"
283 modify filename.
284 -p "filename b mode uid gid major minor"
286 create a block device.
287 -p "filename c mode uid gid major minor"
289 create a character device.
290 -p "filename f mode uid gid command"
292 create file from stdout of command.
293 -p "filename s mode uid gid symlink"
295 create a symbolic link.
296 -p "filename i mode uid gid [s|f]"
298 create a socket (s) or FIFO (f).
299 -p "filename x name=val"
301 create an extended attribute.
302 -p "filename l linkname"
304 create a hard-link to linkname.
305 -p "filename L pseudo_filename"
307 same, but link to pseudo file.
308 -p "filename D time mode uid gid"
310 create a directory with timestamp time.
311 -p "filename M time mode uid gid"
313 modify a file with timestamp time.
314 -p "filename B time mode uid gid major minor"
316 create block device with timestamp time.
317 -p "filename C time mode uid gid major minor"
319 create char device with timestamp time.
320 -p "filename F time mode uid gid command"
322 create file with timestamp time.
323 -p "filename S time mode uid gid symlink"
325 create symlink with timestamp time.
326 -p "filename I time mode uid gid [s|f]"
328 create socket/fifo with timestamp time.
329
331 gzip (default):
332 -Xcompression-level COMPRESSION-LEVEL
333 COMPRESSION-LEVEL should be 1 .. 9 (default 9).
334 -Xwindow-size WINDOW-SIZE
336 WINDOW-SIZE should be 8 .. 15 (default 15).
337 -Xstrategy strategy1,strategy2,...,strategyN
339 Compress using strategy1,strategy2,...,strategyN in turn and
340 choose the best compression. Available strategies: default, fil‐
341 tered, huffman_only, run_length_encoded and fixed.
342 lzo:
344 -Xalgorithm ALGORITHM
345 Where ALGORITHM is one of: lzo1x_1, lzo1x_1_11, lzo1x_1_12,
346 lzo1x_1_15, lzo1x_999 (default).
347 -Xcompression-level COMPRESSION-LEVEL
349 COMPRESSION-LEVEL should be 1 .. 9 (default 8) Only applies to
350 lzo1x_999 algorithm.
351 lz4:
353 -Xhc Compress using LZ4 High Compression.
354 xz:
356 -Xbcj filter1,filter2,...,filterN
357 Compress using filter1,filter2,...,filterN in turn (in addition
358 to no filter), and choose the best compression. Available fil‐
359 ters: x86, arm, armthumb, powerpc, sparc, ia64.
360 -Xdict-size DICT-SIZE
362 Use DICT-SIZE as the XZ dictionary size. The dictionary size
363 can be specified as a percentage of the block size, or as an ab‐
364 solute value. The dictionary size must be less than or equal to
365 the block size and 8192 bytes or larger. It must also be
366 storable in the xz header as either 2^n or as 2^n+2^(n+1). Exam‐
367 ple dict-sizes are 75%, 50%, 37.5%, 25%, or 32K, 16K, 8K etc.
368 zstd:
370 -Xcompression-level COMPRESSION-LEVEL
371 COMPRESSION-LEVEL should be 1 .. 22 (default 15).
372 lzma:
374 (no options) (deprecated - no kernel support)
375
377 SOURCE_DATE_EPOCH
378 If set, this is used as the filesystem creation timestamp. Also
379 any file timestamps which are after SOURCE_DATE_EPOCH will be
380 clamped to SOURCE_DATE_EPOCH. See https://repro‐
381 ducible-builds.org/docs/source-date-epoch/ for more information.
382
384 sqfstar IMAGE.SQFS < archive.tar
385 Create a Squashfs filesystem from the uncompressed tar file "ar‐
386 chive.tar". Sqfstar will use the default compressor (normally
387 gzip), and block size of 128 Kbytes.
388 zcat archive.tgz | sqfstar IMAGE.SQFS
390 Create a Squashfs filesystem from the compressed tar file "ar‐
391 chive.tgz". Sqfstar will use the default compressor (normally
392 gzip), and block size of 128 Kbytes.
393 sqfstar -b 1M -comp zstd IMAGE.SQFS < archive.tar
395 Use a block size of 1 Mbyte and Zstandard compression to create
396 the filesystem.
397 sqfstar -root-uid 0 -root-gid 0 IMAGE.SQFS < archive.tar
399 Tar files do not supply a definition for the root directory, and
400 the default is to make the directory owned/group owned by the
401 user running Sqfstar. The above command sets the owner‐
402 ship/group ownership to root.
403 sqfstar -root-mode 0755 IMAGE.SQFS < archive.tar
405 The default permissions for the root directory is 0777 (rwxr‐
406 wxrwx). The above command sets the permissions to 0755 (rwxr-
407 xr-x).
408 sqfstar IMAGE.SQFS file1 file2 < archive.tar
410 Exclude file1 and file2 from the tar file when creating filesys‐
411 tem.
412 sqfstar IMAGE.SQFS "*.gz" < archive.tar
414 Exclude any files in the top level directory which matches the
415 wildcard pattern "*.gz".
416 sqfstar IMAGE.SQFS "... *.gz" < archive.tar
418 Exclude any file which matches the wildcard pattern "*.gz" any‐
419 where within the tar file. The initial "..." indicates the
420 wildcard pattern is "non-anchored" and will match anywhere.
421 Note: when passing wildcarded names to Sqfstar, they should be quoted
423 (as in the above examples), to ensure that they are not processed by
424 the shell.
425 Using pseudo file definitions
428 sqfstar -p "build_dir d 0644 0 0" IMAGE.SQFS < archive.tar
429 Create a directory called "build_dir" in the output filesystem.
430 sqfstar -p "version.txt l /tmp/build/version" IMAGE.SQFS < archive.tar
432 Create a reference called "version.txt" to a file not in the tar
433 archive, which acts as if that file was in the tar archive.
434 sqfstar -p "date.txt f 0644 0 0 date" IMAGE.SQFS < archive.tar
436 Create a file called "date.txt" which holds the output (stdout)
437 from running the "date" command.
438 sqfstar -p "\"hello world\" f 0644 0 0 date" IMAGE.SQFS < archive.tar
440 As above, but, showing that filenames can have spaces, if they
441 are quoted. The quotes need to be blackslashed to protect them
442 from the shell.
443 sqfstar -p "input f 0644 root root dd if=/dev/sda1 bs=1024" IMAGE.SQFS
445 < archive.tar
446 Create a file containing the contents of partition /dev/sda1".
447 The above allows input from these special files to be captured
448 and placed in the Squashfs filesystem.
449 Note: pseudo file definitions should be quoted (as in the above exam‐
451 ples), to ensure that they are passed to Mksquashfs as a single argu‐
452 ment, and to ensure that they are not processed by the shell.
453
455 Written by Phillip Lougher <phillip@squashfs.org.uk>
456
458 Copyright © 2023 Phillip Lougher <phillip@squashfs.org.uk>
459 This program is free software; you can redistribute it and/or modify it
461 under the terms of the GNU General Public License as published by the
462 Free Software Foundation; either version 2, or (at your option) any
463 later version.
464 This program is distributed in the hope that it will be useful, but
466 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
467 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
468 Public License for more details.
469
471 mksquashfs(1), unsquashfs(1), sqfscat(1)
472 The README for the Squashfs-tools 4.6.1 release, describing the new
474 features can be read here
475 https://github.com/plougher/squashfs-tools/blob/master/README-4.6.1
476 The Squashfs-tools USAGE guide can be read here
478 https://github.com/plougher/squashfs-tools/blob/master/USAGE-4.6
479sqfstar version 4.6.1 July 2023 SQFSTAR(1)