path: root/doc/gensquashfs.1

.TH GENSQUASHFS "1" "June 2019" "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\-\-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 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
.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\-\-exportable\fR, \fB\-e\fR
Generate an export table for NFS support.
.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 INPUT 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>
.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

.PP
Example:
.PP
.in +4n
.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
.fi
.in
.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.