Configuration variables
Configuration variables allow you to provide runtime configuration to the host OS and supervisor. These variables all begin with BALENA_ or RESIN_. Beginning with supervisor v7.0.0, a number of them appear automatically in your dashboard when your device is provisioned.
Configuration variables can be managed at both the fleet and device level.
Note: Configuration variables defined in the dashboard will not apply to devices in local mode.
Variable list
This list contains configuration variables that can be used with balena devices, some of which will automatically appear for devices with supervisor v7.0.0 and greater. While they may not automatically populate in the dashboard, most of these variables can still be used with older supervisor versions, so be sure to check the Valid from column:
| Name | Default | Description | Valid from |
|---|---|---|---|
| BALENA_OVERRIDE_LOCK | 0 | When set to 1 overrides any existing update lock on the device. Allows updating devices in the case that the release locked updates but is stuck in an invalid state. | v1.0.0 |
| BALENA_SUPERVISOR_CONNECTIVITY_CHECK | true | Enable / Disable VPN connectivity check | v1.3.0 |
| BALENA_SUPERVISOR_LOCAL_MODE | false | Enable / Disable local mode | v4.0.0 |
| BALENA_SUPERVISOR_LOG_CONTROL | true | Enable / Disable logs being sent to the balena API | v1.3.0 |
| BALENA_SUPERVISOR_POLL_INTERVAL | 900000 | Define the balena API poll interval in milliseconds. This interval will only matter if the device is not connected to the VPN at the time an update is pushed, or if BALENA_SUPERVISOR_INSTANT_UPDATE_TRIGGER is set to false. Starting from supervisor v9.13.0, the supervisor will use a random time between 0.5 and 1.5 times this poll interval each time it checks the balenaCloud API. The minimum value for this variable is defined by the balenaCloud backend, and may vary. | v1.3.0 |
| BALENA_SUPERVISOR_VPN_CONTROL | true | Enable / Disable VPN | v1.3.0 |
| BALENA_SUPERVISOR_INSTANT_UPDATE_TRIGGER | true | Enable / Disable instant triggering of updates when a new release is deployed. If set to false, the device will ignore the notification that is triggered when the device's target state has changed. In this case, the device will rely on polling to apply updates. Coupled with a large BALENA_SUPERVISOR_POLL_INTERVAL, this allows spreading out updates in large fleets to avoid overloading local networks when there is a large number of devices at one location. | v9.13.0 |
In addition to these values, there may be some device-type specific configuration variables that can be set. For example, these are a few of the values that apply to Raspberry Pi devices, corresponding to the contents of the Raspberry Pi config.txt file:
| Name | Default | Description |
|---|---|---|
| BALENA_HOST_CONFIG_disable_splash | 1 | Enable / Disable the Raspberry Pi rainbow splash screen |
| BALENA_HOST_CONFIG_dtparam | "i2c_arm=on","spi=on","audio=on" | Define DT parameters |
| BALENA_HOST_CONFIG_gpu_mem | 16 | Define device GPU memory in megabytes |
You can find more information on updating config.txt through configuration variables in our Advanced Boot Configuration Guide.
Managing fleet configuration variables
Configuration variables defined at the fleet level control the behavior of any devices running in that fleet unless they are redefined with a device configuration variable of the same name.
If you want to change the default value for one of the prepopulated configuration variables, make sure you are in the Fleet Configuration tab, then click activate for the variable you wish to define:
After activating, the variable will be populated with the default value. Variables that can be enabled or disabled can be switched with the provided toggles. Other values can be edited by clicking the small edit (pencil) icon. To remove the fleet configuration variable, and reset it to its default value, click the delete (trash can) icon.
To define a custom fleet configuration variable, scroll past the automatically populated variables, then click the Add custom variable button in the lower-right corner:
A dialog pops up giving you the option to define a name and value (remember, all config variable names must begin with BALENA_ or RESIN_). Click Add to apply:
If you have already defined configuration variables at the device level, they will appear in a list below your fleet configuration variables. You can easily apply a device value to the entire fleet by clicking Define fleet-wide:
Managing device configuration variables
Device configuration variables define the behavior of a single device. If both the fleet and the device have a configuration variable of the same name, the code on the device will use the value of the device configuration variable. In other words, device configuration variables redefine (or override) fleet configuration variables.
The device configuration variable list includes the prepopulated default values. Variables that can be enabled or disabled can be easily switched with the provided toggles. Other values can be edited by clicking the small edit (pencil) icon.
Clicking the edit icon will pop up a small dialog for editing the value:
To remove the device configuration variable, and reset it to its default value, click the delete (trash can) icon.
Adding a custom device configuration variable is very similar to adding a custom fleet configuration variable. Scroll past the prepopulated variables, click Add custom variable, define a name and value, and click Add.
You can override the value of a custom fleet configuration variable by clicking override. This will pop up the variable editing dialog, where you can change the value:
