unsquashfs(1)

1UNSQUASHFS(1)                    User Commands                   UNSQUASHFS(1)
2
3
4

NAME

6       unsquashfs - tool to uncompress, extract and list squashfs filesystems
7

SYNOPSIS

9       unsquashfs [OPTIONS] FILESYSTEM [files to extract or exclude (with -ex‐
10       cludes) or cat (with -cat )]
11

DESCRIPTION

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
19       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

OPTIONS

25   Filesystem extraction (filtering) options:
26       -d PATHNAME, -dest PATHNAME
27              extract  to  PATHNAME, default "squashfs-root". This option also
28              sets the prefix used when listing the filesystem.
29
30       -max LEVELS, -max-depth LEVELS
31              descend at most LEVELS of directories when extracting.
32
33       -excludes
34              treat files on command line as exclude files.
35
36       -ex, -exclude-list
37              list of files to be excluded, terminated with ; e.g. file1 file2
38              ;.
39
40       -extract-file FILE
41              list of directories or files to extract. One per line.
42
43       -exclude-file FILE
44              list of directories or files to exclude. One per line.
45
46       -match abort  if  any  extract file does not match on anything, and can
47              not be resolved.  Implies -missing-symlinks and -no-wildcards.
48
49       -follow, -follow-symlinks
50              follow symlinks in extract files,  and  add  all  files/symlinks
51              needed to resolve extract file. Implies -no-wildcards.
52
53       -missing, -missing-symlinks
54              Unsquashfs  will abort if any symlink can't be resolved in -fol‐
55              low-symlinks.
56
57       -no-wild, -no-wildcards
58              do not use wildcard matching in extract and exclude names.
59
60       -r, -regex
61              treat extract names as POSIX regular expressions rather than use
62              the default shell wildcard expansion (globbing).
63
64       -all TIME, -all-time TIME
65              set  all file timestamps to TIME, rather than the time stored in
66              the filesystem inode.  TIME can be an unsigned 32-bit int  indi‐
67              cating  seconds  since  the epoch (1970-01-01) or a string value
68              which is passed to the "date" command to parse. Any string value
69              which  the  date  command  recognises can be used such as "now",
70              "last week", or "Wed Feb 15 21:02:39 GMT 2023".
71
72       -cat   cat the files on the command line to stdout.
73
74       -f, -force
75              if file already exists then overwrite.
76
77       -pf FILE
78              output a pseudo file equivalent of the input  Squashfs  filesys‐
79              tem, use - for stdout.
80
81   Filesystem information and listing options:
82       -s, -stat
83              display filesystem superblock information.
84
85       -max LEVELS, -max-depth LEVELS
86              descend at most LEVELS of directories when listing.
87
88       -i, -info
89              print files as they are extracted.
90
91       -li, -linfo
92              print  files as they are extracted with file attributes (like ls
93              -l output).
94
95       -l, -ls
96              list filesystem, but do not extract files.
97
98       -ll, -lls
99              list filesystem with file attributes (like ls -l output), but do
100              not extract files.
101
102       -lln, -llnumeric
103              same as -lls but with numeric uids and gids.
104
105       -lc    list  filesystem  concisely, displaying only files and empty di‐
106              rectories.  Do not extract files.
107
108       -llc   list filesystem concisely with file attributes, displaying  only
109              files and empty directories. Do not extract files.
110
111       -full, -full-precision
112              use full precision when displaying times including seconds.  Use
113              with -linfo, -lls, -lln and -llc.
114
115       -UTC   use UTC rather than local time zone when displaying time.
116
117       -mkfs-time
118              display filesystem superblock time, which is an unsigned  32-bit
119              int   representing   the   time   in  seconds  since  the  epoch
120              (1970-01-01).
121
122   Filesystem extended attribute (xattrs) options:
123       -no, -no-xattrs
124              do not extract xattrs in file system.
125
126       -x, -xattrs
127              extract xattrs in file system (default).
128
129       -xattrs-exclude REGEX
130              exclude any xattr names matching REGEX. REGEX is a POSIX regular
131              expression,  e.g.  -xattrs-exclude '^user.' excludes xattrs from
132              the user namespace.
133
134       -xattrs-include REGEX
135              include any xattr names matching REGEX. REGEX is a POSIX regular
136              expression,  e.g.  -xattrs-include '^user.' includes xattrs from
137              the user namespace.
138
139   Unsquashfs runtime options:
140       -v, -version
141              print version, licence and copyright information.
142
143       -p NUMBER, -processors NUMBER
144              use NUMBER processors.  By default will use the number  of  pro‐
145              cessors available.
146
147       -q, -quiet
148              no verbose output.
149
150       -n, -no-progress
151              do not display the progress bar.
152
153       -percentage
154              display  a percentage rather than the full progress bar.  Can be
155              used with dialog --gauge etc.
156
157       -ig, -ignore-errors
158              treat errors writing files to output as non-fatal.
159
160       -st, -strict-errors
161              treat all errors as fatal.
162
163       -no-exit, -no-exit-code
164              do not set exit code (to nonzero) on non-fatal errors.
165
166       -da SIZE, -data-queue SIZE
167              set data queue to SIZE Mbytes.  Default 256 Mbytes.
168
169       -fr SIZE, -frag-queue SIZE
170              set fragment queue to SIZE Mbytes.  Default 256 Mbytes.
171
172   Miscellaneous options:
173       -h, -help
174              output this options text to stdout.
175
176       -o BYTES, -offset BYTES
177              skip BYTES at start of FILESYSTEM.  Optionally a suffix of K,  M
178              or  G  can  be given to specify Kbytes, Mbytes or Gbytes respec‐
179              tively (default 0 bytes).
180
181       -fstime
182              synonym for -mkfs-time.
183
184       -e, -ef EXTRACT FILE
185              synonym for -extract-file.
186
187       -exc, -excf EXCLUDE FILE
188              synonym for -exclude-file.
189
190       -L     synonym for -follow-symlinks.
191
192       -pseudo-file FILE
193              alternative name for -pf.
194

DECOMPRESSORS AVAILABLE

196       gzip, lzo, lz4, xz, zstd, lzma
197

EXIT STATUS

199       0      The filesystem listed or extracted OK.
200
201       1      FATAL errors occurred, e.g. filesystem corruption,  I/O  errors.
202              Unsquashfs did not continue and aborted.
203
204       2      Non-fatal  errors occurred, e.g. no support for XATTRs, Symbolic
205              links in output filesystem or couldn't write permissions to out‐
206              put filesystem. Unsquashfs continued and did not abort.
207
208       See  -ignore-errors,  -strict-errors  and -no-exit-code options for how
209       they affect the exit status.
210

EXAMPLES

212       unsquashfs IMAGE.SQFS
213              Extract IMAGE.SQFS to "squashfs-root" in the current working di‐
214              rectory.
215
216       unsquashfs -d output IMAGE.SQFS
217              Extract IMAGE.SQFS to "output" in the current working directory.
218
219       unsquashfs -d . IMAGE.SQFS
220              Extract IMAGE.SQFS to current working directory.
221
222       unsquashfs -linfo IMAGE.SQFS
223              Output  a  listing of IMAGE.SQFS with file attributes to stdout,
224              while extracting the filesystem to "squashfs-root".
225
226       unsquashfs -lls IMAGE.SQFS
227              Output a listing of IMAGE.SQFS with file attributes  to  stdout,
228              but do not extract the filesystem.  The listing will be prefixed
229              with "squashfs-root".
230
231       unsquashfs -d "" -lls IMAGE.SQFS
232              Output a listing of IMAGE.SQFS with file attributes  to  stdout,
233              but do not extract the filesystem.  The listing will not be pre‐
234              fixed with "squashfs-root".
235
236       unsquashfs IMAGE.SQFS fs/squashfs
237              Extract only the "fs/squashfs" directory.
238
239       unsquashfs IMAGE.SQFS "[Tt]est/example*"
240              Extract all files beginning with "example" inside top level  di‐
241              rectories called "Test" or "test".
242
243       unsquashfs -excludes IMAGE.SQFS "test/*data*.gz"
244              This  will  extract  everything  except  for  files  that  match
245              *data*.gz in the test directory.  The -excludes option tells Un‐
246              squashfs  to  exclude  the files on the command line rather than
247              extract them.
248
249       unsquashfs -excludes IMAGE.SQFS "... *.gz"
250              This will extract everything except for files  that  match  *.gz
251              anywhere  in the image.   The "..." means this is a non-anchored
252              exclude which matches anywhere.
253
254       unsquashfs -ex "test/*data*.gz" ; IMAGE.SQFS test
255              This uses both extract and exclude options, to  tell  Unsquashfs
256              to  only  extract the "test" directory, and to exclude any files
257              within it that match *data*.gz.
258
259       unsquashfs -ex "... *.gz" IMAGE.SQFS test
260              This uses both extract and exclude options, to  tell  Unsquashfs
261              to only extract the "test" directory, and to exclude files which
262              match "*.gz" anywhere within "test"  directory  or  sub-directo‐
263              ries.
264
265       unsquashfs -dest output -max-depth 2 IMAGE.SQFS
266              Extract only the top two levels of IMAGE.SQFS to "output" direc‐
267              tory.
268
269       unsquashfs -max-depth 2 IMAGE.SQFS "test/*.gz"
270              Only extract the gzipped files in the test directory.
271
272       unsquashfs -llc -max-depth 2 IMAGE.SQFS "test/*.gz"
273              Output a listing of the gzipped files in the test  directory  to
274              stdout, but do not extract them.
275
276       unsquashfs -no-xattrs IMAGE.SQFS
277              Do not extract any extended attributes.  Any extended attributes
278              in the filesystem will be ignored.
279
280       unsquashfs -xattrs-include "^user." IMAGE.SQFS
281              Filter the extended attributes and  only  extract  extended  at‐
282              tributes in the user namespace from the Squashfs filesystem.
283
284       unsquashfs -xattrs-exclude "^user." IMAGE.SQFS
285              Filter  the  extended attributes and do not extract any extended
286              attributes in the user namespace from the Squashfs filesystem.
287
288       Note: when passing wildcarded  names  to  Unsquashfs,  they  should  be
289       quoted  (as  in  the  above examples), to ensure that they are not pro‐
290       cessed by the shell.
291

AUTHOR

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

COPYRIGHT

296       Copyright © 2023 Phillip Lougher <phillip@squashfs.org.uk>
297
298       This program is free software; you can redistribute it and/or modify it
299       under  the  terms of the GNU General Public License as published by the
300       Free Software Foundation; either version 2, or  (at  your  option)  any
301       later version.
302
303       This  program  is  distributed  in the hope that it will be useful, but
304       WITHOUT ANY  WARRANTY;  without  even  the  implied  warranty  of  MER‐
305       CHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
306       Public License for more details.
307