mkqfs

Runs on:

Linux, Microsoft Windows

Options:

fstype

The type of filesystem to build, extract, or verify.

-a

(Optional) Specify that if a warning is generated, the execution fails.

-d

(Optional) Display warnings for undeclared intermediate directories. For example, if there's a target filesystem entry of /dir1/dir2, and /dir1 has never occurred explicitly in the buildfile, the patch file, the input directory, or as a child of a recursively included directory, then /dir1 is considered an undeclared intermediate directory.

To treat undeclared intermediate directories as errors, specify -a in addition to -d.

-f

(Optional) Force extraction to occur if the specified target folder already exists. The target folder is removed before extraction begins. Only valid when -x is used.

-h

(Optional) Print the help menu. If fstype is specified, the help menu for the specific filesystem is printed, otherwise a general help menu is printed.

-i fscontent_file

(Optional) When building or extracting a filesystem, write a summary of the contents of the filesystem to the specified file. Specify - (hyphen) to write the content to stdout.

If you specify -i when building a filesystem, the summary includes the paths of the source files on the host.

If you specify -i when extracting a filesystem, the summary is written instead of extracting the files themselves.

The summary also includes the digest of the files calculated using sha512-256. This information is useful, for example, for comparing to the digest of the source files as found on the host or a later version of the filesystem.

-o output

Specifies either the output image file (when building filesystem images) or the output folder (when extracting filesystem images). Mandatory only when building or extracting images.

-r paths…

(Optional) A list of paths separated by a colon (:) that are searched in the given order to resolve objects (files, links, etc.) when building filesystems.

If not specified, the default search path is the QNX_TARGET environment variable value. If QNX_TARGET is not set, an error is returned.

-s

(Optional) Print statistics when building filesystems.

-v

(Optional) Print additional information when building or extracting filesystems.

This option is mostly meant for debugging or viewing progress. Specify multiple -v options to increase the verbosity.

-x

Extract a filesystem image and dumps the contents to output.

Not all filesystems support extraction.

-y

Verify a filesystem image.

Not all filesystems support verification.

fstype_options

A set of mandatory and optional options for the specific type of filesystem. See Description for information on the available options.

input_file

A mandatory option that specifies one of the following files:

• when building an image, the filesystem buildfile
• when extracting or verifying an image, the filesystem image file
• when fstype is qtd, the filesystem image that the QNX Trusted Disk (QTD) image will protect

Description:

The mkqfs utility generates QNX-supported filesystems. Each supported filesystem can be built and, optionally, verified and extracted. The utility supports the generic options described in Options as well as filesystem-specific ones (which always use capital letters). Specific options are available for the following filesystems:

License checking

The mkqfs utility checks for a valid QNX license key before performing any operation. If the license check fails, the utility stops running and displays a diagnostic message. A license check may fail if the license key is expired, missing, or not currently activated, or if the key doesn’t contain the permissions needed to run the utility.

QNX Trusted Disk (QTD) options:

-A salt

(Optional) The cryptographic salt value (hex) to use to create the filesystem. The salt length must be at least as long as the chosen digest size (see -H) and a maximum of 128 bytes.

If omitted, the salt is randomly generated.

-B size

A mandatory option that specifies, in bytes, the chunk size to use when splitting the source image into chunks to hash. If the source image is a filesystem, use a size that is equal to or greater than the block size that the filesystem uses. Valid values are: 512, 1024, 2048, 4096, 8192, 16384, 32768. You can also specify this value as a number with one of the following suffixes: K, k, M, m, G, g, T, t.

-C size

(Optional) Calculate the size of the metadata tree using the provided image size in bytes. You can also specify this value as a number with one of the following suffixes: K, k, M, m, G, g, T, t.

-H hash

A mandatory option that specifies the cryptographic digest. Supported digests: sha256, sha512, sha512-256, blake2s256, blake2b256, blake2b512, and blake3.

-K key

A mandatory option that specifies either the private key (when building a QTD image) or public key (when verifying a QTD image). The key type must match the type of signature algorithm (see -S). See Cryptographic keys supported by QTD.

-M

(Optional) Restrict the output to QTD metadata.

-P size

(Optional) Build the filesystem image in partition mode, which forces the QTD image to extend to the size specified by size exactly. When you build an image or use -C, the statistics output provides the maximum size of the inner, wrapped filesystem image. You can specify the size as either a number, or a number with one of the following suffixes: K, k, M, m, G, g, T, t.

This option is required when you are building a QTD image to flash to a fixed-size disk partition.

-R version

(Optional) Specify the anti-rollback version as a 64-bit, unsigned integer. When combined with the filesystem driver rollback mount option, this value configures the system to deny the mounting of a filesystem image that has a version that is lower than the value passed to the mount option. This mechanism allows you to maintain the chain of trust in a secure boot environment.

You can use the qtdctl utility to query the rollback version from the QTD-mounted disk partition path. For more information, see qtdctl.

-S signature

A mandatory option that specifies the cryptographic signature algorithm. The following signature algorithms are supported:

Signature	Key type	Used for:
rsa-sha256	RSA	RSA-PKCS#1 v1.5 padding
ecdsa-sha256	EC	EC Digital Signature Algorithm
eddsa-25519	Ed25519	Edwards Digital Signature Algorithm (pure mode)
eddsa-448	Ed448

-X

(Optional) Re-sign the specified input image with a different key. Only the cryptographic signature of the QTD image changes.

This option requires -S, and -K or -Z.

For example, the following command re-signs the image qtd.img using the EC Digital Signature Algorithm and the private key new_private_key.pem. The name of the re-signed image is new_qtd.img:

mkqfs qtd -o new_qtd.img -X -S ecdsa-sha256 -K new_private_key.pem qtd.img

Alternatively, you can re-sign the image with a custom signing command (-Z). For example:

mkqfs qtd -o new_qtd.img -X -S rsa-sha256 -Z \
"openssl pkeyutl -sign -in <hashfile> -inkey new_private_key.pem -out <sigfile> -pkeyopt digest:sha256" qtd.img

-Z sign_cmd

(Optional) The custom signing command for the cryptographic signature of the QTD image. Custom signing allows you to use a custom utility that hides the private key while allowing signing to proceed. This method allows the signing operation to be done remotely through a utility you specify.

The following two tokens need to appear in the signing command. They are replaced by temporary files when the signing command is called:

<hashfile>

A placeholder for the path to the file that contains the sha256 digest in binary format that needs to be signed. If the signing algorithm is EdDSA, then the contents of the file is the raw binary data to sign. (The algorithm itself does the actual hash internally instead of being provided a hash as input.)

<sigfile>

A placeholder for the path to the file where the custom utility writes the signature in binary format.

<sbfile>

An optional placeholder for the path to the file where the custom utility writes the raw superblock to be signed in binary format. The format of the superblock can be viewed in the sys/fs_qtd.h header file.

For example, using openssl as the signing utility:

openssl pkeyutl -sign -in <hashfile> -inkey private_key.pem -out <sigfile> -pkeyopt digest:sha256

Cryptographic keys supported by QTD:

QTD supports EC and RSA keys. The private key must be in the PKCS#8 format and the public key must be in the X.509 format. All keys must use PEM encoding. For RSA, key lengths of up to 16 KiB (kibibits) are supported.

openssl genpkey -algorithm RSA -out rsa_private_key.pem -pkeyopt rsa_keygen_bits:2048
openssl pkey -in rsa_private_key.pem -pubout -out rsa_public_key.pem

openssl ecparam -name prime256v1 -param_enc explicit -no_seed -out ec_params.pem -outform PEM
openssl genpkey -paramfile ec_params.pem -out ec_private_key.pem
openssl pkey -in ec_private_key.pem -pubout -out ec_public_key.pem

openssl genpkey -algorithm ed448 -outform PEM -out ed448_private_key_pkcs8.pem
openssl pkey -outform PEM -pubout -in ed448_private_key_pkcs8.pem -out ed448_public_key_x509.pem

openssl genpkey -algorithm ed25519 -outform PEM -out ed25519_private_key_pkcs8.pem
openssl pkey -outform PEM -pubout -in ed25519_private_key_pkcs8.pem -out ed25519_public_key_x509.pem

Buildfiles:

Specifying search paths

These are a set of filesystem paths on the host system that are searched for the various types of objects defined in the buildfile. The search happens in the order defined by the command line option or attribute that defines the paths to search. If the buildfile specifies a host-side location for a filesystem object, mkqfs appends that location to the search path to form the full path to use to resolve the host filesystem object.

You specify the paths using mkqfs with -r, or the search global attribute.

For more information and examples, see search attribute.

Defining filesystem objects

Filesystem objects are defined on separate lines using the type attribute to indicate the type of object to add to the filesystem image. If the type attribute is missing, the default value of type=file is assumed when mkqfs parses the buildfile.

The object types that you can add to the buildfile depend on the type of filesystem.

Currently, QCFS supports the following object type attributes:

file

[type=file (type_attributes)] fs_path(=host_path|{contents})

Creates a file entry in the filesystem image with the defined properties and content, where:

• Items in () are optional.
• the type_attributes variable is additional attributes set on the file (e.g., user ID). See Specifying object properties.
• fs_path is the location, starting from the root of the filesystem image, in which to put the actual file object.
• host_path is the location to append to the search paths to form the paths that mkqfs searches for the host file to copy to the filesystem image. If host_path is absolute (i.e., starts with /), the search paths are ignored. If this value is not given, it’s assumed to be the same as fs_path.
  • If host_path points to a directory, the full tree of contents under the directory is added to the image under fs_path.
  • If host_path points to a symlink, then an identical symlink object is added to the filesystem image under fs_path.
• contents is the inline contents of the file as defined by the text found between the start and end of the curly braces. Any intermediate curly braces that are part of the contents need to be escaped using backslash (\) characters.

Examples

The following entry specifies the location in the filesystem image, starting from its root, for the file libxml2.so.2. The object type is file by default. To create the full path to search on the host for the file, mkqfs appends lib/libxml2.so.2 to the search paths:

lib/libxml2.so.2

The following entry specifies the location of the file in the filesystem image. To create the full path to search on the host for the file, mkqfs appends usr/lib/libqtrace.so to the search paths:

lib/libqtrace.so=usr/lib/libqtrace.so

The following entry specifies the file permissions with a four-digit octal number (see Specifying permissions):

[type=file perms=0755] lib/libqtrace.so=usr/lib/libqtrace.so

The following entry adds the directory lib to the filesystem image with all the content found on the host in the search paths under usr/lib:

lib=usr/lib

For more information on setting IDs and other properties, see Specifying object properties.

dir

[type=dir (type_attributes)] fs_path

Creates a directory in the filesystem image with the defined properties and content, where:

• Items in () are optional.
• the type_attributes variable is properties set on the directory (e.g., user ID). See Specifying object properties.
• fs_path is the location for the directory, starting from the root of the filesystem image.

Intermediate directories that are not defined explicitly in the buildfile inherit the currently defined directory permissions and user and group IDs of the buildfile when a filesystem element is parsed. These values can be the default that mkqfs provides or defined by the global version of these property attributes (for information on global attributes, see Specifying object properties).

Example

The following entry creates the directory /lib at the root of the filesystem image with the specified user ID, group ID, and file permissions:

[type=dir uid=0 gid=0 dperms=755] /lib 

link

[type=link] fs_path=link_path

Creates a soft link (symlink) entry in the filesystem image where:

• fs_path is the location, starting at the root of the filesystem image, for the soft link object.
• link_path is the absolute or relative path that the soft link points to.

Example

The following entry creates the symlink xbin/more that points to the filesystem object less:

[type=link] xbin/more=less 

hlink

[type=hlink] fs_path=target_path

Creates a hard link entry in the filesystem image. A hard link is another name for a file that points to the same contents as another one.

Where:

• fs_path is the location, starting at the root of the filesystem image, for the hard link object.
• target_path is the relative path from the directory that holds the hard link (the parent directory of fs_path) to the filesystem file object that is shared by the hard link.

Example

The following entry creates a hard link at xbin/ascii that shares the file toybox found under the parent directory of xbin/ascii:

[type=hlink] xbin/ascii=toybox 

Specifying filesystem object properties

Buildfiles can include attributes that define the properties of filesystem objects. They can apply to all types of filesystem objects (global attribute), to specific object types only (type attribute), or to a specific instance of an object only.

A global attribute can be set at any point in a buildfile and does not take an object type attribute as part of its declaration. A global attribute affects the properties of any filesystem objects that are declared after it in the buildfile unless you override it by declaring a type attribute for an object.

There are two types of attributes:

boolean attributes

Require a prefix of a plus (+) or minus (-) sign to be recognized.

value attributes

End with an equal sign (=) followed by a value. The value should use double quotes if it contains spaces.

You can combine multiple attributes within a single set of square brackets.

Some object property attributes can only be specified globally to all object types, some can either apply globally or made to apply to a specific object type only, and some require you to specify the object type they apply to. (When a type is required but not specified, the default type file is used.)

The QCFS supports the following object property attributes:

blksize attribute

blksize=size

Set the block size that the filesystem driver reports to the system. This attribute does not set the block size for the filesystem, and has no functional effect on the filesystem. You can specify any power of 2 from 512 to 32768 bytes. The default value is 4096 bytes. You can also specify this value as a number with one of the following suffixes: K, k, M, m, G, g, T, t.

Example

[blksize=32768] 

optional attribute

+|-optional

If this attribute is enabled (+) and the host file can't be found, output a warning, and then continue building the embedded filesystem. If it's disabled (-) and the host file can't be found, output an error message and exit. The default setting is enabled.

Example

[-optional] 

dupignore attribute

+|-dupignore

If this attribute is enabled (+), any file that is added to the filesystem and is a complete duplicate of another object (i.e., fs_path and host_path are identical) is ignored by mkqfs when it constructs the filesystem image. If the setting is disabled (-), any duplicate file generates an error. The default setting is disabled.

Duplicate files that point to different host_path objects or have different content are always reported as an error.

Example

+dupignore 

followlink attribute

+|-followlink

Specify whether to resolve any symbolic links and include the target files or directories instead of the links.

If you specify +followlink (enable the attribute), whenever an item taken from the host filesystem is a symbolic link, mkqfs follows the link and includes its target. If you omit the attribute, this is the default behavior.

If you specify -followlink (disable it):

• If a symbolic link is named explicitly in the buildfile and is a link to a directory, mkqfs follows the link and recurses into the directory. For directory links included indirectly as part of an explicitly named parent directory, they will not be followed but included as symbolic links.
• If the symbolic link is a link to a file, mkqfs includes the link itself in the image filesystem. It's up to you to include in the image whatever the link points to.

Example

+followlink 

uid attribute

uid=uid [file|dir]

Set the user ID value for the filesystem object. The value of this attribute is a number from 0 to INT32_MAX. The default value is 0.

Example

The following entry is a global attribute that sets the user ID value to 0 for all filesystem object types:

[uid=0]

The following entry sets the user ID for the specified file. It overrides any global ID property attribute declared earlier in the file:

[type=file uid=0] lib/libqtrace.so=usr/lib/libqtrace.so

gid attribute

gid=gid [file|dir]

Set the group ID value for the filesystem object. The value of this attribute is a number from 0 to INT32_MAX. The default value is 0.

Example

The following entry is a global attribute that sets the group ID value to 0 for all filesystem object types:

[gid=0]

The following entry sets the group ID for the specified file. It overrides any global gid attribute earlier in the file:

[type=file gid=0] lib/libqtrace.so=usr/lib/libqtrace.so

perms attribute

perms=perms [file]

Set the permissions for the filesystem object. For more information, see Specifying permissions.

dperms attribute

dperms=perms [dir]

Set the permissions for the filesystem object. For more information, see Specifying permissions.

mtime attribute

mtime=mtime_fmt [file|dir|link]

Set the modify time (mtime), creation time (ctime), and access time (atime) values for the filesystem object. The mtime_fmt value entry needs to follow the format string “%F-%T” that is supported by the strptime() function.

Example

The following entry is a global attribute that sets the mtime value for all filesystem object types:

[mtime="1970-01-01-00:01:05"]

The following entry sets the mtime value for the specified file only:

[mtime="2011-11-11-11:11:11"] file2 = {} 

search attribute

search=path[:path...]

Sets the host-side paths in which to search for the filesystem objects to populate the filesystem image. This attribute overrides any paths set using mkqfs with the -r option.

Example

The following entry sets the search paths for all types of filesystem objects. If the entry for a filesystem object does not specify a host_path to append to the search path, mkqfs searches for fs_path in these search paths in the given order:

[search=/sdp/7.1/target/qnx7/x86_64:/sdp/7.1/target/qnx7/x86_64/boot/sys:/sdp/7.1/target/qnx7:.]

For example, if fs_path is lib/libqtrace.so, mkqfs searches the following paths:

1. /sdp/7.1/target/qnx7/x86_64/lib/libqtrace.so
2. /sdp/7.1/target/qnx7/x86_64/boot/sys/lib/libqtrace.so
3. /sdp/7.1/target/qnx7/lib/libqtrace.so

If host_path is specified, mkqfs appends that path to the search paths. For example, if host_path is usr/lib/libqtrace.so, mkqfs searches the following paths:

1. /sdp/7.1/target/qnx7/x86_64/usr/lib/libqtrace.so
2. /sdp/7.1/target/qnx7/x86_64/boot/sys/usr/lib/libqtrace.so
3. /sdp/7.1/target/qnx7/usr/lib/libqtrace.so

If host_path is an absolute path (i.e., starts with /), the search paths are ignored. For example, if host_path is /lib, mkqfs searches that directory in the host root directory only, even if you specified search paths.

acl attribute

acl=acl_spec[,acl_spec...]

Sets the access control list for the filesystem object. The acl_spec value uses the following format:

tag:id:perm_set

Where:

• tag is one of u (user), g (group), or o (other).
• id is either empty or, if tag is u or g, a decimal numeric user ID or group ID.
• perm_set is the set of permissions granted. Valid characters are r (read), w (write), x (execute), and - (a fill character that doesn't affect permissions). The r, w, and x characters can appear in any order, but at most once each.

This is fairly similar to the short text form of ACLs in other implementations of IEEE 1003.1e draft 17 ACLs, with a few exceptions:

• Only single-character tags are allowed.
• The qualifier, if given, must be numeric.
• No whitespace or other characters are allowed.
• The mask can't be explicitly specified.

This attribute interacts with any perms and dperms attribute that you specified for the file or directory. Any basic permission (e.g., u::*, g::*, o::*) that isn't specified in the ACL is taken from the perms or dperms specification and overwrites the corresponding bits in the object’s stat.st_mode field. For more information about ACLs, see Access Control Lists in the Working with Files chapter of the QNX OS User's Guide.

Example

When the following acl_spec value is specified, user ID 10 is given write access, and group ID 20 is given read and execute access:

acl="u:10:w,g:20:rx"

compblksize attribute

compblksize=size

Sets a maximum block size for file data. Any file data larger than this size is split into separate chunks before compression. Any data that is left over is packaged into a fragment block.

You can specify any power of 2 from 16384 to 1048576 bytes. You can also specify this value as a number with one of the following suffixes: K, k, M, m, G, g, T, t.

metablksize attribute

metablksize=size

Sets a maximum block size for metadata. Any filesystem metadata (e.g., object names, permissions, etc.) larger than this size is regrouped and compressed in separate chunks.

You can specify any power of 2 from 4096 to 32768 bytes. You can also specify this value as a number with one of the following suffixes: K, k, M, m, G, g, T, t.

compressor attribute

compressor=algorithm

Sets the compression algorithm used to compress files and metadata in the image. Specify one of the following values:

lz4hc

LZ4 high compression algorithm

zstd

Zstandard compression algorithm

complvl attribute

complvl=level

Sets the compression algorithm's compression level from least to most compressed. The higher the compression level, the longer it takes to build an image.

If compressor=lz4hc, valid values are 3 to 12.

If compressor=zstd, valid values are 1 to 22.

include attribute

+|-include
        

Include files as part of the buildfile being processed. You can apply this attribute to a single file (specify the path on a new line):

[+include]
 buildfile_path
[-include]
           

or as a global attribute:

[+include]
buildfile_path_1
buildfile_path_2
...
buildfile_path_n
[-include]
            

You can specify variables in the attribute's value. For information on how they're expanded (i.e., evaluated to a value used in their place), go to Environment variables.

Each buildfile_path can be an absolute or a relative path. If buildfile_path starts with a slash (/) on a Linux development host, or a disk volume label followed by a backslash (\) on a Windows host, it's absolute and mkqfs searches for the file in that exact host location. If the path starts with another character sequence, it's a relative path, and mkqfs searches the following directories (in this order):

• the current directory
• all paths specified by search attributes
• the boot/build directory under the current root (specified with the -r command-line option)
• the boot/build directory under ${QNX_TARGET}/${PROCESSOR}

Note that you can't use the target=host notation for the paths.

If an include file can't be found, mkqfs terminates with an error.

Buildfiles are processed top-down, and buildfile inclusion happens in place: when an include attribute is found, the included buildfile is loaded and processed; when processing is completed, mkqfs returns to the including buildfile.

You can nest buildfile inclusions, but any circular inclusion will cause errors. For example, the inclusion hierarchy A(B(D),C(E,F)) is valid, but A(A) and A(B(C(B))) aren't.

Note: The top buildfile together with its included buildfiles effectively form one large buildfile stream that's processed as a single buildfile would be. This means that all attribute settings in effect before an inclusion remain in effect inside the included files, and everything set in an included file is carried over into the parent buildfile.

The default is -include, which causes files (if found) to be added to the filesystem, not to the buildfile.

Specifying permissions

Examples

The following entry adds the empty file file1 to the filesystem image and sets its file permissions with a four-digit octal number:

[perms=0777] file1 = {}

The following entry uses with symbolic mode strings to sets user, group, and other permissions to read, write, and execute, and to sets the user ID when file2 is executed:

[perms=ugo=rwx,u+s] file2 = {}

Environment variables

The buildfile language can expand environment variables in the buildfile before it processes each line. This action can be useful for converting some parts of the buildfile to parameters that are based on configuration parameters.

For example, the following entry adds the content found in the search paths at the location specified by ${DIR1} to the filesystem image at recurse/dir:

[type=file] recurse/dir = ${DIR1} 

Examples:

Building a QTD image and mounting it on a target

The following command makes a Power-Safe filesystem image (QNX) that is less than 2MB in size. This is the filesystem image that the QTD image will protect:

mkxfs -t qnx6fsimg qnx6.build qnx6.img

The following command builds a QTD image. The -P option specifies an image of 2 MB exactly:

mkqfs qtd -s -vv -B 4096 -H sha256 -S ecdsa-sha256 -K ec_test_private_key.pem -P 2097152 -o
        qtd.img qnx6.img

The following command mounts the QTD image with a full disk verification:

mount -t qtd -o key=/proc/boot/ec_test_public_key.pem,stats,verbose,verify /dev/hd1 /dev/qtd-1

You can use the following command to mount the Power-Safe filesystem image:

mount -t qnx6 /dev/qtd-1 /fs

Building and extracting a QCFS

The following command builds a qcfs image using the buildfile input.build:

mkqfs qcfs -o qcfs.img input.build

The following command extracts the contents of a qcfs image:

mkqfs qcfs -x -o extract qcfs.img

Exit status:

0

Successful completion.

>0

An error occurred.

129

License not found.

130

Product is not covered under your license.

131

License expired.

132

License not activated.

133

Can't connect to the license server.