Each container has a corresponding configuration file defining its key features. Every container runs a certain operating system, which also has to be defined in a configuration file. Note that several containers may run the same operating system.
Both container and OS configuration file formats are composed of several
key: value lines.
A detailed description of the container configuration can be found here; the guestOS configuration is described here.
trust|me is operated using a socket-based interface. This interface is used by the control command-line tool, which is installed together with trust|me. It is available from the privileged container (core0) and the debugging shell of CML. This tool is just for basic usage and demonstration of the control interface. For productive use cases an implementation of the protobuf-based control interface should be used, for instance in a web-based UI.
The control tool allows administration and configuration of the trust|me platform, such as creating and starting containers, running a given command inside a container, etc. The available actions are listed below.
Usually, container specific commands use the container-uuid as parameter to identify the corresponding container. However, for convenience also the container name could be used. However, if you have several containers with the same name, always the first matching one is used. In that case, you have to specify the UUID to address all containers.
control start <container-uuid> [ --setup ]
This command starts the container with the given UUID. In order to do so, the container has to be created beforehand by ‘control create’.
--setup parameter allows you to manipulate
the containers root file system tree including all encrypted overlays mounted at
This could be used to bootstrap an encrypted container, see example: Using GuestOs debos.
When entering this command, you will be interactively asked for the Passphrase/PIN of the softtoken
used for container en/decryption. If the container configuration specifies that an external USB pin
reader device should be used (see Container Configuration), the
PIN/passphrase must be entered via this device instead of the standard input keyboard.
control stop <container-uuid>
This command stops the currently running container with the given UUID. When entering this command, you will be interactively asked for the Passphrase/PIN of the softtoken used for container en/decryption. If the container configuration specifies that an external USB pin reader device should be used (see Container Configuration), the PIN/passphrase must be entered via this device instead of the standard input keyboard.
control create <config-template-file> [<container.sig> <container.cert>]
This generates a new container configuration with a random UUID from a configuration file and optionally a signature and a certificate file. The configuration template file has to be given using protobuf-text syntax. It must contain at least the following:
name: "<container name>" guest_os: "<guest os name>" color: <color for UI as argb e.g. 0xff00ffff>
You can use
control list_guestos to get the name for available GuestOSes.
control remove <container-uuid>
Deletes the given container completely including configuration, data images and corresponding wrapped keys.
control wipe <container-uuid>
Wipes the specified container.
Wipes all containers on the device.
control state <container-uuid>
This returns the current state of the given container. Possible states are:
STOPPED: The container has either not been run, was explicitly stopped or the init process of the container exited
STARTING: The container was started using ‘control start’ and the container manager is preparing to launch the container.
BOOTING: The container manager finished preparing the container and the control was handed over to the container’s init process
RUNNING: The container was initialized successfully and is now running.
FREEZING: The container is in the process of freering after a ‘control freeze’ was issued
FROZEN: The container is frozen after a ‘control freeze’ was issued
ZOMBIE: The container is a zombie
SHUTTING_DOWN: The container is in the process of shutting down
SETUP: The container was initialized successfully and is now running in setup mode (target rootfs mounted at /setup)
REBOOTING: The container is rebooting
control config <container-uuid>
Prints the container config to stdout. This could be used for editing the current config.
control update_config <container-uuid> <container.conf> [<container.sig> <container.cert>]
Sends a new config file
container.conf and optionally a signature and certificate file to the
cmld. It is not applied to running containers directly. You have to stop the container and
trigger a reload.
This command reloads all container configs of all containers in state
into the running
control run <container-uuid> <command> [<arg_1> ... <arg_n>]
Experimental, some characters especially control characters may not work as expected. The given command is executed in the context of the given container. Before executing the command, the process is made session leader and get’s a new PTY attached.
control assign_iface --iface <interface-name> <container-uuid> [--persistent]
The ‘persistent’ option also applies the change to the container’s config file, such that the assignment persists container reboot
control unassign_iface --iface <interface-name> <container-uuid> [--persistent]
The ‘persistent’ option also applies the change to the container’s config file, such that the assignment persists container reboot.
control ifaces <container-uuid>
control freeze <container-uuid>
Freezes the specified container, i.e. stops the processes of the container from being scheduled.
Experimental: Processes might behave unexpectedly if the container is frozen for a longer time period
control unfreeze <container-uuid>
Unfreezes the specified container that was previously frozen with
control allow_audio <container-uuid>
Grant audio access to the specified container
control deny_audio <container-uuid>
Denies audio access to the specified container
Lists the configuration of all installed GuestOSes.
control ca_register <ca.cert>
This command registers a new certificate in trusted CA store for allowed GuestOS signatures.
control push_guestos_config <guestos.conf> <guestos.sig> <guestos.pem>
This command can be used to push the specified GuestOS config, signature, and certificate files
of a corresponding GuestOS. This would trigger a download of the corresponding GuestOS image
files from either the download URL provided in the
guestos.conf or the default
download url in the CML’s
device.conf. If an older version is already installed an
update would be triggered after a reboot of the whole system.
control remove_guestos <guestos name>
Deletes the GuestOS by the given
guestos name. All associated files such as
configuration, signature and shared images files are removed permanently.
If the GuestOS is still in use by any container, this command will do nothing.
In this case you have to delete all remaining containers using the GuestOS
control remove, see above.
control pull_csr <device.csr>
During provisioning mode it is posible to
sign a device private key with a customer CA. This command pulls
the corresponding csr from the virtualization layer and
stores the csr in the provided file name
control push_cert <device.cert>
This command pushes back a device certificate provided in file
Remember, you have to provide your own mechanism to transfer and sign
the certification request to your CA. Further, you have to store the
corresponding Customer CA root certificate in the trusted CA store, see
This command provides an interactive prompt for old and new
Pin/Passphrase for the softtoken. Remember, the softtoken is used for
wrapping the container encryption keys and must be provided to container
start. (default passphrase after self-provisioning is
Reboots the device, shutting down any containers which are running
Set the device to the provisioned mode after initial configuration. This setting is persistant.
As soon as this command is run, the device is provisioned and only allows a subset of commands to be
run. All other
control commands will return CMD_UNSUPPORTED error code.
The set of allowed commands in provisioned mode is:
control list control change_pin control create control start control stop control update_config