Skip to main content


The VILLASnode configuration consists of a a single file.

For a collection of example configuration files see:

File format

VILLASnode currently supports two config file formats:

Note: Consider using the villas conf2json command to migrate your old configurations to JSON.

Top-level Structure

At the top level, the configuration file consists of these sections:

OpenAPI / JSON Schema Specification

There exists a formal description of the configuration file as a JSON Schema / OpenAPI 3.0 specification.

The remaining part of this subsection shows a HTML version of this schema rendered by Redoc:

object (Node list)

A list of nodes to/from which this instance sends/receives sample data.

Array of objects (Path list)
Default: []

A list of uni-directional paths which connect the nodes defined in the nodes list.

object (http)
object (Logging configuration)
integer (Number of reserved hugepages)
Default: 100

The number of hugepages which will be reservered by the system.


A value of zero will disable the use of huge pages.

number (Statistics interval)
Default: 1

Specifies the rate at which statistics about the active paths will be periodically printed to the screen.

Setting this value to 5, will print 5 lines per second.

A line includes information such as:

  • Source and Destination of path
  • Messages received
  • Messages sent
  • Messages dropped
integer (Task/Process affinity mask)
Default: 0

Restricts the exeuction of the daemon to certain CPU cores. This technique, also called 'pinning', improves the determinism of the server by isolating the daemon processes on exclusive cores.

A value of 0 will not change the affinity of the process.

Default: 0

Adjusts the scheduling priority of the deamon processes. By default, the daemon uses a real-time optimized FIFO scheduling algorithm.

A value of 0 will not change the priority of the process.

Default: false
string <uuid> (Super-node UUID)
Default: "randomly generated"

Each VILLASnode instance is identified by a globally unique indentifier / UUID.

This UUID can be queried by the API.

If the setting is not provided, a UUID will be generated by hashing the active VILLASnode configuration. This ensures that restarting the VILLASnode instance with the identical configuration will yield always the same UUID.

  • "nodes": {
  • "paths": [ ],
  • "http": {
  • "logging": {
  • "hugepages": 100,
  • "stats": 1,
  • "affinity": 0,
  • "priority": 0,
  • "idle_stop": false,
  • "uuid": "randomly generated"


VILLASnode comes with a lot of existing configurations which can be used for inspiration:

# Global configuration settings go here
stats = 2

# Webserver / API config
http = {
port = 8081

# Logging
logging = {
level = "debug

# Node definitions
nodes = {
test_node = {
in = {
signals = {
count = 12
type = "float"

# Path Mapping
paths = (
in = "test_node",
out = "test_node"

Tips & Tricks

Use environment variables in your configuration

VILLASnode substitutes any environment variables in you JSON and libconfig configuration files.

To replace environment variables you must use the following syntax within any string value of your config: ${MYENV_VAR}.

Note: Non-string values can currently not be substituted by environment variables!


nodes = {
file_node = {
uri = "${FILE_PATH}"

Include other files into your configuration

VILLASnode can include other files into you configuration. This allows you to better structure and reuse parts of your configuration (e.g. the node definitions).

File inclusion is handled via a special key in JSON objects named @include. The value of this key must point to an existing file on your file system.

Note: libconfig supports inclusion of other files out of the box via @include directives. So this tip is mostly useful for JSON configuration files.


"gain": 1.45,
"t_dt": 50e-6
"test_node": {
"type": "file",
"in": {
"signals": {
"count": 12,
"type": "float"
"signal_node": {
"signal": "random",
"in": {
"hooks": [
"type": "lua",
"script": "myscript.lua",
"@include": "params.json"
"@include": "nodes.json"
"paths": [
"in": "signal_node",
"out": "test_node"