Mistake on this page? Email us

Network configuration

Domains

Your devices need to have access to the following domain hosts:

Location Service Domain host
United States CoAP/bootstrap bootstrap.us-east-1.mbedcloud.com
United States Edge container registry containers.us-east-1.mbedcloud.com
United States Edge gateway https://gateways.us-east-1.mbedcloud.com and https://edge-k8s.us-east-1.mbedcloud.com
United States mDS (legacy) coaps://lwm2m.us-east-1.mbedcloud.com
United States mDS (for UDP) coaps://udp-lwm2m.us-east-1.mbedcloud.com
United States mDS (for TPC) coaps://tcp-lwm2m.us-east-1.mbedcloud.com

For firewall rules we recommend you open *.mbedcloud.com -domain for future proofness.

To reach these URLs, the devices need to resolve DNS queries. You therefore need to deploy a DNS server in the network or locally, and make it accessible to the devices (usually over port 53).

If you are using a Snap-based Edge distribution you will in addition also need Canonical's services to be accessible. Please read Snapcraft.io documentation for those.

Notes:

  • Devices use port 5684 (UDP or TCP) to communicate with Device Management.
  • Snap-Edge and Distro-Edge devices may use port 443 (HTTPS) instead of 5684 (or both) depending on the configuration.
  • The traffic must be untampered, see intrusive firewalls.
  • The IPs of the Device Management hosts can change. Therefore, you need to make sure your DNS server does not cache records for longer than their time to live (TTL).

Connecting devices behind NAT

If your devices are behind a NAT, we recommend using either CoAP over TCP; or, if you require UDP, a dedicated tunnel between your device gateway and Device Management.

Intrusive firewalls

Firewalls that perform TLS inspection act as a man-in-the-middle attack. This is blocked by secure transport protocols such as TLS, DTLS and HTTPS. You can spot such a firewall being in place with a simple test:

openssl s_client -connect bootstrap.us-east-1.mbedcloud.com:5684

Confirm the signing certificate is issued by:

issuer=C = GB, ST = Cambridgeshire, L = Cambridge, O = ARM Ltd, CN = ARM Bootstrap CA

If the issuer is not matching or you get a forbidden/blocked error you need to get your device whitelisted by the network owner for untampered traffic for the IP-addresses listed above.

Note: OpenSSL will report certificate check failures, but these are expected. This is due to CoAP based services NOT sending full certificate chains in order to save bandwidth and memory on constrained devices.

If you want to avoid the certificate check failure, you need to download the Izuma Device Management certificates. Use additional argument --cafile <file> with openssl to provide the location of the certificate file.

CoAP over TCP

If your devices are behind NAT or have IPv4 addresses, we recommend using CoAP over TCP because CoAP provides sustained connectivity between client and server, which helps overcome NAT firewall challenges.

You should also consider the power consumption tradeoffs between keeping the connection alive and requiring the device to re-establish the connection to communicate with Device Management when needed, which will also require it to go through the registration process.

There are two ways to keep the connection alive:

At the TCP level, different network operators typically have much shorter keepalive intervals than the devices; if your device's default keepalive intervals are longer than the network timeouts, you can configure them from Device Management Client. Device Management Client uses CoAP PING to provide uniform functionality for maintaining TCP connectivity. CoAP PING sends a periodic Reset Message to maintain the TLS connection. Device Management Client uses the default value of 540 seconds for keepalive.

You can change this on the application side using the MBED_CLIENT_TCP_KEEPALIVE_INTERVAL definition.

For example, with the Device Management Client reference example, there are two recommended ways to define these parameters.

  • Primarily, using the mbed_cloud_client_user_config.h file:

    #define MBED_CLIENT_TCP_KEEPALIVE_INTERVAL   540
    
  • Alternatively (works only for Mbed OS), you can specify these parameters in the application mbed_app.json:

    "mbed-client.tcp-keepalive-interval": 540
    

Note: Do not define the parameters in both mbed_cloud_client_user_config.h and mbed_app.json as this will result in duplicate definitions.