GENSQUASHFS(1)

🎀 GENSQUASHFS 🎀

okay so bestie, welcome to the User Commands section, page GENSQUASHFS(1) 💅 this is the manual for gensquashfs, and she's a whole queen. no cap. let's get into it ✨

---

💖 NAME 💖

gensquashfs — generate squashfs images 🦋

---

🌈 SYNOPSIS 🌈

gensquashfs [OPTIONS] <squashfs-file>

---

👑 DESCRIPTION 👑

Generate a SquashFS image. that's it, that's the whole vibe. one job, and she does it slayfully. 🔥

---

✨ OPTIONS ✨

okay this is the main character section, buckle up 🫶 every flag, every default, nothing skipped, periodt.

• --pack-file, -F <file> — use a gen_init_cpio style description file. the format is specified below (iykyk). if --pack-dir is used, input file paths are relative to the pack directory, otherwise they're relative to the directory the pack file itself lives in.
• --pack-dir, -D <directory> — if --pack-file is used, this is the root path that files get read relative to. if there's no pack file specified, then pack the contents of the given directory into a SquashFS image. that directory becomes the root of the file system 👑
• --sort-file, -S <file> — specify a file that can override the order input files get packed in, or otherwise affect packing behaviour (like disabling compression or fragmentation for certain files, for example). little bit of a control freak, love that for her 💅
• --compressor, -c <name> — pick the compressor to use. run gensquashfs --help to get a list of all available compressors and the default selection. no guessing, just check the help.
• --comp-extra, -X <options> — a comma separated list of extra options for the selected compressor. specify help to get a list of available options.
• --num-jobs, -j <count> — if libsquashfs was compiled with a built in thread pool based, parallel data compressor, this one sets the number of compressor threads. if it's not set, the default is the number of available CPU cores. multithreading era ✨
• --queue-backlog, -Q <count> — the maximum number of data blocks in the thread worker queue before the packer starts waiting for the block processors to catch up. higher values mean higher memory consumption. defaults to 10 times the number of workers.
• --block-size, -b <size> — the block size to use for the SquashFS image. defaults to 131072.
• --dev-block-size, -B <size> — the device block size to pad the image to. defaults to 4096.
• --keep-time, -k — when using --pack-dir only, use the timestamps from the input files instead of setting defaults on all input paths. heads up tho: the root inode and the modification time on the SquashFS image itself will still be set to defaults.
• --one-file-system, -o — when using --pack-dir only, stay in the local filesystem and do not cross mount points. she stays in her lane, respectfully.
• --defaults, -d <options> — a comma separated list of default values for implicitly created directories. these are the values you can set:
  • uid=<value> — default 0
  • gid=<value> — default 0
  • mode=<value> — default 0755
  • mtime=<value> — default $SOURCE_DATE_EPOCH if set, 0 otherwise
• --set-uid, -u <number> — force the owner's user ID for ALL inodes to this value, no matter what the pack file or directory entries actually specify. like, she said what she said. 💀
• --set-gid, -g <number> — force the owner's group ID for ALL inodes to this value, no matter what the pack file or directory entries actually specify. same energy, different field.
• --all-root — a short hand for --set-uid 0 --set-gid 0. one flag, two jobs, efficiency icon ✨
• --selinux, -s <file> — if built with SELinux support, use the given SELinux label file to add context labels to the elements packed into the SquashFS image.
• --xattr-file, -A <file> — read extended attributes from a file. the format for the file is identical to the output generated by getfattr --dump.
• --exportable, -e — generate an export table for NFS support.
• --no-tail-packing, -T — do not perform tail end packing on files that are larger than the specified block size.
• --no-pad — do not pad the resulting image to device block size.

⚠️ bestie this one's spicy: it may result in an image that cannot be loop mounted. so like, know what you're doing 💀

• --force, -f — overwrite the output file if it exists. no asking, just sending it 🔥
• --quiet, -q — do not print out progress reports. silent mode, mysterious mode.
• --help, -h — print help text and exit. 🫶
• --version, -V — print version information and exit. 🎀

---

okay that's part one bestie, the rest is coming so don't go anywhere 👀💖

📦 PACK FILE FORMAT 📦

Okay bestie, the input file is literally just a simple, newline separated list that describes the files to be included in the squashfs image. It's giving very much:

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

Here's the tea on every single placeholder, no cap:

• <path> — Absolute path of the entry in the image. Can be put in quotes if some components contain spaces.
• <location> — 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.
• <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.

---

✨ File Globbing ✨

The glob command requires an input location 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. Recursive slay.

The specified mode, uid and gid are applied to all new entries added by the glob. They can alternatively be set to the special value * 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:

• -type — Followed by a single space and a single, lowercase character describing the inode type to accept. Works similar to the -type option of the find command. Possible values are b (block devices), c (character devices), d (directories), p (named pipes), f (regular files), l (symlinks) and s (sockets). If -type is not used, all are accepted. The first use clamps the selection down to a single type and subsequent uses allow additional types.
• -xdev — Do not cross mount points during a recursive glob.
• -mount — An alias for -xdev
• -keeptime — Use the time stamps from the scanned files.
• -nonrecursive — 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 new directory nodes, but still recurse into a directory if a corresponding node already exists in the virtual filesystem tree. So a typical use case might be to first scan only the directories, and then do several narrower globs to fill them.
• -name <pattern> — 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 '...').
• -path <pattern> — 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.

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. Protect the vibe.

---

🌸 Example 🌸

# 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

✨ SORT FILE FORMAT ✨

okay bestie, the sort file is one entry per line, and each line is just a numeric priority plus a filename. That's it. That's the whole vibe. 💅

The name and the priority get separated by one or more space characters — tabs count too, we're not picky — and the line is allowed to be indented. Any leading or trailing spaces just get dropped on the floor. 🧹

The priority is a 64 bit number and yeah, it can be negative. Files that don't show up in the sort file at all get a default priority of 0, no drama. After the sort file has been processed, but before the input files get packed, the file list is sorted by priority — lower values come first, larger ones after. Simple as.

The filename you give is matched against the actual path of the file in the SquashFS file in the resulting image. It is not matched against the input path, which may be different — lowkey important, don't sleep on that. Any file is allowed to match only once, and the first match encountered in the sort file is the one that wins. periodt. 👑

Lines can be empty, or they can hold a single line comment that starts with #. Filenames can be wrapped in quotation marks ("...") if they need to be, with \ serving as an escape character for quotation marks or for itself. 🎀

To control the packing behavior, you can slip an optional list of flags in between the priority and the filename. The flags get wrapped in brackets and comma separated, like [flag1,flag2,...]. Here's the full roster, no skips:

• glob — interpret the filename as a shell glob pattern and match all the files that the pattern applies to. This does path globbing, meaning a wild card character (* or ?) or a bracket range ([]) cannot match a path separator. A slash must always be matched by an explicit slash. 🌸
• glob_no_path — same as glob, but it disables path globbing. Wild cards are allowed to match slashes. 🦋
• align — force device block alignment of the matched files, i.e. the compressed output always starts at a multiple of the device block size. Padding gets inserted before and after. ✨
• dont_fragment — do not perform tail-end packing for the matched files; always generate a sequence of independent blocks. 🙈
• dont_compress — do not compress the matched files. Note that if tail-end packing is performed, the entire fragment block is left uncompressed. 😭
• dont_deduplicate — 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. 💀
• nosparse — do not perform sparse file detection. If a matched file contains a block of zero bytes, pack them as-is. 🔥

---

🌈 Example 🌈

# 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  "

---

🎀 XATTR FILE FORMAT 🎀

The format for xattr files is trying really hard to be identical to the output of getfattr, and honestly? It ate. 💅

Attributes are listed as key-value pairs with an = sign in between them.

If a line starts with # file: , then the rest of that line is interpreted as an absolute path that all the following xattrs get applied to. 📁

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

Raw binary values can be encoded as hexadecimal or base64 by starting the value with a 0x or 0s prefix respectively. Yes, 0s for base64, not a typo, we don't make the rules. 🫶

---

🌸 Example 🌸

# 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==

---

🌈 ENVIRONMENT 🌈

If the command line switch --defaults is not used, or no default mtime is specified, then the value of the environment variable SOURCE_DATE_EPOCH is used for all file and filesystem timestamps. 👑

If SOURCE_DATE_EPOCH is not set, or it's not a parsable number, or it's out of range, the timestamps default to 0. no thoughts, head empty, epoch zero. 💀

Environment variables are only used if no explicit command line switches are set. Explicit command line switches are always preferred over the environment variables. the command line is the main character here, fr fr. ✨

---

💖 SEE ALSO 💖

rdsquashfs(1), tar2sqfs(1)

---

🦋 AUTHOR 🦋

Written by David Oberhollenzer. 👑

---

⭐ COPYRIGHT ⭐

Copyright © 2019 David Oberhollenzer License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

bestie this is the part where I have to be so serious for one sec: NO WARRANTY, to the extent permitted by law. that's not me being dramatic, that's literally what it says. 😭

---

and that's a wrap on GENSQUASHFS(1) — this page generates squashfs images, it's dated November 2021, and you can find it filed under GENSQUASHFS(1) in the manual. go forth and pack some filesystems, you absolute icon 💅✨🫶