mkqnximage

Syntax:

mkqnximage --type=vmware|vbox|qemu [--build] [--clean] 
           [--config=file[:file]...] [--defaults [=option]]
           [--extra-dirs=none|directory_list] [--getip]
           [--graphics [= yes | no ]] [--help [=option|brief]]
           [--hostname=hostname][--options]
           [--policy=none|path] [--repos=dir[:dir]...]
           [--run [= options | -h ]] [--stop]
           [--telnet [= yes | no ]] [--wipe]

Runs on:

Linux, Mac, Microsoft Windows

Options:

For additional options not described here, use --help and --options.

--build

Force a rebuild of the system image.

--clean

Force a clean build of the system image.

Because mkqnximage sometimes uses files from previous builds instead of regenerating them (for efficiency), rebuilding with --clean can be a helpful troubleshooting step.

--config=file[:file]...

If you have a set of options that you use frequently, you can save them in a file. If you have multiple configuration files, use a colon (:) to separate the filenames. For example, to specify the files set1 and set2:

  mkqnximage --config=set1:set2

--defaults[=option]

Revert the specified option to its default value, or omit option to revert all options to their default values.

--extra-dirs=none | directory_list

Specify additional directories to search for mkqnximage options and other files. Specify none to use only the standard mkqnximage and local directories.

--getip

Get the IP address of the QNX Neutrino system image in this directory.

This option waits for the system image to be up and running before it returns a value.

--graphics=[ yes | no ]

Include libraries and binaries related to graphics and start screen on boot.

--help [= option | brief ]

--help — Display detailed descriptions of all options.
--help=brief — Display a brief description of all options.
--help=option — Display detailed information about the specified option.

--hostname=hostname

Specify the name of the virtual machine. Because VMware and VirtualBox list virtual machines by hostname, this option can make it easier to identify a machine in those environments.

You can use this option to specify a different name. For example:

mkqnximage --type=vmware --run --hostname=qnx

--options

Display the options that are currently used when you run mkqnximage.

--repos=dir[:dir]...

Specify the search path used by mkifs and mkqnx6fsimg to locate files specified in the build files. Use a colon (:) or semi-colon (;) to separate the directories that mkifs and mkqnx6fsimg search.

For example, use the following command to search both $QNX_TARGET and ~/qnx/stage for files to include:

mkqnximage --repos='$QNX_TARGET:~/qnx/stage'

The following command also searches both $QNX_TARGET and ~/qnx/stage, but prefers files in ~/qnx/stage:

mkqnximage --repos='~/qnx/stage:$QNX_TARGET'

--run [=options | -h]

--run — Run the system image in the current directory.
--run=-h — Run the system image in the current directory in headless mode. The system image runs in the background without displaying anything on the screen.

--ssh-ident=path

Set the path to an ssh identity file, which allows you to log in as root to a virtual machine using ssh without specifying a password.

--stop

Stop any running system image.

--telnet [= yes | no]

Support telnet connections to the image. This option is provided as an option because ssh is not pre-installed on all versions of Windows. The default is yes if ssh is not available, and no otherwise.

--type = vmware | vbox | qemu

A directory can only contain one system image, but you can rebuild it for a different virtualization environment at any time, by rerunning with a different --type option. Whatever options you specified for the original environment are preserved.

--wipe

Stop the image if it is running, unregister it from any virtualization environments where it is registered (if possible), and delete the local and output directories.

Description:

The mkqnximage utility is a QNX Neutrino virtual machine image generator. It can generate images to run in the following virtualization environments:

VMware — A hosted hypervisor.
VirtualBox — A free and open-source hosted hypervisor for x86 virtualization.
QEMU (Quick EMUlator) — A free and open-source emulator.

You can configure various options for the generated images, including the target CPU architecture. Currently, only the following combinations of host OS, VM platform, and target CPU architecture are supported:

Virtualization Technology	Host OS	QNX Guest CPU Architecture
VMware	Windows	x86-64
VirtualBox	Windows	x86-64
VirtualBox	macOS	x86-64
QEMU	Ubuntu	x86-64

Note: Currently, graphics is only available for VMware images.

There is no limit to the number of QNX Neutrino images you can create, but each one has to be in a different directory.

For information on creating an image on real hardware, see the BSP documentation for your board.

Preparing the virtualization environment:

VirtualBox network interface requirements

If this is the first time using VirtualBox, make sure it has a network interface before you run mkqnximage. To create a network, select the Network settings from Tools from the left pane and then click on the Create icon. Also, you have to enable DHCP.

Setting environment variables for Microsoft Windows

To use mkqnximage on Microsoft Windows from a cmd window, first locate and run the file qnxsdp-env.bat from the base directory of a QNX Software Center installation.

Building, running, and managing QNX system images:

Getting information about options

The mkqnximage utility supports more options than the ones listed above. To display the complete set of options with a brief description of each, run the following command:

mkqnximage --help=brief

For detailed information about a specific option, specify an option name instead of brief. Specify --help by itself to display all options with full descriptions.

Image directory

Whenever you run mkqnximage, it operates on the image in the current directory, whether you are building or running an image or getting its IP address.

In most cases, when you create a new system image, you start with an empty directory.

When mkqnximage first builds an image, it creates the following directories:

local: Contains information about how the target was built and any local customizations.
output: Contains the actual system image and buildfiles used to generate it. If you delete this directory, you can regenerate the image by running mkqnximage.

The output/build directory contains the build files and startup scripts that mkqnximage generates. You can edit these files and scripts as a quick way to try things out and diagnose problems. However, be aware that the contents of the output/build directory is regenerated when you run mkqnximage with updated options.

Running and stopping system images

Use --run to start the image in the current directory and --stop to stop it.

If you are using VMware Workstation Player, you cannot use mkqnximage to start and stop images. Instead, open the file local/vmware_files/vmware.vmx.

You can combine other options with --run. If the options are different than the ones you used to build the image, mkqnximage rebuilds the image before it runs it; otherwise, it just runs it. If needed, you can use --build to force a rebuild of the system image when you run it. For example, you can force a rebuild to pick up changed versions of files.

Connecting to an image

The --getip option outputs the IP address of the system image if it is currently running. You can then use ssh to log in. You can also use telnet if you specify --telnet.

You can use scp and sftp to transfer files to and from the virtual machine.

Images built by mkqnximage include the users root, qnxuser, and user1 to user6. The password for each user is the same as the username.

Changing build options

When you run mkqnximage, the options you specify are preserved in local/options. To make changes, run mkqnximage and specify just the options you want to change. Use --options to display the current set of preserved options.

Use the following command to revert a single option to its default value:

mkqnximage --defaults=option

To revert all options to their default values, specify --default on its own.

Image filesystems

The filesystems on images built by mkqnximage are organized to achieve the best results for an embedded system rather than the traditional UNIX layout. No filesystem (other than possibly the IFS) is mounted at /. Instead, an image has the following filesystems:

A system partition that in some cases is made read-only. It is mounted at /system and contains binaries and read-only configuration files.
A data partition mounted at /data that is always read-write.

Deleting an image

When you no longer need the system image, use --wipe to unregister it from any virtualization environments where it is registered (if the environment allows it), and delete the local and output directories.

The mkqnximage utility cannot remove a virtual machine from VMware. The --wipe option frees all disk space used by the image, but the virtual machine in VMware’s Virtual Machine Library has to be deleted manually.

Both VMware and VirtualBox allow you to delete virtual machines including all associated files. While this action prevents the image from being run, because all the options are preserved, you can restore it by simply re-running mkqnximage.

Customizing an image

You can add content to files generated by mkqnximage as well as add new files to the image, which allows you to, for example, start new services on boot.

To make these changes, you edit 'snippet' files in the local/snippets directory. The most commonly used files are created for you, and you can create more as needed.

Each snippet file name has a prefix that determines what it does and a suffix that makes its name unique. Although the suffix is usually .custom, you can use a different value. For example, to add files to the system partition, you edit the file local/snippets/system_files.custom, and to add files to the IFS, you edit local/snippets/ ifs_files.custom.

The format of a snippet file depends on the file. For a snippet file that adds files to the system, the format must be in mkifs buildfile format for the IFS or mkqnx6fsimg buildfile format for the other two filesystems. The mkqmximage utility recognizes the following snippet file prefixes:

File prefix	Description
ifs_files	Includes additional files in the IFS. Uses the mkifs buildfile format.
system_files	Includes additional files in the system partition. Uses the mkqnx6fsimg buildfile format.
data_files	Includes additional files in the data partition. Uses the mkqnx6fsimg buildfile format.
ifs_env	Used mainly for creating procmgr symlinks and setting environment variables at the beginning of the IFS startup script. These files must use the format defined for script files by mkifs.
ifs_start	Commands used for starting the system. These commands include security policy loading if appropriate and execution of the startup script or SLM depending on the method used for starting the system. These files must use the format defined for script files by mkifs.
post_start	Included in post_startup.sh, a shell script run at the end of startup.sh and by the SLM configuration file. It should contain commands that ksh can handle.
slm	Included in the SLM configuration file.
profile	Included in target system's /system/etc/profile, which is the file run when a user logs in to set up their environment. It should contain commands that ksh can handle.
passwd_file, shadow_file,group_file	Include content in the passwd, shadow and group files. The format of these files must match that used by /etc/passwd, /etc/shadow, and /etc/group.
definitions	Insert into the start of all preprocessed files to define preprocessor symbols.
options	Define special options. This file is formatted as one or more bash variable assignments. Setting the variable PROC_OPTIONS appends the value of this variable to the procnto command line options.

To include your own files in an image, either provide full paths to the files or use --repos to specify the paths to search.

Configuration files

If you have sets of options that you use frequently, you can save their values in a file and apply them using --config. The files are treated as bash scripts that are sourced by mkqnximage and are expected to set one or more variables to indicate new values for options. For example, a file contains the following line:

OPT_SECURE_PROCFS='yes'

When you load the file using --config, the effect is the equivalent to specifying --secure-procfs=yes.

The current settings of all options in this format are in the file local/options. If you set the environment variable MKQNXIMAGE_CONFIG to a path to this type of file, mkqnximage uses the file to provide the initial configuration whenever it creates a new system image.

Because the configuration file is a bash script, it can do more than set variables. For example, it can set the --hostname option based on the name of the current directory.

Image security

The mkqnximage utility is intended to provide, among other things, a method for demonstrating QNX Neutrino security features. However, it is deliberately not secure because making it secure would make it less suitable for its primary role as an easy-to-use platform for experimentation. Although it provides a good way to learn about security features, for security reasons, it should not be emulated too closely in a real system. The following characteristics are some of ways that it is insecure:

It provides console access running a root shell.
It uses password and ssh public key authentication.
It uses deliberately obvious passwords.
sshd permits root logins.
When QNX Trusted Disk is used, the private key is kept unprotected in a local host directory.
It does not use any form of secure boot.
It runs the qconn service.

Troubleshooting:

If the --getip option fails to return an address, it most likely means that the virtual machine is not running or failed to boot. If have this issue when the machine is running, you should check the console for indications of an error.

If a system fails to boot, check first that you've chosen a virtualization environment that is available on your system. The mkqnximage utility reports the target type after it builds the image.

In some cases, the source of problems might be that some files are not generated as they should be after one or more local changes or QNX packages are updated. To ensure this is not the case, rebuild with --clean or delete the output directory.

If you are running a QEMU image in headless mode, the console output is redirected to output/qemu.out. For VMware and VirtualBox, you can find the output from the commands used to start the virtual machine in .log files in the output directory.

If you get a build failure, a likely reason is changes you've made to one or more customization files. Any line numbers reported by mkifs or mkqnx6fsimg refer to files in the output/build.