Skip to main content


The image configuration file can be found in /etc/ticrypt/controller.toml in Linux machines, and C:\'Program Files'\'Tera Insights'\'tiCrypt VM Controller'\controller.toml in Windows. It contains the necessary information for the VM controller to know how to run each specific VM. These per-image configuration parameters are usually set by the individual building the image.

Image Configuration Structure

The types of values used in the description of parameters are:

String"an example"String value
Int42Whole number value
Port22Number between 0 and 65535
Range"5000-5010"Range of ports
Duration1m, 2h, 3dDuration with unit of measure
ArrPort[5000, 5002, 5005]List/Array of port values
ArrString["a", "b", "c"]List/Array of string values

For each section of the configuration file, we will provide a sub-section to explain the options in the form of a table. For each parameter, we specify the name, as required by the config, the list or type of values with the default value highlighted. When a type and a default value exists, both are specified, e.g. Port=22 specifies that the value is a Port and defaults to 22.

Debug Section [debug]

This section controls the debugging behavior.

enableManagerSudotrue,falseAllow managers to become root/Admin

Terminal section [terminal]

This section controls the behavior of the terminal available in tiCrypt frontend. The terminal allows a more direct interaction with the operating system and it requires less setup (for example, no login).

enabledtrue,falseTurn on/off
commandStringShell command to execute in term.
scrollbackInt=10000History length in lines
maxScrollbackIntMaximum amount of scrollback

Tunnel section [tunnel]

The tunnel section controls application traffic forwarding. Since all ways in and out of the VM are blocked otherwise, this is the only way to access your applications outside the terminal.

enabledtrue,falseTurn on/off
serverPortPort=22Port for the tunneling service
allowedPortsPort, Range, ArrPortThe list of ports that can be forwarded. You need to add ports here for all applications not covered elsewhere.
addGroupsArrStringList of groups to add users with tunneling permissions
tunlsLogLevel0,1,2,3,4None=0, Errors=1, Warning=2, Info=3, Debug=4
idleTimeoutDurationMaximum time of inactivity allowed in ???
sftpEnabledtrue, falseAllow SFTP feature?
sftpPortPort=2022The port used by SFTP. Change only if conflict.
sshDirPathStringPath to the SSH executables
*[]*Sub-section for services
vncPortName the provided port as vnc.
xpraPortName the port as xpra
my_appPortName the port as my_app
*[tunnel.cert]*Control tunnel certificate
countryStringThe country to set on certificate
organizationStringThe organization to set on certificate

The [] section only names the ports. To allow the ports, add them to the allowedPorts.

Statistics section [stats]

This section controls aspects of statistics reporting.

systemIntervalDurationHow often system is polled
logErrorstrue, falseLog the stats collection errors?

Commands section [commands]

This section allows sophisticated setups that require various scripts to be executed in order to provide the desired functionality. A complete example on how these commands are used is in section ???

There are two types of commands: root/Admin and user. Root commands are executes as root and user commands as the respective user.

[commands.rootCommands]Sub-section for root commands
[commands.rootCommands.runEveryTimeCommands]Executed on every event
[commands.rootCommands.runOnlyOnceCommands]Executed on first event
[commands.userCommands]Sub-section for user commands
[commands.userCommands.runEveryTimeCommands]Executed on every event
[commands.userCommands.runOnlyOnceCommands]Executed on first event

In each of the leaf sub-sections above, e.g. [commands.rootCommands.runEveryTimeCommands] a mapping from event type to list of commands can be specified. The list looks like:

example_event = {
action1 = "command1",
action2 = "command2 with args"

The commands can include parameters. For example cd /home

The user commands can use @:user: for the user name. For example, chown @:user: some/folder command will allow replacement for the user name based on the actual user. If user is alin the command executed is chown alin some/folder

The macro @:user: can be used multiple time in a command

The list of currently supported events is:

on_loginCommand to be executed on user login
on_homeDriveAttachedCommand to be executed when the home drive gets attached

VM Image Configuration Example


  • Whether or not the terminal service is enabled. enabled = true

  • The default command to use when running terminals. Default is platform-specific. command = "/bin/bash" command = "powershell.exe"

  • Default number of lines of scrollback history kept. #scrollback = 10000

  • Whether or not the tunnel service is enabled. enabled = true

  • TCP port on which to bind the tunneling service. serverPort = 22

  • List of allowed ports for tunneling. May be a single port, a range of ports, or an array of ports. allowedPorts = \[\] default allowedPorts = 5901 allowedPorts = "5901-5905" allowedPorts = 14500

  • List of additional system groups that users with tunneling permissions will be added to. addGroups = \[\] default addGroups = \[ "Remote Desktop Users" \] Windows: allow access to RDP

  • Timeout for idle tunnels. If set to positive duration, tunnels without active forwarded connections will be killed after the specified timeout. The minimum non-zero idle timeout is 1 second. Default: 15 minutes idleTimeout = "15m"

  • Whether SFTP support is enabled. If enabled, an SSH daemon will be run that is configured to only allow SFTP connections. sftpEnabled = true

  • The local port on which the SFTP SSH daemon runs. This will be automatically added to the allowed tunnel ports. sftpPort = 2022

  • The path to the directory containing the sshd(.exe) and ssh-keygen(.exe) executables. If not set, the following will be checked for the executable:

  1. The assets archive at bin/ssh/
  2. The system path sshDirPath = ""
  • Optional names for ports, which may be referred to in the connection instructions for the VM.vnc = 5901 xpra = 14500

  • Options for the self-signed TLS certificate generated by the tunneling service.tunlsLogLevel = 4

  • If specified, country MUST be a two-letter country code. country = "US" organization = "unspecified"

Commands section

  • Commands to be run with root privileges

  • The following commands will be run only the first time the associated event occurs in one VM lifecycle. example\_event={actionToRunOnce0 = "command0",actionToRunOnce1 = "command1"}

  • The following commands will be run every time the associated event occurs. example\_event={actionToRunEverytime0 = "command0",actionToRunEverytime1 = "command1"}

  • Commands to be run as the user. Events that are not user-related like on_home_drive_attached cannot be run as a user.

  • The following commands will be run only the first time the associated event occurs in one VM lifecycle. example\_event={actionToRunOnce0 = "command0",actionToRunOnce1 = "command1"}

  • The following commands will be run everytime the associated event occurs. example\_event={actionToRunEverytime0 = "command0",actionToRunEverytime1 = "command1"} \'\'\'