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

TypeExampleDescription

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 measue

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.

ParameterValuesDescription

enableManagerSudo

true,*false*

## 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).

ParameterValuesDescription

enabled

*true*,false

Turn on/off

command

String

Shell command to execute in term.

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.

ParameterValuesDescription

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.

ParameterValuesDescription

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

ParameterDescription

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

EventDescription

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

tunlsLogLevel = 4

# Options for the self-signed TLS certificate generated by the tunneling # service.

# 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 everytime 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"}