From 072c6a1aaea508a377c7efb626cd1ffdfc329837 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Mon, 5 Feb 2024 17:10:33 +0100 Subject: [PATCH 1/4] Fix typo Signed-off-by: Didier Wenzek --- docs/src/understand/digital-twin.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/src/understand/digital-twin.md b/docs/src/understand/digital-twin.md index 081624f969f..3cb620e9ac8 100644 --- a/docs/src/understand/digital-twin.md +++ b/docs/src/understand/digital-twin.md @@ -58,7 +58,7 @@ This is usually, but not necessarily, the gateway device where %%te%% is running A child device is a device that is attached to the equipment. A child device can have further nested child devices as well, -forming a hierarchy, with the main device as root and the services as leafs, +forming a hierarchy, with the main device as root and the services as leaves, zooming in from the piece of equipment into its parts. ### Device Profile From 20bfb5a4cc7b59902f04e963d1f7a0da86a1ffbd Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Mon, 5 Feb 2024 19:01:01 +0100 Subject: [PATCH 2/4] Move into configuration intro the content related to tedge config Signed-off-by: Didier Wenzek --- .../configuration/configuration-tools.md | 54 ++---- docs/src/operate/configuration/index.md | 171 +++++++++++++++++- .../configuration/path-configuration.md | 47 +---- 3 files changed, 181 insertions(+), 91 deletions(-) diff --git a/docs/src/operate/configuration/configuration-tools.md b/docs/src/operate/configuration/configuration-tools.md index 414db7c3b0d..62595162be5 100644 --- a/docs/src/operate/configuration/configuration-tools.md +++ b/docs/src/operate/configuration/configuration-tools.md @@ -1,51 +1,20 @@ --- -title: Configuration Tools +title: Configuration Overriding tags: [Operate, Configuration] description: Customizing %%te%% settings --- -## Overview +## Configuration Path -%%te%% can be configured in a few different ways: +`/etc/tedge/tedge.toml` is the default location for %%te%% configuration. -1. The `tedge config` command ([reference here](../../references/cli/tedge-config.md)) -2. The `tedge.toml` file -3. Environment variables +This can be changed by passing an explicit `--config-dir` to all the %%te%% command invocations. -The following sections detail each of the configuration methods. - -## tedge config command - -To set a value in `tedge.toml` using the `tedge` CLI, you can run: - -```sh -sudo tedge config set c8y.url mytenant.cumulocity.com -``` - -The command will set the Cumulocity tenant URL (`c8y.url`) to `mytenant.cumulocity.com` and write the result to [`/etc/tedge/tedge.toml`](#tedgetoml). - -To read the value, run: +For instance, the following uses `/tmp/tedge.toml` to set the `c8y.url` and launch the Cumulocity mapper. ```sh -tedge config get c8y.url -``` - -```text title="Output" -mytenant.cumulocity.com -``` - -## tedge.toml - -`/etc/tedge/tedge.toml` is the file `tedge config` writes to when making a configuration change. As the name suggests, this should be in the [toml format](https://toml.io/). - -The Cumulocity tenant URL and MQTT bind address can be set by the following configuration: - -```toml title="file: /etc/tedge/tedge.toml" -[c8y] -url = "mytenant.cumulocity.com" - -[mqtt] -bind_address = "127.0.0.1" +tedge --config-dir /tmp config set c8y.url mytenant.cumulocity.com +tedge-mapper --config-dir /tmp c8y ``` ## Environment variables @@ -92,9 +61,12 @@ env TEDGE_C8Y_URL=example.com tedge config get example.com ``` -## Unrecognised configurations +## User-specific Configurations -When tedge commands (`tedge`, `tedge-agent`, `tedge-mapper`) detect a configuration setting they don't recognise, they will emit a warning log message[^1]: +The `/etc/tedge/tedge.toml` file can include extra settings used by user-specific plugins. + +When the %%te%% commands (`tedge`, `tedge-agent`, `tedge-mapper`) detect a configuration setting they don't recognise, +they will emit a warning log message: ```sh env TEDGE_C8Y_UNKNOWN_CONFIGURATION=test tedge config get c8y.url @@ -104,5 +76,3 @@ 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 mytenant.cumulocity.com ``` - -[^1]: The log preamble has been abbreviated to aid readability here diff --git a/docs/src/operate/configuration/index.md b/docs/src/operate/configuration/index.md index f69f53096a3..421f35407a9 100644 --- a/docs/src/operate/configuration/index.md +++ b/docs/src/operate/configuration/index.md @@ -5,8 +5,173 @@ sidebar_position: 2 description: How to configure %%te%% --- -import DocCardList from '@theme/DocCardList'; +The settings of all the %%te%% components are grouped in the `/etc/tedge/tedge.toml` file, using [TOML](https://toml.io/). +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. -How to configure %%te%% +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`](../../references/cli/tedge-config.md) 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 %%te%% configuration. + +### List configuration with descriptions + +Display a complete list of available settings with their purpose. + +```sh +tedge config list --doc +``` + +### List configuration that have been set or have defaults + +List the settings for which a specific value has been set. + +```sh +tedge config list +``` + +### Get a single configuration value + +Display the value for the `c8y.url` setting, if one has been set. + +```sh +tedge config get c8y.url +``` + +### Set configuration value + +Update/set the value for the `c8y.url` setting. + +``` +tedge config set c8y.url mytenant.cumulocity.com` +``` + +### Reset a configuration value to use default value + +Unset any user-specific value for the `c8y.url` setting, using then the default value. + +```sh +tedge config unset c8y.url +``` + +## Examples + +### Change path used for temporary files + +The following shows how to change the temp directory used by %%te%% and its components. + +1. Create a new directory which will be used by %%te%% + + ```sh + # 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 + + ```sh title="Example" + sudo tedge config set tmp.path ~/tedge_tmp_dir + ``` + + :::info + 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. + + ```sh + sudo systemctl restart tedge-agent + ``` + +To revert any of these paths back to their default locations, `unset` that config as follows: + +```sh +sudo tedge config unset tmp.path +``` + +Then restart the relevant services. + +```sh +sudo systemctl restart tedge-agent +``` + +## Customizing Settings + +### Configuration Path + +`/etc/tedge/tedge.toml` is the default location for %%te%% configuration. + +This can be changed by passing an explicit `--config-dir` to all the %%te%% command invocations. + +For instance, the following uses `/tmp/tedge.toml` to set the `c8y.url` and launch the Cumulocity mapper. + +```sh +tedge --config-dir /tmp config set c8y.url mytenant.cumulocity.com +tedge-mapper --config-dir /tmp c8y +``` + +### Environment variables + +To aid in configuring %%te%% in containerised environments, %%te%% supports passing in the configuration via environment variables. For instance, to configure the Cumulocity URL and MQTT bind address, you can run: + +```sh +env TEDGE_C8Y_URL=mytenant.cumulocity.com TEDGE_MQTT_BIND_ADDRESS=127.0.0.1 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: + +```sh +env TEDGE_C8Y_URL=mytenant.cumulocity.com tedge-mapper c8y +env TEDGE_C8Y_URL=mytenant.cumulocity.com 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: + +| Setting | Environment variable | +| ------------------- | ------------------------- | +| `c8y.url` | `TEDGE_C8Y_URL` | +| `device.key_path` | `TEDGE_DEVICE_KEY_PATH` | +| `device.cert_path` | `TEDGE_DEVICE_CERT_PATH` | +| `mqtt.bind.address` | `TEDGE_MQTT_BIND_ADDRESS` | + +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](#tedgetoml), you could run: + +```sh +tedge config get c8y.url +``` + +```text title="Output" +mytenant.cumulocity.com +``` + +Now we can run the same command but set an environment variable to override the value stored in the `tedge.toml` file. + +```sh +env TEDGE_C8Y_URL=example.com tedge config get +``` + +```text title="Output" +example.com +``` + +### User-specific Configurations + +The `/etc/tedge/tedge.toml` file can include extra settings used by user-specific plugins. + +When the %%te%% commands (`tedge`, `tedge-agent`, `tedge-mapper`) detect a configuration setting they don't recognise, +they will emit a warning log message: + +```sh +env TEDGE_C8Y_UNKNOWN_CONFIGURATION=test tedge config get c8y.url +``` + +```log title="Output" +2023-03-22 WARN tedge_config: Unknown configuration field "c8y.unknown_configuration" from environment variable TEDGE_C8Y_UNKNOWN_CONFIGURATION +mytenant.cumulocity.com +``` diff --git a/docs/src/operate/configuration/path-configuration.md b/docs/src/operate/configuration/path-configuration.md index 4640eb0a460..ef8cff4d2bb 100644 --- a/docs/src/operate/configuration/path-configuration.md +++ b/docs/src/operate/configuration/path-configuration.md @@ -4,7 +4,7 @@ tags: [Operate, Configuration, Unix] description: Customize %%te%% file/folder paths --- -## thin-edge.io directories +## %%te%% directories The `tedge config set` command can be used to change various file system paths used by the %%te%% components. The following table captures the paths that can be changed along with their default locations. @@ -21,48 +21,3 @@ The following daemons also need to be re-started after `data.path` is updated: * `tedge-agent` * `c8y-firmware-plugin` - -## Example: Set a custom temporary directory path - -The following shows how to change the temp directory used by %%te%% and its components. - - -1. Create a new directory which will be used by %%te%% - - ```sh - # 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 - - ```sh title="Example" - sudo tedge config set tmp.path ~/tedge_tmp_dir - ``` - - :::info - 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. - - ```sh - sudo systemctl restart tedge-agent - ``` - -## Example: Revert custom path settings - -To revert any of these paths back to their default locations, `unset` that config as follows: - -```sh -sudo tedge config unset tmp.path -``` - -Then restart the relevant services. - -```sh -sudo systemctl restart tedge-agent -``` From 7e12aca59971f0257d24868bd2e3741e88df75fe Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Mon, 5 Feb 2024 19:03:27 +0100 Subject: [PATCH 3/4] Remove "Configuration tools" section The content has been moved to the Configuration index page. Signed-off-by: Didier Wenzek --- .../configuration/configuration-tools.md | 78 ------------------- 1 file changed, 78 deletions(-) delete mode 100644 docs/src/operate/configuration/configuration-tools.md diff --git a/docs/src/operate/configuration/configuration-tools.md b/docs/src/operate/configuration/configuration-tools.md deleted file mode 100644 index 62595162be5..00000000000 --- a/docs/src/operate/configuration/configuration-tools.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Configuration Overriding -tags: [Operate, Configuration] -description: Customizing %%te%% settings ---- - -## Configuration Path - -`/etc/tedge/tedge.toml` is the default location for %%te%% configuration. - -This can be changed by passing an explicit `--config-dir` to all the %%te%% command invocations. - -For instance, the following uses `/tmp/tedge.toml` to set the `c8y.url` and launch the Cumulocity mapper. - -```sh -tedge --config-dir /tmp config set c8y.url mytenant.cumulocity.com -tedge-mapper --config-dir /tmp c8y -``` - -## Environment variables - -To aid in configuring %%te%% in containerised environments, %%te%% supports passing in the configuration via environment variables. For instance, to configure the Cumulocity URL and MQTT bind address, you can run: - -```sh -env TEDGE_C8Y_URL=mytenant.cumulocity.com TEDGE_MQTT_BIND_ADDRESS=127.0.0.1 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: - -```sh -env TEDGE_C8Y_URL=mytenant.cumulocity.com tedge-mapper c8y -env TEDGE_C8Y_URL=mytenant.cumulocity.com 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: - -| Setting | Environment variable | -| ------------------- | ------------------------- | -| `c8y.url` | `TEDGE_C8Y_URL` | -| `device.key_path` | `TEDGE_DEVICE_KEY_PATH` | -| `device.cert_path` | `TEDGE_DEVICE_CERT_PATH` | -| `mqtt.bind.address` | `TEDGE_MQTT_BIND_ADDRESS` | - -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](#tedgetoml), you could run: - -```sh -tedge config get c8y.url -``` - -```text title="Output" -mytenant.cumulocity.com -``` - -Now we can run the same command but set an environment variable to override the value stored in the `tedge.toml` file. - -```sh -env TEDGE_C8Y_URL=example.com tedge config get -``` - -```text title="Output" -example.com -``` - -## User-specific Configurations - -The `/etc/tedge/tedge.toml` file can include extra settings used by user-specific plugins. - -When the %%te%% commands (`tedge`, `tedge-agent`, `tedge-mapper`) detect a configuration setting they don't recognise, -they will emit a warning log message: - -```sh -env TEDGE_C8Y_UNKNOWN_CONFIGURATION=test tedge config get c8y.url -``` - -```log title="Output" -2023-03-22 WARN tedge_config: Unknown configuration field "c8y.unknown_configuration" from environment variable TEDGE_C8Y_UNKNOWN_CONFIGURATION -mytenant.cumulocity.com -``` From 748c295ee50f24d13d4b373698b01db12ec6bfe4 Mon Sep 17 00:00:00 2001 From: Didier Wenzek Date: Tue, 6 Feb 2024 11:52:37 +0100 Subject: [PATCH 4/4] Remove unnecessarily repeated content Signed-off-by: Didier Wenzek --- .../configuration/mapper-configuration.md | 10 ----- .../configuration/mosquitto-configuration.md | 42 ++++--------------- 2 files changed, 9 insertions(+), 43 deletions(-) diff --git a/docs/src/operate/configuration/mapper-configuration.md b/docs/src/operate/configuration/mapper-configuration.md index ab88c5ac318..5e7b856e965 100644 --- a/docs/src/operate/configuration/mapper-configuration.md +++ b/docs/src/operate/configuration/mapper-configuration.md @@ -60,13 +60,3 @@ The following command shows how to restart the Cumulocity IoT mapper on a device ```sh sudo systemctl restart tedge-mapper-c8y ``` - -## Change back to the default topics - -If you want a mapper to subscribe back to the default MQTT topics, run: - -```sh -sudo tedge config unset c8y.topics -``` - -Then restart the corresponding mapper. diff --git a/docs/src/operate/configuration/mosquitto-configuration.md b/docs/src/operate/configuration/mosquitto-configuration.md index 295528ea593..a82dd4e4114 100644 --- a/docs/src/operate/configuration/mosquitto-configuration.md +++ b/docs/src/operate/configuration/mosquitto-configuration.md @@ -17,7 +17,13 @@ The mqtt.bind.port and the mqtt.bind.address can be set/unset independently. The %%te%% device has to be disconnected from the cloud using the `tedge` command ```sh -tedge disconnect c8y/az +tedge disconnect c8y + +#or +tedge disconnect az + +#or +tedge disconnect aws ``` ### Step 2: Set the new mqtt port and bind address @@ -40,21 +46,7 @@ For example, this can be get as `ifconfig | grep inet` or set it to `0.0.0.0` This will make sure that all the mqtt clients use the newer port and the bind address that has been set once the device is connected to the cloud as in step 3. -### Step 3: Verify the port and the bind address configured/set - -Use the `tedge` command to print the mqtt port and bind address that has been set as below. - -```sh -tedge config get mqtt.bind.port -tedge config get mqtt.bind.address -``` - -```text title="Output" -1883 -0.0.0.0 -``` - -### Step 4: Connect the thin edge device to cloud +### Step 3: Connect the device to cloud Use the `tedge` command to connect to the desired cloud as below. @@ -69,23 +61,7 @@ tedge connect aws ``` This will configure all the services (mosquitto, tedge-mapper-c8y.service, tedge-mapper-az.service, - tedge-mapper-aws.service, tedge-agent.service) to use the newly set port and the bind address. - -:::note -The step 1 and 2 can be followed in any order. -::: - -## Revert to use default port and bind address - -Use the `tedge` command to set the default port (1883) and default bind address (localhost) as below. - -```sh -sudo tedge config unset mqtt.bind.port -sudo tedge config unset mqtt.bind.address -``` - -Once the port or the bind address is reverted to default, the [step 1](#Step-3:-Connect-the-thin-edge-device-to-cloud) -and 3 has to be followed to use the default port or the default bind address. +tedge-mapper-aws.service, tedge-agent.service) to use the newly set port and the bind address. ## Common Errors