mkqfs (for QFS)

Runs on:

Linux, Microsoft Windows

Options:

The following options are supported for QFS filesystems and other QNX filesystems:

-a

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

-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 you specify qtsafefs, the help menu for the QFS version is printed; otherwise, it's a general help menu.

-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 dump the contents to output.

Not all filesystems support extraction.

-y

Verify a filesystem image.

Not all filesystems support verification.

fstype_options

A set of options (some mandatory) 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

Description:

The mkqfs utility generates QNX-supported filesystems. Each supported filesystem can be built and, optionally, verified and extracted. The version of the utility provided with QFS is qualified for safety-related applications. It supports the generic options described in Options as well as QFS-specific ones (which always use capital letters).

This document describes specific options for QNX Filesystem for Safety (qtsafefs). For options specific to other supported filesystems, go to the mkqfs entry in the QNX SDP 8 Utilities Reference.

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.

qtsafefs 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 (specified by -H) and a maximum of 128 bytes.

If omitted, mkqfs randomly generates the salt on the host platform and stores it in the filesystem image superblock. The same salt is prepended to all data before it is hashed. Because mkqfs generates a new salt each time it creates a filesystem image, a data block that exists in two different QTD images will have a different hash in each image (unless you set the hash using -A).

-B size

Specify, in bytes, the block size to use when splitting the source image into chunks to hash. Mandatory when building an image.

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.

To select an appropriate block size, experiment with block sizes in your pre-deployment system.

-H hash

A mandatory option that specifies the cryptographic digest. Supported digests: sha256 and sha512-256.

-K key

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

-P n[ k | m | g | t ]

(Optional) Build the filesystem image in partition mode, which forces the qtsafefs image to extend to the size in bytes specified by n exactly. You can specify a number or a number with a suffix that represents the appropriate power of 1024. Valid suffix values are k (kilobytes), m (megabytes), g (gigabytes), and t (terabytes). Note that suffixes are case insensitive and must come directly after the number, with no whitespace in between.

This option is required when you are building a qtsafefs 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 filesystem mounted path. For more information, see qtdctl entry of the Utilities Reference.

-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 (secp256r1 recommended)	EC Digital Signature Algorithm
eddsa-25519	Ed25519	Edwards Digital Signature Algorithm (pure mode)
eddsa-448	Ed448

-Z sign_cmd

(Optional) The custom signing command for the cryptographic signature of the qtsafefs 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 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 digest in binary format that needs to be signed.

<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 (in this case rsa-sha256 signing):

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

Cryptographic keys:

Like QNX Trusted Disk (QTD), qtsafefs 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.

The maximum RSA key size that qtsafefs supports is 16 Kibit (kibibits).

For examples of generating the various keys, see Cryptographic keys supported by QTD in the mkqfs entry of the Utilities Reference.

Buildfiles:

Buildfiles consist of a set of attributes that describe the contents and properties of all the filesystem objects, such as files and directories, that are found in the filesystem image.

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, qtsafefs 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 curved brackets 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 libpps.so.1. The object type is file by default. To create the full path to search on the host for the file, mkqfs appends lib/libpps.so.1 to the search paths:

lib/libpps.so.1

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

The following entry adds the file /etc/syslog.conf to the filesystem image, sets its group and user IDs and file permissions, and specifies its content:

[gid=0 uid=0 perms=644] /etc/syslog.conf = {
# Note need a tab to separate fields
*.* /dev/console
}

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 qtsafefs filesystem supports the following global object property attributes, which affect the behavior of mkqfs, set filesystem parameters, or both:

• blksize
• datablksize
• dupignore
• followlink
• metablksize
• optional
• search

The following object property attributes affect filesystem objects either globally or on a per-object basis:

• dperms
• gid
• mtime
• perms
• uid

The acl attribute applies only on a per-object basis.

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

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] 

datablksize attribute

datablksize=size

Sets a block size for file data. Any file data larger than this size is split into separate chunks.

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.

dperms attribute

dperms=perms [dir]

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

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 are not 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 

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

metablksize attribute

metablksize=size

(Optional) Sets a block size for metadata.

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

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 = {} 

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] 

perms attribute

perms=perms [file]

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

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=/path/to/search/a:/path/to/search/b:/path/to/search/c:.]

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

1. /path/to/search/a/lib/libqtrace.so
2. /path/to/search/b/lib/libqtrace.so
3. /path/to/search/c/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. /path/to/search/a/usr/lib/libqtrace.so
2. /path/to/search/b/usr/lib/libqtrace.so
3. /path/to/search/c/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.

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

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:

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.