This Wiki site provides more in-depth info on Vasum configuration files - how Vasum is configured, where configuration files are and what are their contents.
Static configuration
Part of Vasum configuration is kept in static files. These options are kept constant throughout Vasum Servers lifetime. In order to adjust how Vasum works, user can change these options, however applying them requires Vasum to be rebooted.
Static configuration files are written using JSON open standard format, and can be found in /etc/vasum/ directory, as files with .conf extension. The files can be split into two categories:
- Main daemon configuration - there is only one such file, daemon.conf, residing in /etc/vasum/ directory. It contains all the configuration options needed for Vasum to work properly.
- Zone template configuration - these reside in /etc/vasum/templates/ directory. There can be multiple template configuration files, each is used by Vasum Server to create a new Zone. User can specify which configuration file should be used when creating new zones.
Main daemon configuration
The following section covers all fields available as a main daemon configuration file.
dbPath
A string object, representing full path to Vasum dynamic configuration file. On launch the file is read by Vasum, if the file does not exist it is automatically created.
zoneIds
| "zoneIds" : [<string>, <string>, ...]
|
|
An array of strings, keeping pre-existing zone IDs. Vasum will locate and launch these zones at startup.
Deprecated: introduction of dynamic configuration moved the field to configuration database. The field should be left blank.
zonesPath
A string object, representing full path to a directory, where Zones are kept, or where newly created zones will be kept.
zoneImagePath
| "zoneImagePath" : <string>
|
|
A string object, representing full path to an image file, used when creating new Zones.
During new Zone creation, Vasum can use provided image file to copy its data when creating new Zone.
Deprecated: New Zones are created according to provided templates. The field should be left blank.
zoneTemplateDir
| "zoneTemplateDir" : <string>
|
|
A string object, representing full path to a directory with templates used when creating new Zones. All configuration files used by Vasum to create a new Zone are kept inside this directory.
runMountPointPrefix
| "runMountPointPrefix" : <string>
|
|
A string object, representing full path to a directory where Zones run directory will be mounted.
Vasum creates a directory for each Zone inside runMountPointPrefix. There, each Zone has its run directory - its contents are bind-mounted inside Zone to a /run directory.
runMountPointPrefix is not a mandatory option and it can be left blank - Vasum Server will not create Zones run directory visible to Host.
defaultId
A string object, representing default Zone ID.
Vasum can receive a signal from an external tool - for example from a power management application - requesting a switch to default Zone. After receiving the signal, Vasum will switch to a Zone with ID provided in defaultId string.
defaultId is not a mandatory option and its field can be left blank - switching to default functionality will be disabled.
availableVTs
| "availableVTs" : [<int>, <int>, ...]
|
|
A vector of integers, holding available VTs for newly created Zones.
When creating a new Zone, Vasum will use VT numbers from provided vector. Depleting available VT count will result in an error.
The vector can be left blank - Zones will have no VT assigned to them.
inputConfig
| "inputConfig" : {
|
| "enabled" : <bool>,
|
| "device" : <string>,
|
| "code" : <int>,
|
| "numberOfEvents" : <int>,
|
| "timeWindowMs" : <int>
|
| }
|
|
An object containing multiple fields related to Input Monitor module in Vasum Server.
The object describes the functionality of Input Monitor - a module handling input events and notifying Vasum Server when a requested event occurs. It contains of the following fields:
- inputConfig.enabled - A boolean object, informing Vasum Server whether Input Monitor should be active.
- inputConfig.device - A string object, determining the name of a device to look for when initializing Input Monitor. You can either provide a event* device name, or a partial name from /dev/input/by-path directory. Input Monitor will perform a recursive regex search for a device containing specified name.
- inputConfig.code - An integer object, determining value of event code to monitor on inputConfig.device device.
- inputConfig.numberOfEvents - An integer object, determining how many events on inputConfig.device device with inputConfig.code code will trigger Input Monitor to perform a Zone switch. Maximum number of events is 10 - providing higher value results in Input Monitor exception.
- inputConfig.timeWindowMs - An integer object, determining time value in milliseconds within which inputConfig.numberOfEvents events shall occur. Maximum possible time is 10000 milliseconds (10 seconds) - providing higher value results in Input Monitor exception.
Input Monitor will notify Vasum Server about a detected event when inputConfig.numberOfEvents events will happen within inputConfig.timeWindowMs milliseconds.
Zone template configuration
Vasum Server provides a functionality to add new Zones dynamically. To allow configurability during Zone creation process, Vasum handles specifically designed files called templates. The template configuration files for each Zone are kept inside /etc/vasum/templates directory. Each Zone template is described using JSON. From provided template, Vasum Server generates a Zone-specific configuration, and uses it later on during launch process.
To make the templates more generic, Vasum Server supports regexp strings, which can be used to modify specific template fields dynamically:
- ~NAME~ - A regexp, which will be replaced by Zone name.
- ~IP~ - A regexp, which will be replaced by Zone-specific IP octet. The regexp was designed to use exclusively together with #ipv4 and #ipv4Gateway string objects to create unique IPs for Zones.
The following section covers all fields available inside Zone template configuration file.
zoneTemplate
| "zoneTemplate" : <string>
|
|
A string object containing full path to Zone template script associated with defined Zone.
initWithArgs
| "initWithArgs" : [<string>, <string>, ...]
|
|
An array object containing a list of arguments used during Zone initialization.
When a Zone is launched, it can call a user-provided command as a Zone init process. Vasum Server will use the initWithArgs list to build a string array and will provide it to LXC as a launch command.
When launching a separate Linux system inside Zone, it is recommended to leave this field empty. Vasum Server will add a default init command /sbin/init.
requestedState
| "requestedState" : <string>
|
|
A string object containing requested Zone state. See Zone lifecycle description for more info about Zone lifecycle.
Available states to request are: stopped, running, paused.
ipv4Gateway
A string object containing IP gateway for Zone.
ipv4
A string object containing IP for Zone.
cpuQuotaForeground
| "cpuQuotaForeground" : <int>
|
|
An integer object containing information how much CPU quota should be assigned when Zone is running in foreground.
CPU quota determines how much processing power is available inside Zone from Host. The integer is passed to LXC as a CGroup setting - accepted vales are 1000 or higher. To assign all possible resources to a Zone, assign -1 value.
This CPU quota value will be used when Zone will be running in foreground. Only one Zone can run in foreground, while others are set to background. In general, cpuQuotaForeground should be set to a higher value than cpuQuotaBackground.
cpuQuotaBackground
| "cpuQuotaBackground" : <int>
|
|
An integer object containing information how much CPU quota should be assigned when Zone is running in background.
For information on CPU quota read the description of #cpuQuotaForeground. In general, it is a good idea to set cpuQuotaBackground to a lower value than cpuQuotaForeground.
privilege
An integer object informing Vasum Server how important the Zone is. The lower the value, the more important the Zone is.
vt
An integer object containing information which Virtual Terminal should be assigned to a Zone. -1 means no VT should be assigned.
shutdownTimeout
| "shutdownTimeout" : <int>
|
|
An integer object containing time in seconds during which Zone should gracefully shut down. After given time, if Zone is still on, forced shutdown occurs.
To wait forever and never force-shutdown the Zone, set this value to -1. If you want to skip waiting and immediately force-quit the Zone, set the timeout to 0.
switchToDefaultAfterTimeout
| "switchToDefaultAfterTimeout" : <bool>
|
|
A boolean object informing Vasum Server whether, assuming defined Zone is running in foreground, a switch to default Zone should occur. See #defaultId for more info about switching to default Zone.
runMountPoint
| "runMountPoint" : <string>
|
|
A string object defining a path within which Zones /run directory will be visible from Host. The contents of this string are attached to #runMountPointPrefix, and create a full path where one can find Zones /run mount point.
provisions
| "provisions" : [<provisionObject>, <provisionObject>, ...]
|
|
An array object containing multiplie objects defining provisioning for specified zone.
Provisioning tells Vasum Server to perform a specific file-related operation right before launch. There are three types of available provisionObjects, each having different sub-objects:
Link
| {
|
| "source" : <string>,
|
| "target" : <string>
|
| }
|
|
- A Link provision object, defining a hard link to create right before Zone launch. Link object consists of:
-
- source - A string object containing full path to the linked file
- target - A string object containing full path to where the link will be created.
- Both source and target are full paths in Zone's Mount Namespace. Possibility to create hard links is limited by #validLinkPrefixes list.
File
| {
|
| "type" : <int>,
|
| "target" : <string>,
|
| "flags" : <int>,
|
| "mode" : <int>
|
| }
|
|
- A File provision object, defining a file to create right before Zone launch. Consists of:
-
- type - An integer object, informing what type of file will be created. There are three available types: Directory (type = 0), FIFO (type = 1), Regular (type = 2).
- target - A string object, containing full path to where the file will be created. The path is in Zone's Mount Namespace.
- flags - An integer object, containing flags used to create a file with. These are important only when creating a Regular file (type = 2). The flags are passed directly to open syscall, with one exception - if the flag O_CREAT (0x100) is not supplied, Provisioning mechanism attempts to copy target file from Host to Zone, preserving the path.
- mode - An integer object, containing access rights to created file. This is a regular access right variable - refer to open syscall manual (man 2 open, O_CREAT flag description) for more info about file access permissions.
Mount
| {
|
| "source" : <string>,
|
| "target" : <string>,
|
| "type" : <string>,
|
| "flags" : <int>,
|
| "data" : <string>
|
| }
|
|
- A Mount provision object, defining a mount to perform right before Zone launch. Consists of:
-
- source - A string object, containing full path to something to be mounted.
- target - A string object, containing full path where specified source will be mounted. The path is inside Zone's Mount Namespace.
- type - A string object, containing information about filesystem type to mount.
- flags - An integer object, containing flags used during mount.
- data - A string object, containing comma-separated options understood by type filesystem.
- All these options are passed to mount syscall - refer to man 2 mount for more info.
validLinkPrefixes
| "validLinkPrefixes" : [<string>, <string>, ...]
|
|
An array object containing strings - path prefixes, used to validate hard link creation. Provisioning mechanism uses this list when creating Link provisions to determine inside which directories hard links can be created.
Dynamic configuration
Part of Zone configuration generated from templates goes to dynamic configuration file. It is a SQLite database, located in /etc/vasum/vasum.db file. The database comprises of following structure:
"data" table contains a regular key-value structure. The keys are separated into two groups:
- vasum group - this group contains all configuration information for Vasum Server just like main daemon configuration, however the information here can change.
- zone.<zoneName> group - similarly to Zone template configuration, these configurations are Zone-specific. Part of Zone template is reflected in this group and can change dynamically.
The following section will cover in-depth how specific groups reflect Vasum dynamic configuration.
NOTE: Even though this section covers dynamic configuration internals, it is recommended not to update fields described here directly. The only modifying tool of this database should be Vasum Server itself - to change the contents, use Vasum CLI tool.
Group "vasum"
The group covers Vasum Server settings, which are dynamically updated throughout Vasum Server lifetime.
zoneIds
A key containing integer value. Informs Vasum server how many Zones are defined.
zoneIds.<number>
| vasum.zoneIds.<number>|<string>
|
|
A key containing string value. Informs Vasum server about specific Zone's name. A string contained here is later on used as Zone ID in "zone" group.
defaultId
A key containing string value with default Zone ID. See #defaultId for more info.
Group "zone.<zoneName>"
Each defined Zone contains its own group, with its own configuration fields. The following section covers all Zone-specific keys.
zoneTemplatePath
| zone.<zoneName>.zoneTemplatePath|<string>
|
|
A full path to a template file, which was used to create <zoneName> Zone. Some configuration options are still constant throughout Server's lifecycle - Vasum Server checks some needed options inside template file.
requestedState
| zone.<zoneName>.requestedState|<string>
|
|
A key containing string value with requested Zone state. Vasum Server looks up this value during launch procedure. For more info see Zone lifecycle information page.
ipv4Gateway
| zone.<zoneName>.ipv4Gateway|<string>
|
|
A key containing string value with Zone's gateway IP. The value for this key is generated from Zone template using ~IP~ regexp.
ipv4
| zone.<zoneName>.ipv4|<string>
|
|
A key containing string value with Zone's IP. The value for this key is generated from Zone template using ~IP~ regexp.
vt
A key containing integer value informing Vasum Server which VT is currently assigned to a Zone. When a new Zone is created, its VT value can be assigned by Vasum Server from available VT pool. See #availableVTs for more info.
runMountPoint
| zone.<zoneName>.runMountPoint|<string>
|
|
A key containing string value - a path to Zone's run mount point. Zone template usually defines this value together with ~NAME~ regexp - the generated string is kept in this key. Value of this key is concatenated with #runMountPointPrefix to acquire a full path to Zones /run mount point.
