1GENSQUASHFS(1) User Commands GENSQUASHFS(1)
2
6 gensquashfs - generate squashfs images
7
9 gensquashfs [OPTIONS] <squashfs-file>
10
12 Generate a SquashFS image.
13
15 --pack-file, -F <file>
16 Use a gen_init_cpio style description file. The file format is
17 specified below. If --pack-dir is used, input file paths are
18 relative to the pack directory, otherwise they are relative to
19 the directory the pack file is in.
20 --pack-dir, -D <directory>
22 If --pack-file is used, this is the root path relative to which
23 to read files. If no pack file is specified, pack the contents
24 of the given directory into a SquashFS image. The directory be‐
25 comes the root of the file system.
26 --sort-file, -S <file>
28 Specify a file that can override the order in which input files
29 are packed, or affect packing behaviour (e.g. disable compres‐
30 sion or fragmentation for certain files).
31 --compressor, -c <name>
33 Select the compressor to use. Run gensquashfs --help to get a
34 list of all available compressors and the default selection.
35 --comp-extra, -X <options>
37 A comma separated list of extra options for the selected com‐
38 pressor. Specify help to get a list of available options.
39 --num-jobs, -j <count>
41 If libsquashfs was compiled with a built in thread pool based,
42 parallel data compressor, this option can be used to set the
43 number of compressor threads. If not set, the default is the
44 number of available CPU cores.
45 --queue-backlog, -Q <count>
47 Maximum number of data blocks in the thread worker queue before
48 the packer starts waiting for the block processors to catch up.
49 Higher values result in higher memory consumption. Defaults to
50 10 times the number of workers.
51 --block-size, -b <size>
53 Block size to use for Squashfs image. Defaults to 131072.
54 --dev-block-size, -B <size>
56 Device block size to padd the image to. Defaults to 4096.
57 --keep-time, -k
59 When using --pack-dir only, use the timestamps from the input
60 files instead of setting defaults on all input paths. The root
61 inode and the modification time on the SquashFS image itself
62 will still be set to defaults.
63 --one-file-system, -o
65 When using --pack-dir only, stay in the local filesystem and do
66 not cross mount points.
67 --defaults, -d <options>
69 A comma separated list of default values for implicitly created
70 directories. The following values can be set:
71 ┌──────────────┬────────────────────────────────────────┐
73 │Option │ Default │
74 ├──────────────┼────────────────────────────────────────┤
75 │uid=<value> │ 0 │
76 ├──────────────┼────────────────────────────────────────┤
77 │gid=<value> │ 0 │
78 ├──────────────┼────────────────────────────────────────┤
79 │mode=<value> │ 0755 │
80 ├──────────────┼────────────────────────────────────────┤
81 │mtime=<value> │ $SOURCE_DATE_EPOCH if set, 0 otherwise │
82 └──────────────┴────────────────────────────────────────┘
83 --set-uid, -u <number>
84 Force the owners user ID for ALL inodes to this value, no matter
85 what the pack file or directory entries actually specify.
86 --set-gid, -g <number>
88 Force the owners group ID for ALL inodes to this value, no mat‐
89 ter what the pack file or directory entries actually specify.
90 --all-root
92 A short hand for `--set-uid 0 --set-gid 0`.
93 --selinux, -s <file>
95 If built with SELinux support, use the given SELinux label file
96 to add context labels to the elements packed into the SquashFS
97 image.
98 --xattr-file, -A <file>
100 Read extended attributes from a file. The format for the file is
101 identical to the output generated by `getfattr --dump`.
102 --exportable, -e
104 Generate an export table for NFS support.
105 --no-tail-packing, -T
107 Do not perform tail end packing on files that are larger than
108 the specified block size.
109 --force, -f
111 Overwrite the output file if it exists.
112 --quiet, -q
114 Do not print out progress reports.
115 --help, -h
117 Print help text and exit.
118 --version, -V
120 Print version information and exit.
121
123 The input file contains a simple, newline separated list that describe
124 the files to be included in the squashfs image:
125 # a comment
127 file <path> <mode> <uid> <gid> [<location>]
128 dir <path> <mode> <uid> <gid>
129 nod <path> <mode> <uid> <gid> <dev_type> <maj> <min>
130 slink <path> <mode> <uid> <gid> <target>
131 link <path> <dummy> <dummy> <dummy> <target>
132 pipe <path> <mode> <uid> <gid>
133 sock <path> <mode> <uid> <gid>
134 glob <path> <mode|*> <uid|*> <gid|*> [OPTIONS...] <location>
135 ┌───────────┬────────────────────────────────────────┐
138 │<path> │ Absolute path of the entry in the im‐ │
139 │ │ age. Can be put in quotes if some com‐ │
140 │ │ ponents contain spaces. │
141 ├───────────┼────────────────────────────────────────┤
142 │<location> │ Optional location of the input file. │
143 │ │ Can be specified relative to either │
144 │ │ the description file or the pack di‐ │
145 │ │ rectory. If omitted, the image path is │
146 │ │ used as a relative path. │
147 ├───────────┼────────────────────────────────────────┤
148 │<target> │ Symlink or hardlink target. │
149 ├───────────┼────────────────────────────────────────┤
150 │<mode> │ Mode/permissions of the entry. │
151 ├───────────┼────────────────────────────────────────┤
152 │<uid> │ Numeric user id. │
153 ├───────────┼────────────────────────────────────────┤
154 │<gid> │ Numeric group id. │
155 ├───────────┼────────────────────────────────────────┤
156 │<dev_type> │ Device type (b=block, c=character). │
157 ├───────────┼────────────────────────────────────────┤
158 │<maj> │ Major number of a device special file. │
159 ├───────────┼────────────────────────────────────────┤
160 │<min> │ Minor number of a device special file. │
161 └───────────┴────────────────────────────────────────┘
162 File Globbing
164 The glob command requires an input location which is interpreted rela‐
165 tive to the pack directory (or the input file if no directory was spec‐
166 ified). This location is scanned recursively and the contents are added
167 to the specified virtual path.
168 The specified mode, uid and gid are applied to all new entries added by
170 the glob. They can alternatively be set to the special value * to use
171 the value from the input directory.
172 In front of the source location, several additional options can be
174 specified to control the behavior of the glob command:
175 ┌────────────────┬────────────────────────────────────────────────────┐
178 │Option │ Description │
179 ├────────────────┼────────────────────────────────────────────────────┤
180 │-type │ Followed by a single space and a single, lowercase │
181 │ │ character describing the inode type to accept. │
182 │ │ Works similar to the -type option of the find com‐ │
183 │ │ mand. │
184 │ │ │
185 │ │ Possible values are b (block devices), c (charac‐ │
186 │ │ ter devices), d (directories), p (named pipes), f │
187 │ │ (regular files), l (symlinks) and s (sockets). │
188 │ │ │
189 │ │ If -type is not used, all are accepted. The first │
190 │ │ use clamps the selection down to a single type and │
191 │ │ subsequent uses allow additional types. │
192 ├────────────────┼────────────────────────────────────────────────────┤
193 │-xdev │ Do not cross mount points during a recursive glob. │
194 ├────────────────┼────────────────────────────────────────────────────┤
195 │-mount │ An alias for -xdev │
196 ├────────────────┼────────────────────────────────────────────────────┤
197 │-keeptime │ Use the time stamps from the scanned files. │
198 ├────────────────┼────────────────────────────────────────────────────┤
199 │-nonrecursive │ Do not descend into directories. │
200 │ │ │
201 │ │ Even if the type argument does not include direc‐ │
202 │ │ tories, it is still possible to recursively scan a │
203 │ │ hierarchy. In that case, the scanning will not add │
204 │ │ new directory nodes, but still recurse into a di‐ │
205 │ │ rectory if a coresponding node already exist in │
206 │ │ the virtual filesystem tree. │
207 │ │ │
208 │ │ So a typicall use case might be to first scan only │
209 │ │ the directories, and then do several narrower │
210 │ │ globs to fill them. │
211 ├────────────────┼────────────────────────────────────────────────────┤
212 │-name <pattern> │ Only add entries if their name matches a shell │
213 │ │ glob pattern. │
214 │ │ │
215 │ │ If the pattern is supposed to contain spaces, it │
216 │ │ can be wrapped in quotation marks ("..." or │
217 │ │ '...'). │
218 ├────────────────┼────────────────────────────────────────────────────┤
219 │-path <pattern> │ Only add entries if their full resulting path in │
220 │ │ the SquashFS image matches a shell glob pattern. │
221 │ │ Slashes in the path are only matched against │
222 │ │ slashes in the pattern and will never match a wild │
223 │ │ card character or a bracket expression containing │
224 │ │ a slash. │
225 │ │ │
226 │ │ The path is normalized, so it won't have a leading │
227 │ │ or trailing slash. │
228 └────────────────┴────────────────────────────────────────────────────┘
229 Any other, unknown string starting with - will be rejected as unknown
230 option. If the input path starts with -, the sequence -- can be used
231 to stop argument parsing, similar to many command line tools.
232 Example
234 # A simple squashfs image
235 dir /dev 0755 0 0
236 nod /dev/console 0600 0 0 c 5 1
237 dir /root 0700 0 0
238 dir /sbin 0755 0 0
239 # Add a file. Input is relative to pack dir or listing path
241 file /sbin/init 0755 0 0 ../init/sbin/init
242 # Read from ./bin/bash relative to pack dir or listing path
244 # /bin is created implicitly with default attributes.
245 file /bin/bash 0755 0 0
246 # file name with a space in it and a "special" name
248 file "/opt/my app/\"special\"/data" 0600 0 0
249 # collect the contents of ./lib and put it under /usr/lib
251 # mode and uid/gid are explictly set. First we collect the directory tree,
252 # then all so files, then all symlinks that don't end in ".so"
253 glob /usr/lib 0755 0 0 -type d ./lib
254 glob /usr/lib 0755 0 0 -type f -name "*.so.*" ./lib
255 glob /usr/lib 0777 0 0 -type l -name "*.so.*" ./lib
256
258 The sort file is has one entry per line, consisting of a numeric prior‐
259 ity and a filename. The name and the priority are separated by one or
260 more space character (including tabs) and the line can be intended. Any
261 leeding or preceeding spaces are dropped.
262 The priority is a 64 bit number and can be negative. Files not listed
264 in the sort file receive a default priority of 0. After processing the
265 sort file, before packing the input files, the file list is sorted by
266 priority, with lower values preceeding larger ones.
267 The given filename is matched against the actual path of the file in
269 the SquashFS file in the resulting image. It is not matched against the
270 input path, which may differ. Any file is allowed to match only once.
271 The first match encountered in the sort file will be used.
272 Lines can be empty or contain a single line comment, started with #.
274 Filenames can be wrapped can be wrapped in quotation marks ("...") if
275 necessary, with \ serving as an escape character for quotation marks or
276 itself.
277 To control the packing behavior, an optional list of flags can be in‐
279 serted between the priority and the filename. The flags are wrappe in
280 brackets and comma separated, e.g. [flag1,flag2,...]. The following
281 flags are supported:
282 ┌─────────────────┬────────────────────────────┐
285 │Flag │ Description │
286 ├─────────────────┼────────────────────────────┤
287 │glob │ Interpret the filename as │
288 │ │ a shell glob pattern and │
289 │ │ match all files that the │
290 │ │ pattern applies to. This │
291 │ │ performs path globbing, │
292 │ │ i.e. a wild card character │
293 │ │ (* or ?) or a bracket │
294 │ │ range ([]) cannot match a │
295 │ │ path separator. A slash │
296 │ │ must always be matched by │
297 │ │ an explicit slash. │
298 ├─────────────────┼────────────────────────────┤
299 │glob_no_path │ Same as glob, but disables │
300 │ │ path globbing. Wild cards │
301 │ │ are allowed to match │
302 │ │ slashes. │
303 ├─────────────────┼────────────────────────────┤
304 │align │ Force device block align‐ │
305 │ │ ment of the matched files, │
306 │ │ i.e. the compressed output │
307 │ │ always starts at a multi‐ │
308 │ │ ple of the device block │
309 │ │ size. Padding is inserted │
310 │ │ before and after. │
311 ├─────────────────┼────────────────────────────┤
312 │dont_fragment │ Do not perform tail-end │
313 │ │ packing for the matched │
314 │ │ files, always generate a │
315 │ │ sequence of independent │
316 │ │ blocks. │
317 ├─────────────────┼────────────────────────────┤
318 │dont_compress │ Do not compress the │
319 │ │ matched files. Note that │
320 │ │ if tail-end packing is │
321 │ │ performed, the entire │
322 │ │ fragment block is left un‐ │
323 │ │ compressed. │
324 ├─────────────────┼────────────────────────────┤
325 │dont_deduplicate │ Do not perform deduplica‐ │
326 │ │ tion on the matched files. │
327 │ │ If they are packed and the │
328 │ │ data blocks or the tail │
329 │ │ end happens to match a │
330 │ │ previously packed file, │
331 │ │ keep them anyway. │
332 ├─────────────────┼────────────────────────────┤
333 │nosparse │ Do not perform sparse file │
334 │ │ detection. If a matched │
335 │ │ file contians block of │
336 │ │ zero bytes, pack them as- │
337 │ │ is. │
338 └─────────────────┴────────────────────────────┘
339 Example
340 # Specify a packing order with file globbing
341 -8000 [glob] bin/*
342 -5000 [glob] lib/*
343 # glob_no_path means * is allowed to match /
345 -1000 [glob_no_path] share/*
346 # Our boot loader needs this
348 -100000 [dont_compress,dont_fragment,nosparse] boot/vmlinuz
349 # For demonstration, a quoted filename and no flags
351 1337 "usr/share/my \"special\" file "
352
354 The format for xattr files tries to be identical to the output of get‐
355 fattr.
356 Attributes are listed as key-value pairs with an = sign in between.
358 If a line starts with `# file: `, the rest of the line is interpreted
360 as an absolute path that the following xattrs are applied to.
361 Plain text values are wrapped in quotation marks ("...") and support
363 some escape sequences. Currently supported are \", \\ and \0<octal-se‐
364 quence>.
365 Raw binary values can encoded as hexadecimal or base64, by starting the
367 value with a 0x or 0s prefix respectively.
368 Example
371 # file: dev/
372 security.selinux="system_u:object_r:device_t:s0"
373 user.beverage_preference=0xCAFECAFEDECAFBAD
374 # file: dev/rfkill
376 security.selinux="system_u:object_r:wireless_device_t:s0"
377 system.posix_acl_access=0sSGVsbG8gdGhlcmUgOi0pCg==
378
380 If the command line switch --defaults is not used or no default mtime
381 is specified, the value of the environment variable SOURCE_DATE_EPOCH
382 is used for all file and filesystem timestamps.
383 If SOURCE_DATE_EPOCH is not set, not a parsable number or it is out of
385 range, the timestamps default to 0.
386 Environment variables are only used if no explicit command line
388 switches are set. Explicit command line switches are always preferred
389 over the environment variables.
390
392 rdsquashfs(1), tar2sqfs(1)
393
395 Written by David Oberhollenzer.
396
398 Copyright © 2019 David Oberhollenzer License GPLv3+: GNU GPL version 3
399 or later <https://gnu.org/licenses/gpl.html>.
400 This is free software: you are free to change and redistribute it.
401 There is NO WARRANTY, to the extent permitted by law.
402generate squashfs images November 2021 GENSQUASHFS(1)