diff --git a/docs/src/operate/c8y/connect.md b/docs/src/operate/c8y/connect.md index 14ddcad0725..9745c084106 100644 --- a/docs/src/operate/c8y/connect.md +++ b/docs/src/operate/c8y/connect.md @@ -4,6 +4,19 @@ tags: [Operate, Cloud] description: Connecting %%te%% to Cumulocity IoT --- +import UserContext from '@site/src/components/UserContext'; +import UserContextForm from '@site/src/components/UserContextForm'; + +:::tip +#### User Context {#user-context} + +You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use %%te%%. + + + +The user context will be persisted in your web browser's local storage. +::: + To create northbound connection a local bridge shall be established and this can be achieved with `tedge` cli and following commands: :::note @@ -14,10 +27,14 @@ To create northbound connection a local bridge shall be established and this can Configure required parameters for %%te%% with [`tedge config set`](../../references/cli/tedge-config.md): + + ```sh -sudo tedge config set c8y.url example.cumulocity.com +sudo tedge config set c8y.url $C8Y_URL ``` + + :::info If you are unsure which parameters required by the command, simply run the command and it will tell you which parameters are missing. @@ -54,13 +71,13 @@ and the command will prompt you for this user's password. These credentials are used only for this upload and will in no case be stored on the device. ::: + + ```sh -sudo tedge cert upload c8y --user "${C8Y_USER}" +sudo tedge cert upload c8y --user "$C8Y_USER" ``` -```sh title="Example" -sudo tedge cert upload c8y --user "john.smith@example.com" -``` + ## Creating an MQTT bridge between the device and the cloud diff --git a/docs/src/start/connect-aws.md b/docs/src/start/connect-aws.md index ea1b1a6627d..e973cd818a2 100644 --- a/docs/src/start/connect-aws.md +++ b/docs/src/start/connect-aws.md @@ -5,6 +5,21 @@ sidebar_position: 4 description: Connect %%te%% to AWS IoT and publish telemetry data --- +import UserContext from '@site/src/components/UserContext'; +import UserContextForm from '@site/src/components/UserContextForm'; + +:::tip +#### User Context {#user-context} + +You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use %%te%%. + + + +The user context will be persisted in your web browser's local storage. +::: + +### Overview + The very first step to enable %%te%% is to connect your device to the cloud. * This is a 10 minutes operation to be done only once. @@ -23,7 +38,7 @@ Before you try to connect your device to AWS IoT, you need: You can now use [`tedge` command](../references/cli/index.md) to: * [create a certificate for your device](#create-certificate), -* [register the device on AWS IoT Hub](#register), +* [register the device on AWS IoT Core](#register), * [configure the device](#configure), * [connect the device](#connect), and * [send your first telemetry data](#send). @@ -37,10 +52,15 @@ This identifier will be used to uniquely identify your devices among others in y This identifier will be also used as the Common Name (CN) of the certificate. Indeed, this certificate aims to authenticate that this device is the device with that identity. + + + ```sh -sudo tedge cert create --device-id my-device +sudo tedge cert create --device-id $DEVICE_ID ``` + + ## Show certificate details You can then check the content of that certificate. @@ -49,83 +69,180 @@ You can then check the content of that certificate. sudo tedge cert show ``` + + ```text title="Output" Device certificate: /etc/tedge/device-certs/tedge-certificate.pem -Subject: CN=my-device, O=Thin Edge, OU=Test Device -Issuer: CN=my-device, O=Thin Edge, OU=Test Device +Subject: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device +Issuer: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device Valid from: Tue, 09 Mar 2021 14:10:30 +0000 Valid up to: Thu, 10 Mar 2022 14:10:30 +0000 Thumbprint: 860218AD0A996004449521E2713C28F67B5EA580 ``` + + You may notice that the issuer of this certificate is the device itself. This is a self-signed certificate. To use a certificate signed by your Certificate Authority, see the reference guide of [`tedge cert`](../references/cli/tedge-cert.md). -## Register the device on AWS IoT Hub {#register} +## Register the device on AWS IoT Core {#register} For a device to be trusted by AWS, one needs a device certificate and the `tedge cert create` command is the simplest way to get one. Also a policy needs to be attached to the device certificate in AWS IoT Core. AWS IoT Core policies determine what an authenticated identity can do (here the authenticated identity is the device being connected). More info on AWS IoT Core policies can be found [here](https://docs.aws.amazon.com/iot/latest/developerguide/iot-policies.html). -To create a new policy, head over to the AWS IoT Core and navigate to +### Create new policy -**Security → Policies → Create policy → Policy properties → Policy name → Enter the name of your policy (e.g.tedge)** +Before you can register any devices, you must create a policy which can be assigned to each new device during the registration process. The policy grants permissions to the devices to be able to write to specific MQTT topics. -On the Policy statements tab click on ***JSON*** and enter the policy in the ***Policy document*** (an example policy can be found [here](https://raw.githubusercontent.com/thin-edge/thin-edge.io/main/docs/src/start/aws-example-policy.json)) then click ***Create***. +1. Open your AWS IoT Core -In the AWS IoT Core, navigate to ***Manage → All devices → Things → Create things → Create Single thing → Next***. Enter the Thing name which can be obtained from the device with the output of the following command: +2. Navigate to the Policies section under **Security** → **Policies** -```sh -tedge config get device.id -``` +3. Click **Create policy**, and enter a policy name (e.g. `thin-edge.io`) + +4. Under the **Policy statements** tab click on ***JSON*** and add the following JSON: + + :::tip + If you haven't provided the [User Context](#user-context) then it is strongly encouraged to do so, as the following snippet will be updated to reflect your AWS IoT Core settings. + ::: + + + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": "iot:Connect", + "Resource": "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:client/${iot:Connection.Thing.ThingName}" + }, + { + "Effect": "Allow", + "Action": "iot:Subscribe", + "Resource": [ + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topicfilter/thinedge/${iot:Connection.Thing.ThingName}/cmd/#", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/#", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topicfilter/thinedge/devices/${iot:Connection.Thing.ThingName}/test-connection" + ] + }, + { + "Effect": "Allow", + "Action": "iot:Receive", + "Resource": [ + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/cmd", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/cmd/*", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/devices/${iot:Connection.Thing.ThingName}/test-connection" + ] + }, + { + "Effect": "Allow", + "Action": "iot:Publish", + "Resource": [ + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/td", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/${iot:Connection.Thing.ThingName}/td/*", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*", + "arn:aws:iot:$AWS_REGION:$AWS_ACCOUNT_ID:topic/thinedge/devices/${iot:Connection.Thing.ThingName}/test-connection" + ] + } + ] + } + ``` + + + + :::info + A static form of the example policy can be downloaded from the [repository](https://raw.githubusercontent.com/thin-edge/thin-edge.io/main/docs/src/start/aws-example-policy.json), though you will need to replace the `` and `` placeholders with your AWS IoT Core values. + ::: + +4. Click **Create** -In the Device Shadow section which allows connected devices to sync states with AWS choose ***Unnamed shadow (classic)*** and click ***Next*** and ***Configure device certificate - optional*** page opens. +### Registering a Device (thing) -At ***Device certificate*** choose ***Use my certificate → CA is not registered with AWS IoT*** then ***Choose file*** and select your tedge-certificate.pem file, click on ***Open → Next***. +1. Open the AWS IoT Core page -The last step needed is to attach previously created policy to your certificate, **Attach policies to certificate -optional** → Select your created policy **→ Create thing**. +2. Navigate to **Manage** → **All devices** → **Things** + +3. Click **Create things**, select the **Create single thing** option, then click **Next** + +4. Enter the device name (e.g. Thing name) + + + + ``` + $DEVICE_ID + ``` + + + + :::tip + The thing name must match the device certificate's Common Name. If you are unsure what the value is, then you can check the common name of the device by using the following `tedge` command: + + ```sh + tedge config get device.id + ``` + ::: + +4. Select the ***Unnamed shadow (classic)*** option and click ***Next*** + +5. On the ***Device certificate*** page, choose ***Use my certificate → CA is not registered with AWS IoT*** + +6. ***Choose file*** and select your `tedge-certificate.pem` file, click on ***Open → Next*** + + If you haven't previously downloaded the public device certificate, you can print the contents (don't worry this is not sensitive information), and then you can save the certificate's contents to a file on your computer so it can be uploaded to AWS. + + You can print the public certificate to the console using the following command: + + ```sh + cat /etc/tedge/device-certs/tedge-certificate.pem + ``` + +7. On the **Policies** page, select the previously created policy, e.g. `thin-edge.io`, then click **Create thing** ## Configure the device {#configure} -To connect the device to the AWS IoT Hub, one needs to set the URL of the IoT Hub and the root certificate of the IoT +To connect the device to the AWS IoT Core, one needs to set the URL of the IoT Hub and the root certificate of the IoT Hub as below. -Set the URL of your AWS IoT Hub. +Set the URL of your AWS IoT Core. + + ```sh -sudo tedge config set aws.url "${AWS_URL}" +sudo tedge config set aws.url "$AWS_URL" ``` -```sh title="Example" -sudo tedge config set aws.url "a2e8ahbpo21syc.iot.eu-central-1.amazonaws.com" -``` + The URL is unique to the AWS account and region that is used, and can be found in the AWS IoT Core by navigating to -"Settings". It will be listed under "Device data endpoint" (e.g. `a2e8ahbpo21syc.iot.eu-central-1.amazonaws.com`) +**Settings**. It will be listed under **Device data endpoint**. -Set the path to the root certificate if necessary. The default is `/etc/ssl/certs`. -```sh -sudo tedge config set aws.root_cert_path /etc/ssl/certs/AmazonRootCA1.pem -``` +:::note +The Amazon's public root certificate for your region's AWS IoT Core needs to be present in your ca-certificate store for the communication to the cloud to be trusted. -This will set the root certificate path of the AWS IoT Hub. In most of the Linux flavors, the certificate will be -present in /etc/ssl/certs. If not found download it from -[here](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs). +In most of the Linux flavors, the certificate will be present in `/etc/ssl/certs` directory. If the certificate is not present, then you can download it manually from +[Amazon](https://docs.aws.amazon.com/iot/latest/developerguide/server-authentication.html#server-authentication-certs) and add it to your system's ca-certificate store by following the +[Adding a root certificate](../operate/security/cloud-authentication.md#adding-a-root-certificate) documentation. +::: ## Connect the device {#connect} -Now, you are ready to get your device connected to AWS IoT Hub with `tedge connect aws`. +Now, you are ready to get your device connected to AWS IoT Core with `tedge connect aws`. This command configures the MQTT broker: * to establish a permanent and secure connection to the AWS cloud, * to forward local messages to the cloud and vice versa. Also, if you have installed `tedge-mapper`, this command starts and enables the tedge-mapper-aws systemd service. -At last, it sends packets to AWS IoT Hub to check the connection. +At last, it sends packets to AWS IoT Core to check the connection. ```sh sudo tedge connect aws @@ -198,6 +315,15 @@ tedge-mapper-aws service successfully started and enabled! ``` +:::tip +If you having troubles with the connection, then check the following items: + +* Check that the policy is attached to the device's certificate +* Check that the policy includes your AWS IoT Core's region and account id +* Check [Amazon diagnosing connectivity issues](https://docs.aws.amazon.com/iot/latest/developerguide/diagnosing-connectivity-issues.html) documentation for further debugging steps +* Check the mosquitto logs for errors, e.g. "verify" errors would indicate that you are missing Amazon's root certificate in the ca-certificate store +::: + ## Sending your first telemetry data {#send} Using the AWS mapper, you can publish measurement telemetry data to AWS by publishing on the `te/device/main///m/` topic: diff --git a/docs/src/start/connect-azure.md b/docs/src/start/connect-azure.md index fe0a3d73bd8..9d3c2222440 100644 --- a/docs/src/start/connect-azure.md +++ b/docs/src/start/connect-azure.md @@ -5,6 +5,19 @@ sidebar_position: 3 description: Connect %%te%% to Azure IoT and publish telemetry data --- +import UserContext from '@site/src/components/UserContext'; +import UserContextForm from '@site/src/components/UserContextForm'; + +:::tip +#### User Context {#user-context} + +You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use %%te%%. + + + +The user context will be persisted in your web browser's local storage. +::: + The very first step to enable %%te%% is to connect your device to the cloud. * This is a 10 minutes operation to be done only once. * It establishes a permanent connection from your device to the cloud end-point. @@ -35,10 +48,14 @@ This identifier will be used to uniquely identify your devices among others in y This identifier will be also used as the Common Name (CN) of the certificate. Indeed, this certificate aims to authenticate that this device is the device with that identity. + + ```sh -sudo tedge cert create --device-id my-device +sudo tedge cert create --device-id "$DEVICE_ID" ``` + + ```text title="Output" Certificate was successfully created ``` @@ -51,15 +68,19 @@ You can then check the content of that certificate. sudo tedge cert show ``` + + ```text title="Output" Device certificate: /etc/tedge/device-certs/tedge-certificate.pem -Subject: CN=my-device, O=Thin Edge, OU=Test Device -Issuer: CN=my-device, O=Thin Edge, OU=Test Device +Subject: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device +Issuer: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device Valid from: Tue, 09 Mar 2021 14:10:30 +0000 Valid up to: Thu, 10 Mar 2022 14:10:30 +0000 Thumbprint: 860218AD0A996004449521E2713C28F67B5EA580 ``` + + You may notice that the issuer of this certificate is the device itself. This is a self-signed certificate. The Thumbprint is the Sha1sum of the certificate. This is required for registering the @@ -90,10 +111,14 @@ To connect the device to the Azure IoT Hub, one needs to set the URL/Hostname of Set the URL/Hostname of your Azure IoT Hub. + + ```sh -sudo tedge config set az.url your-iot-hub-name.azure-devices.net +sudo tedge config set az.url $AZURE_URL ``` + + The URL/Hostname can be found in the Azure web portal, clicking on the overview section of your IoT Hub. Set the path to the root certificate if necessary. The default is `/etc/ssl/certs`. diff --git a/docs/src/start/connect-c8y.md b/docs/src/start/connect-c8y.md index 4ef93d822f6..d8903b8ccf5 100644 --- a/docs/src/start/connect-c8y.md +++ b/docs/src/start/connect-c8y.md @@ -5,6 +5,19 @@ sidebar_position: 2 description: Connect %%te%% to Cumulocity IoT and publish telemetry data --- +import UserContext from '@site/src/components/UserContext'; +import UserContextForm from '@site/src/components/UserContextForm'; + +:::tip +#### User Context {#user-context} + +You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use %%te%%. + + + +The user context will be persisted in your web browser's local storage. +::: + The very first step to enable %%te%% is to connect your device to the cloud. * This is a 10 minutes operation to be done only once. * It establishes a permanent connection from your device to the cloud end-point. @@ -36,10 +49,14 @@ To connect the device to the Cumulocity IoT, one needs to set the URL of your Cu Set the URL of your Cumulocity IoT tenant. + + ```sh -sudo tedge config set c8y.url your-tenant.cumulocity.com +sudo tedge config set c8y.url $C8Y_URL ``` + + Set the path to the root certificate if necessary. The default is `/etc/ssl/certs`. ```sh @@ -56,17 +73,25 @@ If you are using the Cumulocity Iot [custom domain feature](https://cumulocity.c For example, below shows setting the HTTP and MQTT endpoints: + + ```sh -tedge config set c8y.http "custom.example.com" +tedge config set c8y.http "$C8Y_URL" tedge config set c8y.mqtt "t12345.cumulocity.com:8883" ``` + + :::tip If you have `curl` and `jq` installed, then you can check if you are using a custom domain by executing the following command. If the response includes a different domain than the url used in the curl command, then you are using a custom domain, and you should use the output to set the `c8y.mqtt` thin-edge.io setting instead. + + ```sh -curl custom.example.com/tenant/loginOptions | jq -r '.loginOptions[] | select(.loginRedirectDomain) | .loginRedirectDomain' +curl -sfL https://$C8Y_URL/tenant/loginOptions | jq -r '.loginOptions[] | select(.loginRedirectDomain) | .loginRedirectDomain' ``` + + ::: @@ -84,13 +109,17 @@ This is the certificate chain of the server and not the device's certificate kep ::: If the Cumulocity server's certificate chain file isn't available locally, it can be downloaded using a web browser or using some other -third-party tools like openssl command as follows (to be adjusted based on your env): +third-party tools like openssl command as follows: + + ```sh -openssl s_client -connect : < /dev/null 2>/dev/null \ +openssl s_client -connect $C8Y_URL:443 < /dev/null 2>/dev/null \ | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' ``` + + ## Create the certificate The `tedge cert create` command creates a self-signed certificate which can be used for testing purpose. @@ -100,10 +129,14 @@ This identifier will be used to uniquely identify your devices among others in y This identifier will be also used as the Common Name (CN) of the certificate. Indeed, this certificate aims to authenticate that this device is actually the device with that identity. + + ```sh -sudo tedge cert create --device-id my-device +sudo tedge cert create --device-id "$DEVICE_ID" ``` + + ```text title="Output" Certificate was successfully created ``` @@ -114,15 +147,19 @@ You can then check the content of that certificate. sudo tedge cert show ``` + + ```text title="Output" Device certificate: /etc/tedge/device-certs/tedge-certificate.pem -Subject: CN=my-device, O=Thin Edge, OU=Test Device -Issuer: CN=my-device, O=Thin Edge, OU=Test Device +Subject: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device +Issuer: CN=$DEVICE_ID, O=Thin Edge, OU=Test Device Valid from: Tue, 09 Feb 2021 17:16:52 +0000 Valid up to: Tue, 11 May 2021 17:16:52 +0000 Thumbprint: CDBF4EC17AA02829CAC4E4C86ABB82B0FE423D3E ``` + + You may notice that the issuer of this certificate is the device itself. This is a self-signed certificate. To use a certificate signed by your Certificate Authority, @@ -141,13 +178,13 @@ This can be done: to your tenant "Device Management/Management/Trusted certificates". * or using the `tedge cert upload c8y` command. + + ```sh -sudo tedge cert upload c8y --user "${C8Y_USER}" +sudo tedge cert upload c8y --user "$C8Y_USER" ``` -```sh title="Example" -sudo tedge cert upload c8y --user "john.smith@example.com" -``` + ### Common errors diff --git a/docs/src/start/getting-started.md b/docs/src/start/getting-started.md index e8645ade0f8..a0642bb40c1 100644 --- a/docs/src/start/getting-started.md +++ b/docs/src/start/getting-started.md @@ -4,6 +4,19 @@ tags: [Getting Started, Cumulocity] sidebar_position: 1 --- +import UserContext from '@site/src/components/UserContext'; +import UserContextForm from '@site/src/components/UserContextForm'; + +:::tip +#### User Context {#user-context} + +You can customize the documentation and commands shown on this page by providing relevant settings which will be reflected in the instructions. It makes it even easier to explore and use %%te%%. + + + +The user context will be persisted in your web browser's local storage. +::: + After following this tutorial you will have an overview of the installation and configuration of %%te%%. As an example, a Raspberry Pi is used. This tutorial explains in small steps to reach the goal of sending data to Cumulocity IoT and performing some additional device management tasks. @@ -107,13 +120,13 @@ To connect the device to the Cumulocity IoT it needs to be configured. This URL is needed to allow the upload of the certificate to the specific tenant and the registration of the device. It can be configured via: + + ```sh -sudo tedge config set c8y.url "${YOUR_C8Y_URL}" +sudo tedge config set c8y.url "$C8Y_URL" ``` -```sh title="Example" -sudo tedge config set c8y.url "mycompany.cumulocity.com" -``` + ### Certificate @@ -121,26 +134,25 @@ sudo tedge config set c8y.url "mycompany.cumulocity.com" First, we need to create the device certificate locally (If the device certificate is already uploaded, directly via the UI to Cumulocity IoT this step can be skipped). + + ```sh -sudo tedge cert create --device-id "${DEVICE_ID}" +sudo tedge cert create --device-id "$DEVICE_ID" ``` -```sh title="Example" -export DEVICE_ID="gateway_4932C0CE7D12" -sudo tedge cert create --device-id "${DEVICE_ID}" -``` + The device id is a unique identifier e.g. the MAC address that identifies the physical device. The certificate is uploaded to the Cumulocity IoT Tenant via: + + ```sh -sudo tedge cert upload c8y --user "${C8Y_USER}" +sudo tedge cert upload c8y --user "$C8Y_USER" ``` -```sh title="Example" -sudo tedge cert upload c8y --user "john.smith@example.com" -``` + If the password prompt appears, enter your password. @@ -320,8 +332,7 @@ The APT plugin (provided by the `tedge-apt-plugin` package) is installed by defa ```sh -sudo tedge disconnect c8y -sudo tedge connect c8y +sudo tedge reconnect c8y ``` ### Adding new software into the software repository in Cumulocity IoT