Skip to content
Snippets Groups Projects
Commit e6c9bf08 authored by Ryan Gonzalez's avatar Ryan Gonzalez Committed by Detlev Casanova
Browse files

configure_c2e_on_iot: Describe how to connect to our cloud2edge 

This also changes the configuration to be in config.json instead of
provisioning.json, mostly just because the former is what the tests
actually use in practice. In addition, the tenant ID is assumed to be
`dev.apertis`, which has already been set up with the Hono<->Ditto
connection.

https://phabricator.apertis.org/T8946



Signed-off-by: default avatarRyan Gonzalez <ryan.gonzalez@collabora.com>
parent faf82b2c
No related branches found
No related tags found
1 merge request!500configure_c2e_on_iot: Describe how to connect to our cloud2edge
Pipeline #427768 passed with warnings
Stage: test
Stage: generate-html
Stage: generate-pdf
Stage: test-urls
Stage: deploy
Hide whitespace changes
Inline Side-by-side
content/guides/configure_c2e_on_iot.md 0 → 100644
+ 166
− 0
View file @ e6c9bf08
+++
date = "2022-10-11"
weight = 100
title = "Configure IoT images to connect to cloud2edge"
+++
Apertis maintains an instance of [Eclipse cloud2edge](https://www.eclipse.org/packages/packages/cloud2edge/) that can be used to test the IoT images using Eclipse Kanto. The following sections describe how to set up the IoT image's suite-connector configuration to be able to connect to this instance.
The following sections describe how to set the IoT image's suite-connector configuration.
# Required Information
Various stub values will be seen throughout the commands in this document that will need to be replaced. Any command that needs some values inside to be replaced will have those listed in the paragraph preceding the command.
The following variables need to be set to the credentials used to connect to the Apertis cloud2edge instance (these credentials are **not** publicly available, [contact the Apertis team](https://www.apertis.org/policies/community/) to request access):
- `$HONO_REGISTRY_USERNAME`, `$HONO_REGISTRY_PASSWORD`: The username and password for Hono's device registry.
- `$DITTO_USERNAME`, `$DITTO_PASSWORD`: The username and password for Ditto.
The following variables need to be set to unique values for each individual device registration:
- `$DEVICE_ID`: The identifier for the device, in the format `NAMESPACE:NAME`, where `NAMESPACE` is some unique identifying namespace for the device. In order to avoid conflicts, you are advised to use a non-trivial, hard-unique device identifier.
- `$AUTH_ID`: The device's authentication identifier (essentially a username) used to connect to Hono. This value is specific to a device and need not be globally unique, but for simplicity, feel free to reuse the device ID (note that `:` is not valid here and should be replaced with another character, such as `_`).
- `$PASSWORD`: The device's password used to connect to Hono. This should be a reasonably long, secure password, preferably generated via a [secure password generation tool](https://bitwarden.com/password-generator/).
# Device Registration
Registration is typically done outside of the IoT device.
You can register a new device `$DEVICE_ID` via the following command (set `$HONO_REGISTRY_USERNAME`, `$HONO_REGISTRY_PASSWORD`, and `$DEVICE_ID`):
```bash
$ curl -X POST -u "$HONO_REGISTRY_USERNAME:$HONO_REGISTRY_PASSWORD" "https://hono-registry.apertis.dev/v1/devices/dev.apertis/$DEVICE_ID"
```
After this, login credentials can be assigned to the device (set `$HONO_REGISTRY_USERNAME`, `$HONO_REGISTRY_PASSWORD`, `$DEVICE_ID`, `$AUTH_ID`, and `$PASSWORD`):
```bash
$ curl -X PUT -u "$HONO_REGISTRY_USERNAME:$HONO_REGISTRY_PASSWORD" -H 'Content-Type: application/json' -d@- "https://hono-registry.apertis.dev/v1/credentials/dev.apertis/$DEVICE_ID" <<EOF
[
{
"type": "hashed-password",
"auth-id": "$AUTH_ID",
"secrets": [
{
"pwd-plain": "$PASSWORD"
}
]
}
]
EOF
```
Next, an Eclipse Ditto thing [digital twin](https://www.eclipse.org/ditto/intro-digitaltwins.html) should be created for the device (set `$DITTO_USERNAME`, `$DITTO_PASSWORD`, and `$DEVICE_ID`):
```bash
$ curl -X PUT -u "$DITTO_USERNAME:$DITTO_PASSWORD" -H 'Content-Type: application/json' -d@- "https://ditto.apertis.dev/api/2/things/$DEVICE_ID" <<EOF
{
"_policy": {
"entries": {
"DEFAULT": {
"subjects": {
"nginx:ditto": {
"type": "Ditto user authenticated via nginx"
}
},
"resources": {
"thing:/": {
"grant": ["READ", "WRITE"],
"revoke": []
},
"policy:/": {
"grant": ["READ", "WRITE"],
"revoke": []
},
"message:/": {
"grant": ["READ", "WRITE"],
"revoke": []
}
}
},
"HONO": {
"subjects": {
"pre-authenticated:hono-connection": {
"type": "Connection to Eclipse Hono"
}
},
"resources": {
"thing:/": {
"grant": ["READ", "WRITE"],
"revoke": []
},
"message:/": {
"grant": ["READ", "WRITE"],
"revoke": []
}
}
}
}
},
"attributes": {
"location": "Germany"
},
"features": {
"temperature": {
"properties": {
"value": null
}
},
"humidity": {
"properties": {
"value": null
}
}
}
}
EOF
```
In this example, digital twin is registered with the attributes `location: Germany` and the `temperature` and `humidity` features. (Note that the `_policy` section should remain untouched!)
Once your device is registered, you are ready to configure the IoT image on the device.
# Configure the IoT Image
The configuration to connect to the server needs to be written in the `/etc/suite-connector/config.json` file and can be created via the following command (set `$DEVICE_ID`, `$AUTH_ID`, and `$PASSWORD`):
```bash
$ sudo tee /etc/suite-connector/config.json >/dev/null <<EOF
{
"cacert": "/etc/suite-connector/apertis.crt",
"logFile": "/var/log/suite-connector/suite-connector.log",
"address": "mqtts://hono.apertis.dev:8883",
"tenantId": "dev.apertis",
"deviceId": "$DEVICE_ID",
"authId": "$AUTH_ID",
"password": "$PASSWORD"
}
EOF
```
This setup assumes the SSL certificate for Apertis's cloud2edge is located at `/etc/suite-connector/apertis.crt`. In order to obtain it, run:
```bash
$ openssl s_client -connect hono.apertis.dev:443 -showcerts </dev/null \
| openssl x509 -outform PEM \
| sudo tee /etc/suite-connector/apertis.crt >/dev/null
```
## Starting the Service
The `suite-connector` service can now be enabled and started with:
```bash
$ sudo systemctl enable --now suite-connector.service
```
# Device Deletion
After you're done with a device, you can delete it and its digital twin via the following commands:
```bash
$ curl -X DELETE -u "$DITTO_USERNAME:$DITTO_PASSWORD" "https://ditto.apertis.dev/api/2/things/$DEVICE_ID"
$ curl -X DELETE -u "$HONO_REGISTRY_USERNAME:$HONO_REGISTRY_PASSWORD" "https://hono-registry.apertis.dev/v1/devices/dev.apertis/$DEVICE_ID"
```
content/guides/configure_hono_on_iot.md deleted 100644 → 0
+ 0
− 110
View file @ faf82b2c
+++
date = "2022-07-20"
weight = 100
title = "Configure IoT images to connect to Hono"
+++
The Eclipse project provides a publicly available Hono sandbox that can be used to test IoT devices that will use Kanto.
To connect to the Eclipse Hono sandbox, the device and user account must be registered.
Then, the IoT image's suite-connector configuration must be adapted to use the correct parameters.
The following sections describe how to set it all up.
# Hono Registration
Registration is done from a desktop, not from the IoT device.
Eclipse provides [a guide](https://www.eclipse.org/kanto/docs/getting-started/hono/) on how to use the Hono sandbox.
It can be followed up to the [Provision the Eclipse Hono tenant and device](https://www.eclipse.org/kanto/docs/getting-started/hono/#provision-the-eclipse-hono-tenant-and-device) section.
In order to minimize the risk of collisions of device identities and credentials and to reduce the risk of others guessing your identifiers, you are advised to use non-trivial, hard-to-guess tenant and device identifiers (e.g. a UUID).
Eclipse lists [other recommendations on using the Hono sandbox](https://www.eclipse.org/hono/sandbox/).
Once your device is registered, you are ready to configure the IoT image on the device.
# Configure the IoT Image
The configuration of the provisioning needs to be written in the `/etc/suite-connector/provisioning.json` file.
Here is an example for the provisioning configuration to connect to the Hono sandbox:
```
{
"id": "hono-sandbox",
"hub": {
"credentials": {
"tenantId": "[TENANT]",
"type": "hashed-password",
"enabled": true,
"secrets": [
{
"passwordBase64": "[BASE64_PASSWORD]"
}
],
"deviceId": "[DEVICE_ID]",
"authId": "[AUTH_ID]",
"adapters": [
{
"type": "mqtt",
"uri": "tcp://hono.eclipseprojects.io",
"host": "hono.eclipseprojects.io",
"port": 1883
}
]
},
"device": {
"enabled": true,
"deviceId": "[DEVICE_ID]"
}
},
"things": {
"thing": {
"attributes": {
"Info": {
"displayName": "cli",
"gateway": false
}
},
"thingId": "[DEVICE_ID]",
"policyId": "policy"
}
}
}
```
Once the file is created, change the following values:
- `[TENANT]`: The Hono tenant that has been created in the previous section.
- `[BASE64_PASSWORD]`: The Hono password that has been used in the previous section. The password must be encoded in base64. It can be obtain by running `echo -n [PASSWORD] | base64`. \*
- `[DEVICE_ID]`: The identifier of the device on the tenant created in the previous section (Note that is has to be set at 3 places).
- `[AUTH_ID]`: The authentication identifier of the device created in the previous section.
The file can now be saved.
Before starting the `suite-connector` service, check the following section about limitations.
\*: Note that a base64 encoding is not a hash (`base64 -d` will decode the encoded value into the password) and is mainly used here to prevent human eyes to get the password with a simple glimpse at the encoded value.
## Limitations
### No SSL
For this `demo`, no SSL is used. Beware that your Hono password might be sent over the internet without encryption.
### CA Certificate
The current version of the suite-connector program [requires a CA Certificate to be present and valid](https://github.com/eclipse-kanto/suite-connector/issues/34).
A basic certificate is provided in `/etc/suite-connector/iothub.crt` but does not do anything for now.
If you want to, you can generate a dummy `iothub.crt` file in `/etc/suite-connector/`.
To generate it, you can run:
openssl genrsa -out ca.key 2048
sudo openssl req -new -x509 -days 1826 -key ca.key -out /etc/suite-connector/iothub.crt
## Starting the Service
The `suite-connector` service can now be started with:
systemctl start suite-connector.service
content/policies/images.md
+ 3
− 3
View file @ e6c9bf08
......@@ -81,8 +81,8 @@ provides the Kanto suite-connector utility.
A basic configuration is provided to be able to use the image on an IoT device
that uses Kanto.
To configure the image to connect to an Eclipse Hono sandbox, follow [these
instructions]({{< ref "/configure_hono_on_iot.md" >}}).
To configure the image to connect to the Apertis cloud2edge instance, follow
[these instructions]({{< ref "/configure_c2e_on_iot.md" >}}).
Currently, IoT images are only APT-based images, for development purpose.
......@@ -160,7 +160,7 @@ The release includes artifacts for network booting using the TFTP and NFS protoc
* initrd with kernel modules matching the image to be loaded via TFTP
* DTBs (compiled device trees) for the reference hardware platforms to be loaded via TFTP
* rootfs tarball to be loaded via NFS
# Supported Artifacts
Here's a basic overview of the architectures and update mechanisms supported by
......
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
Apertis Website Terms of Use Privacy Policy