diff options
Diffstat (limited to 'USAGE-SQFSTAR-4.6')
| -rw-r--r-- | USAGE-SQFSTAR-4.6 | 812 |
1 files changed, 812 insertions, 0 deletions
diff --git a/USAGE-SQFSTAR-4.6 b/USAGE-SQFSTAR-4.6 new file mode 100644 index 0000000..9b5f0e8 --- /dev/null +++ b/USAGE-SQFSTAR-4.6 @@ -0,0 +1,812 @@ + SQFSTAR - A tool to create a Squashfs filesystem from a TAR archive + +Sqfstar will read an uncompressed TAR archive from standard in, and it will +create a Squashfs filesystem from it. If a TAR archive is compressed it +should be piped through a decompressor utility and then input into Sqfstar. + +Sqfstar supports V7, ustar, bsdtar (libarchive), GNU tar and PAX extensions. +Sparse file extensions are supported, including the "old GNU format, type S", +and PAX formats, Versions 0.0, 0.1 and the current 1.0. + +Sqfstar supports extended attributes, and recognises the SCHILY xattr +PAX extension (used by GNU tar), and the LIBARCHIVE xattr PAX extension +(used by bsdtar). + +The Sqfstar usage info is: + +SYNTAX:sqfstar [OPTIONS] FILESYSTEM [list of exclude dirs/files] + +Filesystem compression options: +-b <block_size> set data block to <block_size>. Default 128 Kbytes. + Optionally a suffix of K or M can be given to specify + Kbytes or Mbytes respectively +-comp <comp> select <comp> compression + Compressors available: + gzip (default) + lzo + lz4 + xz + zstd +-noI do not compress inode table +-noId do not compress the uid/gid table (implied by -noI) +-noD do not compress data blocks +-noF do not compress fragment blocks +-noX do not compress extended attributes +-no-compression do not compress any of the data or metadata. This is + equivalent to specifying -noI -noD -noF and -noX + +Filesystem build options: +-reproducible build filesystems that are reproducible (default) +-not-reproducible build filesystems that are not reproducible +-mkfs-time <time> set filesystem creation timestamp to <time>. <time> can + be an unsigned 32-bit int indicating seconds since the + epoch (1970-01-01) or a string value which is passed to + the "date" command to parse. Any string value which the + date command recognises can be used such as "now", + "last week", or "Wed Feb 15 21:02:39 GMT 2023" +-all-time <time> set all file timestamps to <time>. <time> can be an + unsigned 32-bit int indicating seconds since the epoch + (1970-01-01) or a string value which is passed to the + "date" command to parse. Any string value which the date + command recognises can be used such as "now", "last + week", or "Wed Feb 15 21:02:39 GMT 2023" +-root-time <time> set root directory time to <time>. <time> can be an + unsigned 32-bit int indicating seconds since the epoch + (1970-01-01) or a string value which is passed to the + "date" command to parse. Any string value which the date + command recognises can be used such as "now", "last + week", or "Wed Feb 15 21:02:39 GMT 2023" +-root-mode <mode> set root directory permissions to octal <mode> +-root-uid <value> set root directory owner to specified <value>, + <value> can be either an integer uid or user name +-root-gid <value> set root directory group to specified <value>, + <value> can be either an integer gid or group name +-all-root make all files owned by root +-force-uid <value> set all file uids to specified <value>, <value> can be + either an integer uid or user name +-force-gid <value> set all file gids to specified <value>, <value> can be + either an integer gid or group name +-default-mode <mode> tar files often do not store permissions for + intermediate directories. This option sets the default + directory permissions to octal <mode>, rather than 0755. + This also sets the root inode mode +-default-uid <uid> tar files often do not store uids for intermediate + directories. This option sets the default directory + owner to <uid>, rather than the user running Sqfstar. + This also sets the root inode uid +-default-gid <gid> tar files often do not store gids for intermediate + directories. This option sets the default directory + group to <gid>, rather than the group of the user + running Sqfstar. This also sets the root inode gid +-pseudo-override make pseudo file uids and gids override -all-root, + -force-uid and -force-gid options +-exports make the filesystem exportable via NFS +-no-sparse do not detect sparse files +-no-fragments do not use fragments +-no-tailends do not pack tail ends into fragments +-no-duplicates do not perform duplicate checking +-no-hardlinks do not hardlink files, instead store duplicates + +Filesystem filter options: +-p <pseudo-definition> add pseudo file definition. The definition should + be quoted +-pf <pseudo-file> add list of pseudo file definitions. Pseudo file + definitions in pseudo-files should not be quoted +-ef <exclude_file> list of exclude dirs/files. One per line +-regex allow POSIX regular expressions to be used in exclude + dirs/files +-ignore-zeros allow tar files to be concatenated together and fed to + Sqfstar. Normally a tarfile has two consecutive 512 + byte blocks filled with zeros which means EOF and + Sqfstar will stop reading after the first tar file on + encountering them. This option makes Sqfstar ignore the + zero filled blocks + +Filesystem extended attribute (xattrs) options: +-no-xattrs do not store extended attributes +-xattrs store extended attributes (default) +-xattrs-exclude <regex> exclude any xattr names matching <regex>. <regex> is a + POSIX regular expression, e.g. -xattrs-exclude '^user.' + excludes xattrs from the user namespace +-xattrs-include <regex> include any xattr names matching <regex>. <regex> is a + POSIX regular expression, e.g. -xattrs-include '^user.' + includes xattrs from the user namespace +-xattrs-add <name=val> add the xattr <name> with <val> to files. If an + user xattr it will be added to regular files and + directories (see man 7 xattr). Otherwise it will be + added to all files. <val> by default will be treated as + binary (i.e. an uninterpreted byte sequence), but it can + be prefixed with 0s, where it will be treated as base64 + encoded, or prefixed with 0x, where val will be treated + as hexidecimal. Additionally it can be prefixed with + 0t where this encoding is similar to binary encoding, + except backslashes are specially treated, and a + backslash followed by 3 octal digits can be used to + encode any ASCII character, which obviously can be used + to encode control codes. The option can be repeated + multiple times to add multiple xattrs + +Sqfstar runtime options: +-version print version, licence and copyright message +-force force Sqfstar to write to block device or file +-exit-on-error treat normally ignored errors as fatal +-quiet no verbose output +-info print files written to filesystem +-no-progress do not display the progress bar +-progress display progress bar when using the -info option +-percentage display a percentage rather than the full progress bar. + Can be used with dialog --gauge etc. +-throttle <percentage> throttle the I/O input rate by the given percentage. + This can be used to reduce the I/O and CPU consumption + of Sqfstar +-limit <percentage> limit the I/O input rate to the given percentage. + This can be used to reduce the I/O and CPU consumption + of Sqfstar (alternative to -throttle) +-processors <number> use <number> processors. By default will use number of + processors available +-mem <size> use <size> physical memory for caches. Use K, M or G to + specify Kbytes, Mbytes or Gbytes respectively +-mem-percent <percent> use <percent> physical memory for caches. Default 25% +-mem-default print default memory usage in Mbytes + +Expert options (these may make the filesystem unmountable): +-nopad do not pad filesystem to a multiple of 4K +-offset <offset> skip <offset> bytes at the beginning of FILESYSTEM. + Optionally a suffix of K, M or G can be given to specify + Kbytes, Mbytes or Gbytes respectively. + Default 0 bytes +-o <offset> synonym for -offset + +Miscellaneous options: +-fstime <time> alternative name for mkfs-time +-root-owned alternative name for -all-root +-noInodeCompression alternative name for -noI +-noIdTableCompression alternative name for -noId +-noDataCompression alternative name for -noD +-noFragmentCompression alternative name for -noF +-noXattrCompression alternative name for -noX + +-help output this options text to stdout +-h output this options text to stdout + +-Xhelp print compressor options for selected compressor + +Pseudo file definition format: +"filename d mode uid gid" create a directory +"filename m mode uid gid" modify filename +"filename b mode uid gid major minor" create a block device +"filename c mode uid gid major minor" create a character device +"filename f mode uid gid command" create file from stdout of command +"filename s mode uid gid symlink" create a symbolic link +"filename i mode uid gid [s|f]" create a socket (s) or FIFO (f) +"filename x name=val" create an extended attribute +"filename l linkname" create a hard-link to linkname +"filename L pseudo_filename" same, but link to pseudo file +"filename D time mode uid gid" create a directory with timestamp time +"filename M time mode uid gid" modify a file with timestamp time +"filename B time mode uid gid major minor" + create block device with timestamp time +"filename C time mode uid gid major minor" + create char device with timestamp time +"filename F time mode uid gid command" create file with timestamp time +"filename S time mode uid gid symlink" create symlink with timestamp time +"filename I time mode uid gid [s|f]" create socket/fifo with timestamp time + + +Files and directories in the TAR archive may be excluded, and both anchored +and non-anchored exclude files are supported (see section 6 and examples later). +Wildcards (globbing) is supported by default. + +Sqfstar can also by invoked by running "mksquashfs - image.sqfs -tar", if +the Sqfstar link isn't available. + +1. USAGE EXAMPLES +----------------- + +% sqfstar image.sqfs < archive.tar + + Create a Squashfs image from archive.tar, using defaults (gzip compression, + 128K blocks). + +% sqfstar -comp xz -b 1M image.sqfs < archive.tar + + As previous, but use XZ compression and 1Mbyte block sizes. + +% zcat archive.tgz | sqfstar image.sqfs + + Create a Squashfs image from a gzip compressed tar archive. + +% sqfstar -root-uid 0 -root-gid 0 image.sqfs < archive.tar + + Tar files do not supply a definition for the root directory, and the + default is to make the directory owned/group owned by the user running + Sqfstar. The above command sets the ownership/group ownership to root. + +% sqfstar -root-mode 0755 image.sqfs < archive.tar + + The default permissions for the root directory is 0777 (rwxrwxrwx). The + above command sets the permissions to 0755 (rwxr-xr-x). + +% sqfstar image.sqsh dir1/file1 dir2/file2 < archive.tar + + Create a Squashfs image but exclude the files "file1" and "file2". + +% sqfstar image.sqsh "... *.[ch]" < archive.tar + + Create a Squashfs image but exclude any file matching "*.[ch]" anywhere + in the archive. + + +2. CHANGING COMPRESSION ALGORITHM AND COMPRESSION SPECIFIC OPTIONS +------------------------------------------------------------------ + +By default Sqfstar will compress using the GZIP compression algorithm. This +algorithm offers a good trade-off between compression ratio, and memory and time +taken to decompress. + +Squashfs also supports LZ4, LZO, XZ and ZSTD compression. LZO offers worse +compression ratio than GZIP, but is faster to decompress. XZ offers better +compression ratio than GZIP, but at the expense of greater memory and time +to decompress (and significantly more time to compress). LZ4 is similar +to LZO. ZSTD has been developed by Facebook, and aims to compress well and +be fast to decompress. You should experiment with the compressors to +see which is best for you. + +If you're not building the squashfs-tools and kernel from source, then +the tools and kernel may or may not have been built with support for LZ4, LZO, +XZ or ZSTD compression. The compression algorithms supported by the build of +Sqfstar can be found by typing sqfstar -help. + +The full list of compressors available and their compression specific options +are: + +Compressors available and compressor specific options: + gzip (default) + -Xcompression-level <compression-level> + <compression-level> should be 1 .. 9 (default 9) + -Xwindow-size <window-size> + <window-size> should be 8 .. 15 (default 15) + -Xstrategy strategy1,strategy2,...,strategyN + Compress using strategy1,strategy2,...,strategyN in turn + and choose the best compression. + Available strategies: default, filtered, huffman_only, + run_length_encoded and fixed + lzo + -Xalgorithm <algorithm> + Where <algorithm> is one of: + lzo1x_1 + lzo1x_1_11 + lzo1x_1_12 + lzo1x_1_15 + lzo1x_999 (default) + -Xcompression-level <compression-level> + <compression-level> should be 1 .. 9 (default 8) + Only applies to lzo1x_999 algorithm + lz4 + -Xhc + Compress using LZ4 High Compression + xz + -Xbcj filter1,filter2,...,filterN + Compress using filter1,filter2,...,filterN in turn + (in addition to no filter), and choose the best compression. + Available filters: x86, arm, armthumb, powerpc, sparc, ia64 + -Xdict-size <dict-size> + Use <dict-size> as the XZ dictionary size. The dictionary size + can be specified as a percentage of the block size, or as an + absolute value. The dictionary size must be less than or equal + to the block size and 8192 bytes or larger. It must also be + storable in the xz header as either 2^n or as 2^n+2^(n+1). + Example dict-sizes are 75%, 50%, 37.5%, 25%, or 32K, 16K, 8K + etc. + zstd + -Xcompression-level <compression-level> + <compression-level> should be 1 .. 22 (default 15) + +If the compressor offers compression specific options (all the compressors now +have compression specific options except the deprecated lzma1 compressor) +then these options are also displayed (.i.e. in the above XZ is shown with two +compression specific options). The compression specific options are, obviously, +specific to the compressor in question, and the compressor documentation and +web sites should be consulted to understand their behaviour. In general +the Sqfstar compression defaults for each compressor are optimised to +give the best performance for each compressor, where what constitutes +best depends on the compressor. For GZIP/XZ best means highest compression, +for LZO/LZ4 best means a tradeoff between compression and (de)-compression +overhead (LZO/LZ4 by definition are intended for weaker processors). + +3. REDUCING CPU AND I/O USAGE +----------------------------- + +By default Sqfstar will use all the CPUs available to compress and create the +filesystem, and will read from the TAR archive and write to the output +filesystem as fast as possible. This maximises both CPU usage and I/O. + +Sometimes you don't want Sqfstar to use all CPU and I/O bandwidth. For those +cases Sqfstar supports two complementary options, -processors and -throttle. + +The -processors option can be used to reduce the number of parallel compression +threads used by Sqfstar. Reducing this to 1 will create the minimum number of +threads, and this will reduce CPU usage, and that in turn will reduce I/O +(because CPUs are normally the bottleneck). + +The -throttle option reduces the speed Sqfstar reads from the TAR archive. +The value is a percentage (obviously from 1 - 100), and 50 will reduce the +read rate by half (the read thread will spend half its time idling), and 75 +by three quarters. Reducing the speed of I/O will also reduce the CPU +usage as there is insufficient data rate to use all cores. + +Which option should you use? Both will effectively reduce CPU and I/O in +normal cases where intensive use is being made of both I/O and CPUs. But +in edge cases there can be an imbalance where reducing one has no effect, or +it can't be reduced any further. For instance when there is only 1 or 2 cores +available, setting -processors to the minimum of 1 may still use too much +CPU. Additionally if your input source is slow Sqfstar may still max it out +with -processors set to the minimum of 1. In this case you can use -throttle +in addition to -processors or on its own. + +4. CHANGING GLOBAL COMPRESSION DEFAULTS USED IN SQFSTAR +------------------------------------------------------- + +There are a large number of options that can be used to control the compression +in Sqfstar. By and large the defaults are the most optimum settings and should +rarely need to be changed. + +Note, this does not apply to the block size, increasing the block size from +the default of 128 Kbytes will increase compression (especially for the XZ and +ZSTD compressors) and should increase I/O performance too. However, a block +size of greater than 128 Kbytes may increase latency in certain cases (where the +filesystem contains lots of fragments, and no locality of reference is +observed). For this reason the block size default is configured to the less +optimal 128 Kbytes. Users should experiment with 256 Kbyte sizes or above. + +The -b option allows the block size to be selected, both "K" and "M" postfixes +are supported, this can be either 4K, 8K, 16K, 32K, 64K, 128K, 256K, 512K or +1M bytes. + +The -noI, -noD, -noF and -noX options can be used to force Sqfstar to not +compress inodes/directories, data, fragments and extended attributes +respectively. Giving all options generates an uncompressed filesystem. + +The -no-fragments option tells Sqfstar to not generate fragment blocks. A +fragment block consists of multiple small files (all smaller than the block +size) packed and compressed together. This produces much better compression +than storing and compressing these files separately. It also typically +improves I/O as multiple files in the same directory are read at the same time. +You don't want to enable this option unless you fully understand the effects. + +The -no-tailends option tells Sqfstar to not pack file tailends into fragment +blocks. Normally a file will not be a multiple of the block size, and so +there were always be a tail which doesn't fit fully into a data block. This +tailend is by default packed into fragment blocks. Enabling this option will +reduce compression. + +The -no-duplicates option tells Sqfstar to not check the files being added to +the filesystem for duplicates. This can result in quicker filesystem generation +although obviously compression will suffer badly if there is a lot of duplicate +files. + +5. SPECIFYING THE UIDs/GIDs USED IN THE FILESYSTEM +-------------------------------------------------- + +By default files in the generated filesystem use the ownership of the file +stored in the TAR archive. TAR archives depending on the TAR format stores +ownership in two ways. The early V7 format only stored a numeric UID and GID. +If Sqfstar is reading a V7 archive these are used. Later ustar and PAX +archives can also store a string user name and group name. If these are +present and are recognised by the system (i.e. can be mapped to a UID and GID), +their UID and GID is used. If a user name or group name is not recognised +by the system, the numeric UID or GID is used. + +The -all-root option forces all file UIDs/GIDs in the generated Squashfs +filesystem to be root. This allows root owned filesystems to be built without +root access on the host machine. + +The "-force-uid value" option forces all files in the generated Squashfs +filesystem to be owned by value, where value can either be a user name or a +numeric UID. + +The "-force-gid value" option forces all files in the generated Squashfs +filesystem to be group owned by value, where value can be either a group name or +a numeric GID. + +6. EXCLUDING FILES FROM THE FILESYSTEM +-------------------------------------- + +Sqfstar can exclude files from the TAR archive, so that they don't appear in +the Squashfs filesystem. Exclude files can be directly specified on +the command line (immediately after the FILESYSTEM argument), or the -ef +option can be used to specify an exclude file, with one exclude file per line. + +Exclude files by default use wildcard matching (globbing) and can match on +more than one file (if wildcards are used). Regular expression matching +can be used instead by specifying the -regex option. In most cases wildcards +should be used rather than regular expressions because wildcard matching +behaviour is significantly easier to understand! + +In addition to wildcards/regex expressions, exclude files can be "anchored" or +"non-anchored". An anchored exclude is one which matches from the root of the +directory and nowhere else, a non-anchored exclude matches anywhere. For +example given the directory hierarchy "a/b/c/a/b", the anchored exclude "a/b" +will match "a/b" at the root of the directory hierarchy, but it will not match +the "/a/b" sub-directory within directory "c", whereas a non-anchored exclude +would. + +A couple of examples should make this clearer. + +Anchored excludes + + 1. sqfstar image.sqsh 'test/*.gz' < archive.tar + + Exclude all files matching "*.gz" in the top level directory "test". + + 2. sqfstar image.sqsh '*/[Tt]est/example*' < archive.tar + + Exclude all files beginning with "example" inside directories called + "Test" or "test", that occur inside any top level directory. + + Using extended wildcards, negative matching is also possible. + + 3. sqfstar image.sqsh 'test/!(*data*).gz' < archive.tar + + Exclude all files matching "*.gz" in top level directory "test", + except those with "data" in the name. + +Non-anchored excludes + + By default excludes match from the top level directory, but it is + often useful to exclude a file matching anywhere in the source directories. + For this non-anchored excludes can be used, specified by pre-fixing the + exclude with "...". + + Examples: + + 1. sqfstar image.sqsh '... *.gz' < archive.tar + + Exclude files matching "*.gz" anywhere in the source directories. + For example this will match "example.gz", "test/example.gz", and + "test/test/example.gz". + + 2. sqfstar image.sqsh '... [Tt]est/*.gz' < archive.tar + + Exclude files matching "*.gz" inside directories called "Test" or + "test" that occur anywhere in the source directories. + + Again, using extended wildcards, negative matching is also possible. + + 3. sqfstar image.sqsh '... !(*data*).gz' < archive.tar + + Exclude all files matching "*.gz" anywhere in the source directories, + except those with "data" in the name. + + +7. FILTERING AND ADDING EXTENDED ATTRIBUTES (XATTRs) +---------------------------------------------------- + +Sqfstar has a number of options which allow extended attributes (xattrs) to be +filtered from the TAR archive or added to the created Squashfs filesystem. + +The -no-xattrs option removes any extended attributes which may exist in the +TAR archive, and creates a filesystem without any extended attributes. + +The -xattrs-exclude option specifies a regular expression (regex), which +removes any extended attribute that matches the regular expression from all +files. For example the regex '^user.' will remove all User extended attributes. + +The -xattrs-include option instead specifies a regular expression (regex) +which includes any extended attribute that matches, and removes anything +that does't match. For example the regex '^user.' will only keep User +extended attributes and anything else will be removed. + +Sqfstar also allows you to add extended attributes to files in the Squashfs +filesystem using the -xattrs-add option. This option takes an xattr name and +value pair separated by the '=' character. + +The extended attribute name can be any valid name and can be in the namespaces +security, system, trusted, or user. User extended attributes are added to files +and directories (see man 7 xattr for explanation), and the others are added to +all files. + +The extended attribute value by default will be treated as binary (i.e. an +uninterpreted byte sequence), but it can be prefixed with 0s, where it will be +treated as base64 encoded, or prefixed with 0x, where it will be treated as +hexidecimal. + +Obviously using base64 or hexidecimal allows values to be used that cannot be +entered on the command line such as non-printable characters etc. But it +renders the string non-human readable. To keep readability and to allow +non-printable characters to be entered, the 0t prefix is supported. This +encoding is similar to binary encoding, except backslashes are specially +treated, and a backslash followed by three octal digits can be used to encode +any ASCII character, which obviously can be used to encode non-printable values. + +The following four command lines are equivalent + +sqfstar -xattrs-add "user.comment=hello world" image.sqfs +sqfstar -xattrs-add "user.comment=0saGVsbG8gd29ybGQ=" image.sqfs +sqfstar -xattrs-add "user.comment=0x68656c6c6f20776f726c64" +sqfstar -xattrs-add "user.comment=0thello world" image.sqfs + +Obviously in the above example there are no non-printable characters and so +the 0t prefixed string is identical to the first line. The following three +command lines are identical, but where the space has been replaced by the +non-printable NUL '\0' (null character). + +sqfstar -xattrs-add "user.comment=0thello\000world" image.sqfs +sqfstar -xattrs-add "user.comment=0saGVsbG8Ad29ybGQ=" image.sqfs +sqfstar -xattrs-add "user.comment=0x68656c6c6f00776f726c64" image.sqsh + +8. PSEUDO FILE SUPPORT +---------------------- + +Sqfstar supports pseudo files, these allow files, directories, character +devices, block devices, fifos, symbolic links, hard links and extended +attributes to be specified and added to the Squashfs filesystem being built, +rather than requiring them to be present in the TAR archive. This, for example, +allows device nodes to be added to the filesystem without requiring root access. + +Pseudo files also support "dynamic pseudo files" and a modify operation. +Dynamic pseudo files allow files to be dynamically created when Sqfstar +is run, their contents being the result of running a command or piece of +shell script. The modifiy operation allows the mode/uid/gid of an existing +file in the source filesystem to be modified. + +Two Sqfstar options are supported, -p allows one pseudo file to be specified +on the command line, and -pf allows a pseudo file to be specified containing a +list of pseduo definitions, one per line. + +8.1 CREATING A DYNAMIC FILE +--------------------------- + +Pseudo definition + +Filename f mode uid gid command + +mode is the octal mode specifier, similar to that expected by chmod. + +uid and gid can be either specified as a decimal number, or by name. + +command can be an executable or a piece of shell script, and it is executed +by running "/bin/sh -c command". The stdout becomes the contents of +"Filename". + +Examples: + +Running a basic command +----------------------- + +/somedir/dmesg f 444 root root dmesg + +creates a file "/somedir/dmesg" containing the output from dmesg. + +Executing shell script +---------------------- + +RELEASE f 444 root root \ + if [ ! -e /tmp/ver ]; then \ + echo 0 > /tmp/ver; \ + fi; \ + ver=`cat /tmp/ver`; \ + ver=$((ver +1)); \ + echo $ver > /tmp/ver; \ + echo -n `cat /tmp/release`; \ + echo "-dev #"$ver `date` "Build host" `hostname` + +Creates a file RELEASE containing the release name, date, build host, and +an incrementing version number. The incrementing version is a side-effect +of executing the shell script, and ensures every time Sqfstar is run a +new version number is used without requiring any other shell scripting. + +The above example also shows that commands can be split across multiple lines +using "\". Obviously as the script will be presented to the shell as a single +line, a semicolon is need to separate individual shell commands within the +shell script. + +Reading from a device (or fifo/named socket) +-------------------------------------------- + +input f 444 root root dd if=/dev/sda1 bs=1024 count=10 + +Copies 10K from the device /dev/sda1 into the file input. Ordinarily Sqfstar +given a device, fifo, or named socket will place that special file within the +Squashfs filesystem, the above allows input from these special files to be +captured and placed in the Squashfs filesystem. + +8.2 CREATING A BLOCK OR CHARACTER DEVICE +---------------------------------------- + +Pseudo definition + +Filename type mode uid gid major minor + +Where type is either + b - for block devices, and + c - for character devices + +mode is the octal mode specifier, similar to that expected by chmod. + +uid and gid can be either specified as a decimal number, or by name. + +For example: + +/dev/chr_dev c 666 root root 100 1 +/dev/blk_dev b 666 0 0 200 200 + +creates a character device "/dev/chr_dev" with major:minor 100:1 and +a block device "/dev/blk_dev" with major:minor 200:200, both with root +uid/gid and a mode of rw-rw-rw. + +8.3 CREATING A DIRECTORY +------------------------ + +Pseudo definition + +Filename d mode uid gid + +mode is the octal mode specifier, similar to that expected by chmod. + +uid and gid can be either specified as a decimal number, or by name. + +For example: + +/pseudo_dir d 666 root root + +creates a directory "/pseudo_dir" with root uid/gid and mode of rw-rw-rw. + +8.4 CREATING A SYMBOLIC LINK +---------------------------- + +Pseudo definition + +Filename s mode uid gid symlink + +uid and gid can be either specified as a decimal number, or by name. + +Note mode is ignored, as symlinks always have "rwxrwxrwx" permissions. + +For example: + +symlink s 0 root root example + +Creates a symlink "symlink" to file "example" with root uid/gid. + +8.5 CREATING HARD LINKS (FILE REFERENCES) +----------------------------------------- + +The "f" Pseudo definition allows a regular file to be created from the output of +a command (or shell). Often this is used to reference a file outside the source +directories by executing "cat", e.g. + +README f 0555 0 0 cat /home/phillip/latest-version/README + +Because this is a quite frequent use of the definition, an alternative faster +"File reference" or Hard Link Pseudo definition exists: + +README l /home/phillip/latest-version/README + +Will create a reference to "/home/phillip/latest-version/README", +and obviously the timestamp/mode and owership will be used. + +The definition also can be used to create additional references to files +within the source directories. For instance if "phillip/latest/README" was a +file being added to the filesystem, then + +README l phillip/latest/README + +Will create a Hard Link (and increment the nlink count on the inode). + +In both cases, the path to the file being referenced is the system +filesystem path, and can be absolute (prefixed with /), or relative +to the current working directory. + +There is an additional 'L' Pseudo definition, which closes a loophole in +the above 'l' definition. The 'l' Pseudo definition cannot create references +or Hard Links to files created by Pseudo definitions, because by +definition they do not exist in the system filesystem. + +with 'L' the referenced file is expected to be a Pseudo file, and in this case +the path is taken to be from the root of the Squashfs filesystem being created, +e.g. + +char-dev c 0555 0 0 1 2 + +link L char-dev + +Will create a Hard Link named "link" to the character device called "char-dev" +created by the previous Pseudo definition. + +8.6 CREATING SOCKETS/FIFOS +-------------------------- + +Pseudo definition + +filename i mode uid gid [s|f] + +To create a Unix domain socket, 's' should be used, i.e. + +filename i 0777 root root s + +and to create a FIFO, 'f' should be used, i.e. + +filename i 0777 root root f + +8.7 ADDING EXTENDED ATTRIBUTES TO FILES +--------------------------------------- + +Pseudo definition + +filename x name=val + +Will add the extended attribute <name> to <filename> with <val > contents. See +Section 7 for a description of the <val> formats supported. + +8.8 MODIFYING ATTRIBUTES OF AN EXISTING FILE +-------------------------------------------- + +Pseudo definition + +Filename m mode uid gid + +mode is the octal mode specifier, similar to that expected by chmod. + +uid and gid can be either specified as a decimal number, or by name. + +For example: + +dmesg m 666 root root + +Changes the attributes of the file "dmesg" in the filesystem to have +root uid/gid and a mode of rw-rw-rw, overriding the attributes obtained +from the TAR archive. + + +9. EXTENDED PSEUDO FILE DEFINITIONS WITH TIMESTAMPS +--------------------------------------------------- + +The Pseudo file definitions described above do not allow the timestamp +of the created file to be specified, and the files will be timestamped +with the current time. + +Extended versions of the Pseudo file definitions are supported which +take a <time> timestamp. These are distinquished from the previous +definitions by using an upper-case type character. For example the "D" +definition is identical to the "d" definition, but it takes a <time> +timestamp. + +The list of extended definitions are: + + filename F time mode uid gid command + filename D time mode uid gid + filename B time mode uid gid major minor + filename C time mode uid gid major minor + filename S time mode uid gid symlink + filename I time mode uid gid [s|f] + filename M time mode uid gid + +<time> can be either an unsigned decimal integer (which represents the +seconds since the epoch of 1970-01-01 00:00 UTC), or a "date string" +which is parsed and converted into an integer since the epoch, by calling +the "date" command. + +Because most date strings have spaces, they will need to be quoted, and if +entered on the command line, these quotes will need to be protected from the +shell by backslashes, i.e. + +% sqfstar img.sqfs -p "file D \"1 jan 1980\" 0777 phillip phillip" < archive.tar + +Obviously anything "date" accepts as a valid string can be used, such as +"yesterday", "last week" etc. + + +10. MISCELLANEOUS OPTIONS +------------------------ + +The -info option displays the files/directories as they are compressed and +added to the filesystem. The original uncompressed size of each file +is printed, along with DUPLICATE if the file is a duplicate of a +file in the filesystem. + +The -nopad option informs Sqfstar to not pad the filesystem to a 4K multiple. +This is performed by default to enable the output filesystem file to be mounted +by loopback, which requires files to be a 4K multiple. If the filesystem is +being written to a block device, or is to be stored in a bootimage, the extra +pad bytes are not needed. |