Merge pull request #2682 from didier-wenzek/docs/clarify-configuratio…

…n-tools

Docs/clarify configuration tools

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.
 
-<DocCardList />
+## 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
+```

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.

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