Specify Device Configuration Management using Cumulocity

Signed-off-by: Didier Wenzek <didier.wenzek@free.fr>

2 files changed, 163 insertions, 0 deletions

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index 8d7d37a4..c2c8dc22 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -48,6 +48,7 @@
     - [Init System configuration](references/init-system-config.md)
 
   - [Write my own software management plugin](./tutorials/write-my-software-management-plugin.md)
+  - [Device Configuration Management using Cumulocity](./references/c8y-configuration-management.md)
 
   - [APIs](api.md)
     - [The Bridged Topics](./references/bridged-topics.md)
diff --git a/docs/src/references/c8y-configuration-management.md b/docs/src/references/c8y-configuration-management.md
new file mode 100644
index 00000000..4decde65
--- /dev/null
+++ b/docs/src/references/c8y-configuration-management.md
@@ -0,0 +1,162 @@
+# Device Configuration Management using Cumulocity
+
+Thin-edge provides an operation plugin to
+[manage device configurations using Cumulocity](https://cumulocity.com/guides/users-guide/device-management/#to-retrieve-and-apply-a-configuration-snapshot-to-a-device-which-supports-multiple-configuration-types).
+
+* This management is bi-directional:
+  * A device can be taken as reference, all the managed files being uploaded to the cloud
+    and stored there as a configuration snapshot.
+  * A configuration snapshot can be pushed from the cloud to any devices of the same type,
+    i.e. supporting the same kind of configuration files.
+* With this operation plugin, the device owner defines the list of files
+  (usually configuration files, but not necessarily),
+  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.  
+* 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.
+  The aim is to avoid breaking the system with half downloaded files.
+* Once a snapshot has been downloaded from Cumulocity to the device,
+  __the plugin publishes a notification message on the local thin-edge MQTT bus__.
+  The device software has to subscribe to these messages if any action is required,
+  say to check the content of file, to preprocess it or to restart a daemon. 
+* In other words, the responsibilities of the plugin are:
+  * to define the list of files under configuration management
+  * to notify the cloud when this list is updated,
+  * to upload these files to the cloud on demand,  
+  * to download the files pushed from the cloud,
+  * to make sure that the target files are updated atomically after successful download,
+  * to notify the device software when the configuration is updated.
+* By contrast, the plugin is not responsible for:
+  * checking the uploaded files are well-formed,
+  * restarting the configured processes.
+* A user-specific component, installed on the device,
+  can implement more sophisticated configuration use-cases by:
+  * listening for configuration updates on the local thin-edge MQTT bus,
+  * restarting the appropriate processes when appropriate,  
+  * declaring intermediate files as the managed files,
+    to have the opportunity to check or update their content
+    before moving them to the actual targets.
+
+## Installation
+
+Assuming the configuration plugin `c8y_configuration_plugin`
+has been installed in `/usr/bin/c8y_configuration_plugin`,
+two files must be added under `/etc/tedge/operations/c8y/`
+to declare that this plugin supports two Cumulocity operations:
+uploading and downloading configuration files
+(which respective SmartRest2 codes are `526` and `524`).
+
+```shell
+$ ls -l /etc/tedge/operations/c8y/c8y_UploadConfigFile
+-rw-r--r-- 1 tedge tedge 95 Mar 22 14:24 /etc/tedge/operations/c8y/c8y_UploadConfigFile
+
+$ cat /etc/tedge/operations/c8y/c8y_UploadConfigFile
+[exec]
+  topic = "c8y/s/ds"
+  on_message = "526"
+  command = "/usr/bin/c8y_configuration_plugin"
+  
+$ ls -l /etc/tedge/operations/c8y/c8y_DownloadConfigFile
+-rw-r--r-- 1 tedge tedge 97 Mar 22 14:24 /etc/tedge/operations/c8y/c8y_DownloadConfigFile
+
+$ cat /etc/tedge/operations/c8y/c8y_DownloadConfigFile
+[exec]
+  topic = "c8y/s/ds"
+  on_message = "524"
+  command = "/usr/bin/c8y_configuration_plugin"
+```
+
+## Configuration
+
+The `c8y_configuration_plugin` configuration is stored by default under `/etc/tedge/c8y/c8y_configuration_plugin.toml`
+
+This [TOML](https://toml.io/en/) file defines the list of files to be managed from the cloud tenant.
+
+```shell
+$ cat /etc/tedge/c8y/c8y_configuration_plugin.toml
+files = [
+    '/etc/tedge/tedge.toml',
+    '/etc/tedge/mosquitto-conf/c8y-bridge.conf',
+    '/etc/tedge/mosquitto-conf/tedge-mosquitto.conf',
+    '/etc/mosquitto/mosquitto.conf'
+  ]
+```
+
+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.
+* 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.
+* If the file `/etc/tedge/c8y/c8y_configuration_plugin.toml` is ill-formed
+  or cannot be read then an error is logged, but the operation proceed
+  as if the file were empty.
+  
+The behavior of the `c8y_configuration_plugin` is also controlled
+by the configuration of thin-edge:
+
+* `tedge config get mqtt.bind_address`: the address of the local MQTT bus.
+* `tedge config get mqtt.port`: the TCP port of the local MQTT bus.
+* `tedge config get tmp.path`: the directory where the files are updated
+  before being copied atomically to their targets.
+* `tedge config get log.path`: the directory used for logging.
+
+## Usage
+
+```shell
+$ c8y_configuration_plugin
+Thin-edge device configuration management for Cumulocity
+
+USAGE:
+    c8y_configuration_plugin [OPTIONS] [SMARTREST_OPERATION]
+
+OPTIONS:
+        --config-file <CONFIG_FILE>    [default: /etc/tedge/c8y/c8y_configuration_plugin.toml]
+    -h, --help                         Print help information
+    -V, --version                      Print version information
+
+SMARTREST_OPERATION:
+    The SmartRest2 message received on `c8y/s/ds` and triggering either a download or an upload.
+    This operation is then processed in its enterity by the `c8y_configuration_plugin`,
+    notifying the Cumulocity tenant of its progress (messages `501`, `502` and `503`).
+    
+    If no SmartRest2 operation is provided, `c8y_configuration_plugin`
+    sends a `119` message to the cloud tenant with the list of managed configuration files.
+```
+
+## Logging
+
+The `c8y_configuration_plugin` reports progress and errors in the log file `/var/log/tedge/c8y_configuration_plugin.log`
+
+* All upload and download operation requests are logged, when received and when completed,
+  with one line per file.
+* All changes to the list of managed file is logged, one line per change.
+* All errors are reported with the operation context (upload or download? which file?).
+
+## Internals
+
+Points that still need to be addressed:
+
+* __CRITICAL__ When the list of configurations is sent to the Cumulocity?
+  * This question is related to how the `c8y_configuration_plugin` is launched.
+  * If launched by the mapper when a `524` or `526` message is received on `c8y/s/ds`,
+    then the `c8y_configuration_plugin` must be launched at least once to send a `119`.
+    * This can be done on install. Or when the file `c8y_configuration_plugin.toml` is changed.
+      This is utterly fragile.
+    * One can update the mapper to run `[init]` operations.
+      This is more consistent with the current design and will be useful for other operations
+      (for instance, log management).
+  * The `c8y_configuration_plugin` command can also run as a daemon that
+    sends a first `119` message, subscribe to `c8y/s/ds`,
+    and process autonomously the `524` or `526` messages.
+    * In that case, the files `/etc/tedge/operations/c8y/c8y_DownloadConfigFile`
+      and `/etc/tedge/operations/c8y/c8y_UploadConfigFile` are simply empty.
+    * The `c8y_configuration_plugin` has to be run as a daemon on the device.
+* The user running `c8y_configuration_plugin` must have read and write access
+  to all the files listed by the configuration `/etc/tedge/c8y/c8y_configuration_plugin.toml`.
+* When a download file is copied to its target, the unix user, group and mod must be preserved.
+  * 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