Agent Configuration

The Overlock Agent is a flexible local logging destination which runs on IoT nodes.


  1. Configuration is stored in /etc/overlock.conf
  2. Values for node_id, project_id, project_key and product_name need to be set in the config file
  3. All other options are optional

More detail is given below.

Configuration file location

The config file should be placed in /etc/overlock.conf.

A few notes on node_id

the node_id can be set in a few ways which is so that it's easier to make Overlock fit in around your existing system. The order of precedence of the loading locations is:

  1. Environment OVERLOCK_NODE_ID
  2. node_id in the config file
  3. node_id file, from path from node_id_file in the config file

If none of these can be found then the Overlock agent will not start.

Configuration Options


The node_id should be set to your primary key or reference to the device you're installing Overlock on. For testing and one-off installations, node_id is an easier approach to setting the node_id than the node_id_file option, however the latter option is often a lot better when you're deploying lots of devices and want to minimize the need for custom config files.




The node_id_file option should point to a text file containing your ID of the IoT node which the agent is running on. E.g. if my device has an id of device_123, the node_id_file option should contain an absolute path to a text file containing device_123. Overlock will then know to use this as the Node's ID.


# This is the default

Contents of /etc/overlock_id:


Your IoT device should be provisioned such that it writes a node ID to the location that node_id_file points to. This allows you to store the node ID in a location such as an EEPROM or or in your own config file.

A common use case would be to set node_id_file to /tmp/overlock_id at boot time if the device ID is stored in your own config file.

The node ID can also be set with an environment variable called OVERLOCK_NODE_ID, see environment variables.


The project_id option is a project wide ID which is provided in your project settings page. This should be the same for all nodes which are connecting to your project. A default is not provided for this value.




project_key is an Overlock generated value of which there may be one or more of per project. A valid value for this can be gained from the project configuration page. A default is not provided for this.




The product_name option should be used to set the name of the product which the agent is running on, so that it can be grouped in the front-end. If not provided, it will default to _unknown.

product_name may contain letters, numbers, - and _. They must not start with an _ since these are reserved for special names, such as _unknown.




The default_context is the number of log events which should be sent to Overlock when a problem occurs. 50 is the default.




log_ttl sets the expiry on log messages in the cache. Log messages may be removed sooner if the log volume is high. The value is a number of seconds. 1 day is the default.


Set the `log_ttl` to 1 hour


The severity_threshold is the log level at which a Diagnostics report should be created and sent to Overlock. This defaults to the error threshold, but some developers may wish to change this to critical for example. 40 is the default.

Matching is done on a greater than or equal to basis.

Standard logging levels from the agents:

name numerical severity
debug 10
info 20
warning 30
error 40
critical 50



Using environment variables

All configuration options in the Overlock agent are also available as environment variables. normally this is just done as an all-caps version of the key name from the configuration file which is also prefixed with OVERLOCK_, e.g. OVERLOCK_LOG_TTL. Values have the same format as the documentation.

The only exception to this rule, is that in addition to OVERLOCK_NODE_ID_FILE, it's also possible to directly set the node_id with an environment variable by using OVERLOCK_NODE_ID.

Variables are only loaded when the agent starts and any changes will only be picked up when the agent is restarted. The agent should only really be started as soon as the system is up and running, so effectively changed variables should only be picked up after a system reboot.

Ordinarily you will only need to use environment variables if you're customizing the startup of the Overlock agent.