1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
# 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.
* 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.
The aim is to avoid breaking the system with half downloaded files.
* When a downloaded file is copied to its target, the unix user, group and mod are preserved.
* 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`).
These two files can be created using the `c8y_configuration_plugin --init` option:
```shell
$ sudo c8y_configuration_plugin --init
$ 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
$ 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
```
The `c8y_configuration_plugin` has to be run as a daemon on the device, the latter being connected to Cumulocity.
## 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.
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', type = 'tedge.toml' },
{ path = '/etc/tedge/mosquitto-conf/c8y-bridge.conf' },
{ path = '/etc/tedge/mosquitto-conf/tedge-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.
* 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.
## Usage
```shell
$ c8y_configuration_plugin --help
c8y_configuration_plugin 0.6.2
Thin-edge device configuration management for Cumulocity
USAGE:
c8y_configuration_plugin [OPTIONS]
OPTIONS:
--config-dir <CONFIG_DIR> [default: /etc/tedge]
--config-file <CONFIG_FILE> [default: $CONFIG_DIR/c8y/c8y-configuration-plugin.toml]
--debug Turn-on the debug log level
-h, --help Print help information
-i, --init Create supported operation files
-V, --version Print version information
On start, `c8y_configuration_plugin` notifies the cloud tenant of the managed configuration files,
listed in the `CONFIG_FILE`, sending this list with a `119` on `c8y/s/us`.
`c8y_configuration_plugin` subscribes then to `c8y/s/ds` listening for configuration operation
requests (messages `524` and `526`).
notifying the Cumulocity tenant of their progress (messages `501`, `502` and `503`).
The thin-edge `CONFIG_DIR` is used to find where:
* to store temporary files on download: `tedge config get tmp.path`,
* to connect the MQTT bus: `tedge config get mqtt.port`.
```
## Logging
The `c8y_configuration_plugin` reports progress and errors on its `stderr`.
* 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?).
## Notifications
When a configuration file is successfully downloaded from the cloud,
the `c8y_configuration_plugin` service notifies this update over MQTT.
* 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" }`.
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.
|
