Skip to main content
Version: 1.0.1


The settings of all the components are grouped in the /etc/tedge/tedge.toml file, using TOML. These configuration settings are organized in a hierarchy that reflects the component hierarchy. For instance, all the settings related to Cumulocity IoT share a c8y prefix, such as c8y.url for the Cumulocity URL.

This file can be edited directly and can even be extended to include plugin-specific settings. However, it's recommended to use the tedge config command to edit the settings as it provides guidance for expected settings and checks for invalid entries.

Common Commands

The following is a list of common commands which can be used to get/set/list configuration.

List configuration with descriptions

Display a complete list of available settings with their purpose.

tedge config list --doc

List configuration that have been set or have defaults

List the settings for which a specific value has been set.

tedge config list

Get a single configuration value

Display the value for the c8y.url setting, if one has been set.

tedge config get c8y.url

Set configuration value

Update/set the value for the c8y.url setting.

tedge config set c8y.url`

Reset a configuration value to use default value

Unset any user-specific value for the c8y.url setting, using then the default value.

tedge config unset c8y.url


Change path used for temporary files

The following shows how to change the temp directory used by and its components.

  1. Create a new directory which will be used by

    # create a directory (with/without sudo)
    mkdir ~/tedge_tmp_dir

    # give ownership to tedge user and group
    sudo chown tedge:tedge ~/tedge_tmp_dir
  2. Update the tedge configuration to point to the newly created directory

    sudo tedge config set tmp.path ~/tedge_tmp_dir

    The directory must be available to tedge user and tedge group.

  3. Restart the tedge daemons after any of these paths are updated, for it to take effect.

    sudo systemctl restart tedge-agent

To revert any of these paths back to their default locations, unset that config as follows:

sudo tedge config unset tmp.path

Then restart the relevant services.

sudo systemctl restart tedge-agent

Customizing Settings

Configuration Path

/etc/tedge/tedge.toml is the default location for configuration.

This can be changed by passing an explicit --config-dir to all the command invocations.

For instance, the following uses /tmp/tedge.toml to set the c8y.url and launch the Cumulocity mapper.

tedge --config-dir /tmp config set c8y.url
tedge-mapper --config-dir /tmp c8y

Environment variables

To aid in configuring in containerised environments, supports passing in the configuration via environment variables. For instance, to configure the Cumulocity URL and MQTT bind address, you can run:

env TEDGE_MQTT_BIND_ADDRESS= tedge connect c8y 

The environment variables won't be stored anywhere, so you will need to set the relevant values when running the mapper and agent:

env tedge-mapper c8y 
env tedge-agent

The names for these environment variables are prefixed with TEDGE_ to avoid conflicts with other applications, and any .s in the variable names are replaced with _s. Some example mappings are shown below:

SettingEnvironment variable

You can also use tedge config to inspect the value that is set, which may prove useful if you are using a mix of toml configuration and environment variables. If you had tedge.toml file set as shown above, you could run:

tedge config get c8y.url

Now we can run the same command but set an environment variable to override the value stored in the tedge.toml file.

env tedge config get

User-specific Configurations

The /etc/tedge/tedge.toml file can include extra settings used by user-specific plugins.

When the commands (tedge, tedge-agent, tedge-mapper) detect a configuration setting they don't recognise, they will emit a warning log message:

env TEDGE_C8Y_UNKNOWN_CONFIGURATION=test tedge config get c8y.url
2023-03-22 WARN tedge_config: Unknown configuration field "c8y.unknown_configuration" from environment variable TEDGE_C8Y_UNKNOWN_CONFIGURATION