mkqfs

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.

Because QNX Trusted Disk (qtd) is not a filesystem, it is not constructed using a buildfile.

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

• blksize
• compblksize
• complvl
• compressor
• dupignore
• followlink
• include
• 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 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"

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] 

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.

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.

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

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

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

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.

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 16384 bytes. 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=/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.

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} 

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

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.