Configuration

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:

Type	Example	Description
String	"an example"	String value
Int	42	Whole number value
Port	22	Number between 0 and 65535
Range	"5000-5010"	Range of ports
Duration	1m, 2h, 3d	Duration 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 exist, 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.

Parameter	Values	Description
enableManagerSudo	true,false	Allow managers to become root/Admin

Terminal section [terminal]

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

Parameter	Values	Description
enabled	true,false	Turn on/off
command	String	Shell command to execute in terminal
scrollback	Int=10000	History length in lines
maxScrollback	Int	Maximum 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.

Parameter	Values	Description
enabled	true,false	Turn on/off
serverPort	Port=22	Port for the tunneling service
allowedPorts	Port, Range, ArrPort	The list of ports that can be forwarded. You need to add ports here for all applications not covered elsewhere.
addGroups	ArrString	List of groups to add users with tunneling permissions
tunlsLogLevel	0,1,2,3,4	None=0, Errors=1, Warning=2, Info=3, Debug=4
idleTimeout	Duration	Maximum time of inactivity allowed in ???
sftpEnabled	true, false	Allow SFTP feature?
sftpPort	Port=2022	The port used by SFTP. Change only if conflict.
sshDirPath	String	Path to the SSH executables
*[tunnel.services]*		Sub-section for services
vnc	Port	Name the provided port as vnc.
xpra	Port	Name the port as xpra
my_app	Port	Name the port as my_app
*[tunnel.cert]*		Control tunnel certificate
country	String	The country to set on certificate
organization	String	The organization to set on certificate

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

Statistics section [stats]

This section controls aspects of statistics reporting.

Parameter	Values	Description
systemInterval	Duration	How often system is polled
logErrors	true, false	Log the stats collection errors?

Commands section [commands]

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

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

Parameter	Description
[commands.rootCommands]	Sub-section for root commands
[commands.rootCommands.runEveryTimeCommands]	Executed on every event
[commands.rootCommands.runOnlyOnceCommands]	Executed on the first event
[commands.userCommands]	Sub-section for user commands
[commands.userCommands.runEveryTimeCommands]	Executed on every event
[commands.userCommands.runOnlyOnceCommands]	Executed on the 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 this:

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 the user is alin the command executed is chown alin some/folder
• The macro @:user: can be used multiple times in a command.

The list of currently supported events is:

Event	Description
on_login	Command to be executed on user login
on_homeDriveAttached	Command to be executed when the home drive gets attached

VM Image Configuration Example

toml

• 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. Maybe 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, a 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 every time the associated event occurs. example\_event={actionToRunEverytime0 = "command0",actionToRunEverytime1 = "command1"} \'\'\'