aboutsummaryrefslogtreecommitdiff
path: root/bin/gensquashfs/gensquashfs.1
blob: 88f58c44b576aff192ba04ca290bd57b695a5128 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
.TH GENSQUASHFS "1" "November 2021" "generate squashfs images" "User Commands"
.SH NAME
gensquashfs \- generate squashfs images
.SH SYNOPSIS
.B gensquashfs
[\fI\,OPTIONS\/\fR] <squashfs-file>\/\fR
.SH DESCRIPTION
Generate a SquashFS image.
.SH OPTIONS
.TP
\fB\-\-pack\-file\fR, \fB\-F\fR <file>
Use a \fBgen_init_cpio\fR style description file. The file format is specified
below. If \fB\-\-pack\-dir\fR is used, input file paths are relative to the
pack directory, otherwise they are relative to the directory the pack file
is in.
.TP
\fB\-\-pack\-dir\fR, \fB\-D\fR <directory>
If \fB\-\-pack\-file\fR is used, this is the root path relative to which to
read files. If no pack file is specified, pack the contents of the given
directory into a SquashFS image. The directory becomes the root of the file
system.
.TP
\fB\-\-sort\-file\fR, \fB\-S\fR <file>
Specify a file that can override the order in which input files are packed,
or affect packing behaviour (e.g. disable compression or fragmentation for
certain files).
.TP
\fB\-\-compressor\fR, \fB\-c\fR <name>
Select the compressor to use.
Run \fBgensquashfs \-\-help\fR to get a list of all available compressors
and the default selection.
.TP
\fB\-\-comp\-extra\fR, \fB\-X\fR <options>
A comma separated list of extra options for the selected compressor. Specify
\fBhelp\fR to get a list of available options.
.TP
\fB\-\-num\-jobs\fR, \fB\-j\fR <count>
If libsquashfs was compiled with a built in thread pool based, parallel data
compressor, this option can be used to set the number of compressor
threads. If not set, the default is the number of available CPU cores.
.TP
\fB\-\-queue\-backlog\fR, \fB\-Q\fR <count>
Maximum number of data blocks in the thread worker queue before the packer
starts waiting for the block processors to catch up. Higher values result
in higher memory consumption. Defaults to 10 times the number of workers.
.TP
\fB\-\-block\-size\fR, \fB\-b\fR <size>
Block size to use for Squashfs image.
Defaults to 131072.
.TP
\fB\-\-dev\-block\-size\fR, \fB\-B\fR <size>
Device block size to padd the image to.
Defaults to 4096.
.TP
\fB\-\-keep\-time\fR, \fB\-k\fR
When using \fB\-\-pack\-dir\fR only, use the timestamps from the input files
instead of setting defaults on all input paths. The root inode and the
modification time on the SquashFS image itself will still be set to defaults.
.TP
\fB\-\-one\-file\-system\fR, \fB\-o\fR
When using \fB\-\-pack\-dir\fR only, stay in the local filesystem and do not
cross mount points.
.TP
\fB\-\-defaults\fR, \fB\-d\fR <options>
A comma separated list of default values for
implicitly created directories.
The following values can be set:
.TS
tab(;) allbox;
l l
l l
l l
l l
l l
rd.
\fBOption\fR;\fBDefault\fR
uid=<value>;0
gid=<value>;0
mode=<value>;0755
mtime=<value>;\fB$SOURCE\_DATE\_EPOCH\fR if set, 0 otherwise
.TE
.TP
\fB\-\-set\-uid\fR, \fB\-u\fR <number>
Force the owners user ID for ALL inodes to this value, no matter what the pack
file or directory entries actually specify.
.TP
\fB\-\-set\-gid\fR, \fB\-g\fR <number>
Force the owners group ID for ALL inodes to this value, no matter what the pack
file or directory entries actually specify.
.TP
\fB\-\-all\-root\fR
A short hand for `\-\-set\-uid 0 \-\-set\-gid 0`.
.TP
\fB\-\-selinux\fR, \fB\-s\fR <file>
If built with SELinux support, use the given SELinux label file to add context
labels to the elements packed into the SquashFS image.
.TP
\fB\-\-xattr-file\fR, \fB\-A\fR <file>
Read extended attributes from a file. The format for the file is identical to
the output generated by `\fBgetfattr \-\-dump\fR`.
.TP
\fB\-\-exportable\fR, \fB\-e\fR
Generate an export table for NFS support.
.TP
\fB\-\-no\-tail\-packing\fR, \fB\-T\fR
Do not perform tail end packing on files that are larger than the specified
block size.
.TP
\fB\-\-force\fR, \fB\-f\fR
Overwrite the output file if it exists.
.TP
\fB\-\-quiet\fR, \fB\-q\fR
Do not print out progress reports.
.TP
\fB\-\-help\fR, \fB\-h\fR
Print help text and exit.
.TP
\fB\-\-version\fR, \fB\-V\fR
Print version information and exit.
.SH PACK FILE FORMAT
The input file contains a simple, newline separated list that describe the
files to be included in the squashfs image:
.PP
.in +4n
.nf
# a comment
file <path> <mode> <uid> <gid> [<location>]
dir <path> <mode> <uid> <gid>
nod <path> <mode> <uid> <gid> <dev_type> <maj> <min>
slink <path> <mode> <uid> <gid> <target>
link <path> <dummy> <dummy> <dummy> <target>
pipe <path> <mode> <uid> <gid>
sock <path> <mode> <uid> <gid>
glob <path> <mode|*> <uid|*> <gid|*> [OPTIONS...] <location>
.fi
.in

.TS
tab(;) allbox;
l l
l l
l l
l l
l l
l l
l l
l l
l l
rd.
<path>;T{
Absolute path of the entry in the image. Can be put in quotes
if some components contain spaces.
T}
<location>;T{
Optional location of the input file. Can be specified relative to either the
description file or the pack directory. If omitted, the image path is used
as a relative path.
T}
<target>;Symlink or hardlink target.
<mode>;Mode/permissions of the entry.
<uid>;Numeric user id.
<gid>;Numeric group id.
<dev_type>;Device type (b=block, c=character).
<maj>;Major number of a device special file.
<min>;Minor number of a device special file.
.TE

.SS File Globbing
The \fBglob\fR command requires an \fIinput location\fR which is interpreted
relative to the pack directory (or the input file if no directory was
specified). This location is scanned recursively and the contents are added
to the specified virtual path.

The specified \fImode\fR, \fIuid\fR and \fIgid\fR are applied to all new
entries added by the glob. They can alternatively be set to the special
value \fB*\fR to use the value from the input directory.

In front of the source location, several additional options can be specified to
control the behavior of the glob command:

.TS
tab(;) allbox;
l l
l l
l l
l l
l l
l l
l l
l l
rd.
\fBOption\fR;\fBDescription\fR
\-type;T{
Followed by a single space and a single, lowercase character describing
the inode type to accept. Works similar to the \fB\-type\fR option of the
\fBfind\fR command.

Possible values are \fBb\fR (block devices), \fBc\fR  (character devices),
\fBd\fR (directories), \fBp\fR (named pipes), \fBf\fR (regular files),
\fBl\fR (symlinks) and \fBs\fR (sockets).

If \fB\-type\fR is not used, all are accepted. The first use clamps the
selection down to a single type and subsequent uses allow additional
types.
T}
\-xdev;Do not cross mount points during a recursive glob.
\-mount;An alias for \fB\-xdev\fR
\-keeptime;Use the time stamps from the scanned files.
\-nonrecursive;T{
Do not descend into directories.

Even if the type argument does not include directories, it is still possible to
recursively scan a hierarchy. In that case, the scanning will not add \fInew\fR
directory nodes, but still recurse into a directory if a coresponding node
already exist in the virtual filesystem tree.

So a typicall use case might be to first scan only the
directories, and then do several narrower globs to fill them.
T}
\-name <pattern>;T{
Only add entries if their name matches a shell glob pattern.

If the pattern is supposed to contain spaces, it can be wrapped in
quotation marks ("..." or '...').
T}
\-path <pattern>;T{
Only add entries if their full resulting path in the SquashFS image
matches a shell glob pattern. Slashes in the path are only matched
against slashes in the pattern and will never match a wild card
character or a bracket expression containing a slash.

The path is normalized, so it won't have a leading or trailing slash.
T}
.TE
.PP
Any other, unknown string starting with \- will be rejected as unknown option.
If the input path starts with \-, the sequence \-\- can be used to stop
argument parsing, similar to many command line tools.
.SS Example
.PP
.nf
# A simple squashfs image
dir /dev 0755 0 0
nod /dev/console 0600 0 0 c 5 1
dir /root 0700 0 0
dir /sbin 0755 0 0

# Add a file. Input is relative to pack dir or listing path
file /sbin/init 0755 0 0 ../init/sbin/init

# Read from ./bin/bash relative to pack dir or listing path
# /bin is created implicitly with default attributes.
file /bin/bash 0755 0 0

# file name with a space in it and a "special" name
file "/opt/my app/\\"special\\"/data" 0600 0 0

# collect the contents of ./lib and put it under /usr/lib
# mode and uid/gid are explictly set. First we collect the directory tree,
# then all so files, then all symlinks that don't end in ".so"
glob /usr/lib 0755 0 0 -type d ./lib
glob /usr/lib 0755 0 0 -type f -name "*.so.*" ./lib
glob /usr/lib 0777 0 0 -type l -name "*.so.*" ./lib
.fi
.SH SORT FILE FORMAT
The sort file is has one entry per line, consisting of a numeric priority and
a filename. The name and the priority are separated by one or more space
character (including tabs) and the line can be intended. Any leeding or
preceeding spaces are dropped.

The priority is a 64 bit number and can be negative. Files not listed in the
sort file receive a default priority of 0. After processing the sort file,
before packing the input files, the file list is sorted by priority, with lower
values preceeding larger ones.

The given filename is matched against the actual path of the file in the
SquashFS file in the resulting image. It is \fInot\fR matched against the input
path, which may differ. Any file is allowed to match only once. The first match
encountered in the sort file will be used.

Lines can be empty or contain a single line comment, started with
\fB#\fR. Filenames can be wrapped can be wrapped in quotation marks ("...") if
necessary, with \fB\\\fR serving as an escape character for quotation marks or
itself.

To control the packing behavior, an optional list of flags can be inserted
between the priority and the filename. The flags are wrappe in brackets and
comma separated, e.g. [flag1,flag2,...]. The following flags are supported:

.TS
tab(;) allbox;
l l
l l
l l
l l
l l
l l
l l
l l
rd.
\fBFlag\fR;\fBDescription\fR
glob;T{
Interpret the filename as a shell glob pattern and match all files that the
pattern applies to. This performs path globbing, i.e. a wild card
character (\fB*\fR or \fB?\fR) or a bracket range (\fB[]\fR) cannot match
a path separator. A slash must always be matched by an explicit slash.
T}
glob_no_path;T{
Same as \fBglob\fR, but disables path globbing. Wild cards are allowed to
match slashes.
T}
align;T{
Force device block alignment of the matched files, i.e. the compressed output
always starts at a multiple of the device block size. Padding is inserted before
and after.
T}
dont_fragment;T{
Do not perform tail-end packing for the matched files, always generate a
sequence of independent blocks.
T}
dont_compress;T{
Do not compress the matched files. Note that if tail-end packing is performed,
the entire fragment block is left uncompressed.
T}
dont_deduplicate;T{
Do not perform deduplication on the matched files. If they are packed and the
data blocks or the tail end happens to match a previously packed file, keep
them anyway.
T}
nosparse;T{
Do not perform sparse file detection. If a matched file contians block of zero
bytes, pack them as-is.
T}
.TE
.PP
.SS Example
.PP
.nf
# Specify a packing order with file globbing
-8000  [glob]          bin/*
-5000  [glob]          lib/*

# glob_no_path means * is allowed to match /
-1000  [glob_no_path]  share/*

# Our boot loader needs this
-100000  [dont_compress,dont_fragment,nosparse]  boot/vmlinuz

# For demonstration, a quoted filename and no flags
1337  "usr/share/my \\"special\\" file  "
.fi
.SH XATTR FILE FORMAT
The format for xattr files tries to be identical to the output
of \fBgetfattr\fR.

Attributes are listed as key-value pairs with an \fB=\fR sign in between.

If a line starts with `\fB# file: \fR`, the rest of the line is interpreted
as an absolute path that the following xattrs are applied to.

Plain text values are wrapped in quotation marks ("...") and support some
escape sequences.
Currently supported are \fB\\"\fR, \fB\\\\\fR and \fB\\0<octal-sequence>\fR.

Raw binary values can encoded as hexadecimal or base64, by starting the
value with a \fB0x\fR or \fB0s\fR prefix respectively.

.SS Example
.PP
.nf
# file: dev/
security.selinux="system_u:object_r:device_t:s0"
user.beverage_preference=0xCAFECAFEDECAFBAD

# file: dev/rfkill
security.selinux="system_u:object_r:wireless_device_t:s0"
system.posix_acl_access=0sSGVsbG8gdGhlcmUgOi0pCg==
.fi
.SH ENVIRONMENT
If the command line switch \fB\-\-defaults\fR is not used or no default mtime
is specified, the value of the environment variable \fBSOURCE\_DATE\_EPOCH\fR
is used for all file and filesystem timestamps.

If \fBSOURCE\_DATE\_EPOCH\fR is not set, not a parsable number or it is out of
range, the timestamps default to 0.

Environment variables are only used if no explicit command line switches
are set. Explicit command line switches are always preferred over the
environment variables.
.SH SEE ALSO
rdsquashfs(1), tar2sqfs(1)
.SH AUTHOR
Written by David Oberhollenzer.
.SH COPYRIGHT
Copyright \(co 2019 David Oberhollenzer
License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>.
.br
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.