diff options
| -rw-r--r-- | docs/src/references/c8y-configuration-management.md | 34 |
1 files changed, 22 insertions, 12 deletions
diff --git a/docs/src/references/c8y-configuration-management.md b/docs/src/references/c8y-configuration-management.md index 013dfb30..cab49bb4 100644 --- a/docs/src/references/c8y-configuration-management.md +++ b/docs/src/references/c8y-configuration-management.md @@ -13,8 +13,9 @@ Thin-edge provides an operation plugin to that will be managed from the cloud tenant. * Notably, __the plugin configuration itself is managed from the cloud__, meaning, the device owner can update from the cloud the list of files to be managed. -* By default, __the managed files are represented on the cloud by their full path on the device__. - Optionally, the device owner can assign an alias to each target path. +* Cumulocity manages the configuration files accordingly to their type, + a name that is chosen by the device owner to categorise each configuration. + By default, the full path of a configuration file on the device is used as its type. * When files are downloaded from the cloud to the device, __these files are stored in a temporary directory first__. They are atomically moved to their target path, only after a fully successful download. @@ -72,20 +73,26 @@ The `c8y_configuration_plugin` configuration is stored by default under `/etc/te This [TOML](https://toml.io/en/) file defines the list of files to be managed from the cloud tenant. Each configuration file is defined by a record with: * The full `path` to the file. +* An optional configuration `type`. If not provided, the `path` is used as `type`. +* Optional unix file ownership: `user`, `group` and octal `mode`. + These are only used when a configuration file pushed from the cloud doesn't exist on the device. + When a configuration file is already present on the device, this plugin never changes file ownership, + ignoring these parameters. ```shell $ cat /etc/tedge/c8y/c8y-configuration-plugin.toml files = [ - { path = '/etc/tedge/tedge.toml' }, + { path = '/etc/tedge/tedge.toml', type = 'tedge.toml' }, { path = '/etc/tedge/mosquitto-conf/c8y-bridge.conf' }, { path = '/etc/tedge/mosquitto-conf/tedge-mosquitto.conf' }, - { path = '/etc/mosquitto/mosquitto.conf' } + { path = '/etc/mosquitto/mosquitto.conf', type = 'mosquitto', user = 'mosquitto', group = 'mosquitto', mode = 0o644 } ] ``` Note that: * The file `/etc/tedge/c8y/c8y-configuration-plugin.toml` itself doesn't need to be listed. This is implied, so the list can *always* be configured from the cloud. + The `type` for this self configuration file is `c8y-configuration-plugin`. * If the file `/etc/tedge/c8y/c8y-configuration-plugin.toml` is not found, empty, ill-formed or not-readable then only `c8y-configuration-plugin.toml` is managed from the cloud. @@ -144,12 +151,15 @@ The `c8y_configuration_plugin` reports progress and errors on its `stderr`. When a configuration file is successfully downloaded from the cloud, the `c8y_configuration_plugin` service notifies this update over MQTT. -* Each message provides the path to the freshly updated file as in `{ "changedFile": "/etc/tedge/tedge.toml" }`. -* The messages are published on `tedge/configuration_change`. +* The notification messages are published on the topic `tedge/configuration_change/{type}`, + where `{type}` is the type of the configuration file that have been updated, + for instance `tedge/configuration_change/tedge.toml` +* Each message provides the path to the freshly updated file as in `{ "path": "/etc/tedge/tedge.toml" }`. -## Internals - -Points that still need to be addressed: - -* Ability to give a type name to a configuration file. -* What if the target file doesn't exist? Is this is an error? If not what user, group and mod are to be used?
\ No newline at end of file +Note that: +* If no specific type has been assigned to a configuration file, then the path to this file is used as its type. + Update notifications for that file are then published on the topic `tedge/configuration_change/{path}`, + for instance `tedge/configuration_change//etc/tedge/mosquitto-conf/c8y-bridge.conf`. +* Since the type of configuration file is used as an MQTT topic name, the characters `#` and `+` cannot be used in a type name. + If such a character is used in a type name (or in the path of a configuration file without explicit type), + then the whole plugin configuration `/etc/tedge/c8y/c8y-configuration-plugin.toml` is considered ill-formed.
\ No newline at end of file |