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 john the command executed is chown john 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:

The assets archive at bin/ssh/
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"} \'\'\'

Example Conf File

Image 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

Global Settings

This options are specified at the top level of the configuration file.

ControllerSubvariant

This option allows us to select a different controller to be downloaded, instead of the default.

By default, the VMC Stub optains the controller from http://vmc.ticrypt/<arch>/<os>/<variant> (or http://vmc-test.ticrypt/<arch>/<os>/<variant> for test versions). If a non-empty controller subvariant is passed, the VMC Stub will attempt to get the controller from http://vmc.ticrypt/<arch>/<os>/<variant>/<subvariant> (or http://vmc-test.ticrypt/<arch>/<os>/<variant>/<subvariant> for test versions).

If we fail trying to obtain a specified controller subvariant, we fall back to the default.

ConfigPrefix

This option allows us to select a different image configuration, instead of the default.

By default, the VMC Stub loads the image configuration from /etc/ticrypt/controller.toml on Linux and C:\'Program Files'\'Tera Insights'\'tiCrypt VM Controller'\controller.toml on Windows. If a ConfigPrefix is passed in the preregistration parameters, the VMC Stub will try to load and use instead the configuration named: <config-path>/<configprefix>-controller.toml.

If we fail trying to use the specified configuration, we fall back to the default.

Debug Configuration

This section contains configuration parameters intended only for debugging. Parameters:

EnableManagerSudo

Terminal Configuration

This section represents configuration parameters for running terminal-based applications. If enabled, applications started in this manner can be interacted with in the client. Parameters:

Enabled: Whether or not the terminal service is enabled
DefaultCommand: The default command to use when running terminals. The default is platform-specific. (e.g. command = "/bin/bash", command = "powershell.exe")
Scrollback: Default number of lines of scrollback history kept.
MaxScrollback

Tunnel Configuration

This section contains configuration parameters for TLS-tunneled TCP connections to configured applications. Parameters:

Enabled: Whether or not the tunnel service is enabled.
ServerPort: TCP port on which to bind the tunneling service. The default is port 22.
AllowedPorts: List of allowed ports for tunneling. It may be a single port, a range of ports, or an array of ports.
CertOpts: Options for the self-signed TLS certificate generated by the tunneling service.
- Country: If specified, the country MUST be a two-letter country code.
- Organization
Services: Optional names for ports, which may be referred to in the connection instructions for the VM.
TunlsLogLevel: If specified, the log level to use for tunnels log messages. Messages will only be logged if the log level is less or equal to the configured value. Valid values are:
```
- None     = 0
- Errors   = 1
- Warnings = 2
- Info     = 3
- Debug    = 4

If no log level is specified, the Errors log level will be used.
```
AddGroups: If specified, users will be added to the following system groups if they are not already members when opening a tunnel.
IdleTimeout: If non-zero, tunnels will be killed after this amount of time with no active connections being forwarded.
SFTPEnabled: If set to true, SFTP support will be enabled. SFTP support works by running an SSHD instance that is configured to listen on localhost and only allow SFTP connections.
SFTPPort: Local port on which the SSH daemon will be configured to listen. If not set or set to an invalid port, the default of 2022 will be used.
SSHDirPath: Path to directory containing the sshd and ssh-keygen executables. If not set, the VM controller will first check in the assets for bin/ssh/, then the system paths.

Stats Configuration

A StatsConfig contains configuration parameters for the stats service. Parameters:

SystemInterval: How often to poll system stats.
LogErrors: Whether to log errors from retrieving system stats. Default is false, as timeouts occur on Windows relatively frequently on systems under heavy use when requesting CPU information.

User Configuration

This sections contains options related to users and profiles. Parameters:

ChangeAdministratorPassword: if set to true, the admin password will be changed automatically.
ManagersAsAdmins: if set to true, it will make every managers an administrator.
CreateDirs: will create the specified directories in the user home.
CreateHiddenDirs: will create the specified hidden directories in the user home.
UserProfileLinkType: of type string, default value: "hardlink". Other possible values: "softlink".

Commands Configuration

This section contains the root and user commands to run in certain stages of the image. This feature enables the creator of the VM Image to define certain commands or scripts they want to run in certain stages of the VM. Parameters:

RootCommands: Commands to run as root.
- RETCommands: Run every time commands. These commands will be run every time the VM gets to the stage that triggers them.
- ROOCommands: Run only once commands. These commands will run only the first time the VM gets to the stage that triggers them if successful. Otherwise it will keep running every time the VM gets to that stage until the command runs successfully.
UserCommands: Commands to run as the user.
- RETCommands: Same as in Root Commands.
- ROOCommands: Same as in Root Commands.

It is also possible to run root commands that contain user information. For example, we might need to give ownership of a protected file to our user. That command could look something like this: chown myuser some/folder. We can get the program to inject the correct user by writing @:user: in the command configuration (e.g. chown @:user: some/folder). The VM Controller will replace the string @:user: for the username of the user triggering the commands. Currently, the only events supported are on_login and on_homeDriveAttached.

VM Image Configuration Example

[debug]
#Defines the level of logs that will be printed by the VMC
#Possible values are: "trace", "debug", "info", "warn", "error", "fatal", "panic"
#Default value is "info"
#logLevel="info"

#Managers of the VMC can be allowed to run sudo commands. This is disabled by default.
#enableManagerSudo = false


[terminal]
# 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
#maxScrollback = 100000

# A TunnelConfig contains configuration parameters for TLS-tunneled TCP
# connections to configured applications.
[tunnel]
# 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, 5901 ]

# If specified, the log level to use for tunls log messages. Messages will
# only be logged if the log level is <= the configured value.
#
# Valid values are:
#   - None     = 0
#   - Errors   = 1
#   - Warnings = 2
#   - Info     = 3
#   - Debug    = 4
#
# If no log level is specified, the Errors log level will be used
# tunlsLogLevel = "info"  # default

# 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.
[tunnel.services]
#vnc = 5901
#xpra = 14500

# Options for the self-signed TLS certificate generated by the tunneling
# service.
[tunnel.cert]
# If specified, country MUST be a two-letter country code.
#country = "US"
#organization = "unspecified"

[stats]
# How often to poll system stats in nanoseconds. Default is 1 second.
# systemInterval = 

# User configuration
[users]
# If true, the VMC will not attempt to change the admin password at startup.
#dontChangeAdminPassword = true

# Change to true if you want managers to automatically become VM
# administrators.
#managersAsAdmin = false

# Uncomment and add names of directories to be automatically created in the
# user's home on their encrypted drive if they do not already exist.
# This will allow for the directories to be automatically linked into the user's
# profile on the C: drive even if they did not originally exist.
#createDirs = []
#createHiddenDirs = []

# Password Length of the random password created for the users.
#passwordLength = 32

# Link type only applicable for Windows
# Possible values are "junction" and "softlink"
# Default value is "junction"
#userProfileLinkType = "junction"

# Commands
[commands]
# Commands to be run by root
[commands.rootCommands]
# Only once
[commands.rootCommands.runOnlyOnceCommands]
# ...
#Every Time
[commands.rootCommands.runEveryTimeCommands]

# This feature enables the creator of the VM Image to define certain commands or scripts they want to run in certain stages of the VM
# Dynamic parameters can also be passed to these scripts using the @:parameterName: syntax
# We support the following events and tags:
#   "on_login" : {@:user:}
#   "on_homeDriveAttached" : {}
#   "on_driveAttached" : {@:driveName:, @:driveSlot:, @:driveType:}
#   "on_vpnConnected" : {}

# When a home drive is attached, both the events on_homeDriveAttached & on_driveAttached are triggered in that order

# Syntax
# event_name = {command0_name = "command0", command1_name = "command1"} 
# Examples:
# on_login = {setXdgRuntimeDir = “install -o @:user: -m 700 -d /run/user/$(id -u @:user:)“, dockerGroup = “usermod -aG docker @:user:“}
# on_driveAttached = {setENV = "export DRIVE=@:driveName:"}

# To run a command in async mode, add "-async" to the event name
# Example: on_driveAttached-async = {setENV = "export DRIVEASYNC=@:driveSlot:"}

# Commands to be run by the user
[commands.userCommands]
# Only once
[commands.userCommands.runOnlyOnceCommands]
# ...
# Every Time
[commands.userCommands.runEveryTimeCommands]
# ...

Image Configuration Structure

Debug Section [debug]​

Terminal section [terminal]​

Tunnel section [tunnel]​

Statistics section [stats]​

Commands section [commands]​

VM Image Configuration Example

toml​

Commands section​

Example Conf File​

Image Configuration

Image Configuration Structure​

Global Settings​

ControllerSubvariant​

ConfigPrefix​

Debug Configuration​

Terminal Configuration​

Tunnel Configuration​

Stats Configuration​

User Configuration​

Commands Configuration​

VM Image Configuration Example​

Debug Section `[debug]`

Terminal section `[terminal]`

Tunnel section `[tunnel]`

Statistics section `[stats]`

Commands section `[commands]`

`toml`

Commands section

Example Conf File

Image Configuration Structure

Global Settings

ControllerSubvariant

ConfigPrefix

Debug Configuration

Terminal Configuration

Tunnel Configuration

Stats Configuration

User Configuration

Commands Configuration

VM Image Configuration Example