Merge pull request #2970 from reubenmiller/docs-custom-domains

docs: add instructions for Cumulocity IoT custom domains

docs/src/start/connect-c8y.md

@@ -50,6 +50,25 @@ This will set the root certificate path of the Cumulocity IoT.
 In most of the Linux flavors, the certificate will be present in `/etc/ssl/certs`.
 If not found download it from [here](https://www.identrust.com/dst-root-ca-x3).
 
+### Custom domain
+
+If you are using the Cumulocity Iot [custom domain feature](https://cumulocity.com/docs/enterprise-tenant/customization/#domain-name), then you need to set two urls instead of one, as the HTTP and MQTT endpoints on custom domains are different because the custom domain only applies to the HTTP endpoint. The MQTT endpoint must point to the underlying Cumulocity IoT instance.
+
+For example, below shows setting the HTTP and MQTT endpoints:
+
+```sh
+tedge config set c8y.http "custom.example.com"
+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'
+```
+:::
+
 
 ## Connecting to Cumulocity server signed with self-signed certificate
 
@@ -134,6 +153,18 @@ sudo tedge cert upload c8y --user "[email protected]"
 
 Below shows some common errors that can be experienced when trying to upload the device certificate.
 
+#### InvalidCertificate(NotValidForName)
+
+If you receive the following error, then you are most likely using the [custom domain feature](https://cumulocity.com/docs/enterprise-tenant/customization/#domain-name), and should see the [custom domain instructions](#custom-domain) to configure the correct HTTP and MQTT endpoints.
+
+```sh
+ERROR: Custom { kind: InvalidData, error: InvalidCertificate(NotValidForName) }
+Error: failed to connect to Cumulocity cloud.
+
+Caused by:
+    Connection check failed
+```
+
 #### 401 - Unauthorized
 
 The 401 (Unauthorized) error means either the user and/or password is invalid for the configured Cumulocity IoT url that was set in the `tedge config set c8y.url <url>` command.
@@ -143,7 +174,7 @@ Check the following items to help you diagnose the root cause of the problem:
 * Check the configured `c8y.url`. Copy/paste the url into a Web Browser to validate that it does open the intended Cumulocity IoT tenant
 * Check your username. The user/email is case-sensitive, so make sure the user matches your configured Cumulocity IoT user
 * Check your password. Use copy/paste to enter your password as this eliminates typos
-* Check that you are not using a SSO user. SSO users are not permitted to use the REST API calls which the `tedge cert upload c8y` command is using. Please create a new Cumulocity IoT user via the [Administration Pge](https://cumulocity.com/guides/users-guide/administration/#to-add-a-user)
+* Check that you are not using a SSO user. SSO users are not permitted to use the REST API calls which the `tedge cert upload c8y` command is using. Please create a new Cumulocity IoT user via the [Administration Page](https://cumulocity.com/guides/users-guide/administration/#to-add-a-user)
 
 
 #### 403 - Forbidden