Configure an IoT Edge device to communicate through a proxy server

Článok
02/05/2024

Applies to: IoT Edge 1.5 IoT Edge 1.4

Important

IoT Edge 1.5 LTS and IoT Edge 1.4 LTS are supported releases. IoT Edge 1.4 LTS is end of life on November 12, 2024. If you are on an earlier release, see Update IoT Edge.

IoT Edge devices send HTTPS requests to communicate with IoT Hub. If you connected your device to a network that uses a proxy server, you need to configure the IoT Edge runtime to communicate through the server. Proxy servers can also affect individual IoT Edge modules if they make HTTP or HTTPS requests that you haven't routed through the IoT Edge hub.

This article walks through the following four steps to configure and then manage an IoT Edge device behind a proxy server:

Install the IoT Edge runtime on your device

The IoT Edge installation scripts pull packages and files from the internet, so your device needs to communicate through the proxy server to make those requests. For Windows devices, the installation script also provides an offline installation option.

This step is a one-time process to configure the IoT Edge device when you first set it up. You also need these same connections when you update the IoT Edge runtime.
Configure IoT Edge and the container runtime on your device

IoT Edge is responsible for communications with IoT Hub. The container runtime is responsible for container management, so communicates with container registries. Both of these components need to make web requests through the proxy server.

This step is a one-time process to configure the IoT Edge device when you first set it up.
Configure the IoT Edge agent properties in the config file on your device

The IoT Edge daemon starts the edgeAgent module initially. Then, the edgeAgent module retrieves the deployment manifest from IoT Hub and starts all the other modules. Configure the edgeAgent module environment variables manually on the device itself, so that the IoT Edge agent can make the initial connection to IoT Hub. After the initial connection, you can configure the edgeAgent module remotely.

This step is a one-time process to configure the IoT Edge device when you first set it up.
For all future module deployments, set environment variables for any module communicating through the proxy

Once you set up and connect an IoT Edge device to IoT Hub through the proxy server, you need to maintain the connection in all future module deployments.

This step is an ongoing process done remotely so that every new module or deployment update maintains the device's ability to communicate through the proxy server.

Know your proxy URL

Before you begin any of the steps in this article, you need to know your proxy URL.

Proxy URLs take the following format: protocol://proxy_host:proxy_port.

The protocol is either HTTP or HTTPS. The Docker daemon can use either protocol, depending on your container registry settings, but the IoT Edge daemon and runtime containers should always use HTTP to connect to the proxy.
The proxy_host is an address for the proxy server. If your proxy server requires authentication, you can provide your credentials as part of the proxy host with the following format: user:password@proxy_host.
The proxy_port is the network port at which the proxy responds to network traffic.

Install IoT Edge through a proxy

Whether your IoT Edge device runs on Windows or Linux, you need to access the installation packages through the proxy server. Depending on your operating system, follow the steps to install the IoT Edge runtime through a proxy server.

Linux devices

If you're installing the IoT Edge runtime on a Linux device, configure the package manager to go through your proxy server to access the installation package. For example, Set up apt-get to use a http-proxy. Once you configure your package manager, follow the instructions in Install Azure IoT Edge runtime as usual.

Windows devices using IoT Edge for Linux on Windows

If you're installing the IoT Edge runtime using IoT Edge for Linux on Windows, IoT Edge is installed by default on your Linux virtual machine. You're not required to install or update any other steps.

Windows devices using Windows containers

If you're installing the IoT Edge runtime on a Windows device, you need to go through the proxy server twice. The first connection downloads the installer script file, and the second connection is during the installation to download the necessary components. You can configure proxy information in Windows settings, or include your proxy information directly in the PowerShell commands.

The following steps demonstrate an example of a windows installation using the -proxy argument:

The Invoke-WebRequest command needs proxy information to access the installer script. Then the Deploy-IoTEdge command needs the proxy information to download the installation files.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Deploy-IoTEdge -proxy <proxy URL>
```
The Initialize-IoTEdge command doesn't need to go through the proxy server, so the second step only requires proxy information for Invoke-WebRequest.
```
. {Invoke-WebRequest -proxy <proxy URL> -useb aka.ms/iotedge-win} | Invoke-Expression; Initialize-IoTEdge
```

If you have complicated credentials for the proxy server that you can't include in the URL, use the -ProxyCredential parameter within -InvokeWebRequestParameters. For example,

$proxyCredential = (Get-Credential).GetNetworkCredential()
. {Invoke-WebRequest -proxy <proxy URL> -ProxyCredential $proxyCredential -useb aka.ms/iotedge-win} | Invoke-Expression; `
Deploy-IoTEdge -InvokeWebRequestParameters @{ '-Proxy' = '<proxy URL>'; '-ProxyCredential' = $proxyCredential }

For more information about proxy parameters, see Invoke-WebRequest.

Configure IoT Edge and Moby

IoT Edge relies on two daemons running on the IoT Edge device. The Moby daemon makes web requests to pull container images from container registries. The IoT Edge daemon makes web requests to communicate with IoT Hub.

You must configure both the Moby and the IoT Edge daemons to use the proxy server for ongoing device functionality. This step takes place on the IoT Edge device during initial device setup.

Moby daemon

Since Moby is built on Docker, refer to the Docker documentation to configure the Moby daemon with environment variables. Most container registries (including DockerHub and Azure Container Registries) support HTTPS requests, so the parameter that you should set is HTTPS_PROXY. If you're pulling images from a registry that doesn't support transport layer security (TLS), then you should set the HTTP_PROXY parameter.

Choose the article that applies to your IoT Edge device operating system:

Configure Docker daemon on Linux The Moby daemon on Linux devices keeps the name Docker.
Configure Docker daemon on Windows The Moby daemon on Windows devices is called iotedge-moby. The names are different because it's possible to run both Docker Desktop and Moby in parallel on a Windows device.

IoT Edge daemon

The IoT Edge daemon is similar to the Moby daemon. Use the following steps to set an environment variable for the service, based on your operating system.

The IoT Edge daemon always uses HTTPS to send requests to IoT Hub.

Linux

Open an editor in the terminal to configure the IoT Edge daemon.

sudo systemctl edit aziot-edged

Enter the following text, replacing <proxy URL> with your proxy server address and port. Then, save and exit.

[Service]
Environment="https_proxy=<proxy URL>"

Starting in version 1.2, IoT Edge uses the IoT identity service to handle device provisioning with IoT Hub or IoT Hub Device Provisioning Service. Open an editor in the terminal to configure the IoT identity service daemon.

sudo systemctl edit aziot-identityd

Enter the following text, replacing <proxy URL> with your proxy server address and port. Then, save and exit.

[Service]
Environment="https_proxy=<proxy URL>"

Refresh the service manager to pick up the new configurations.

sudo systemctl daemon-reload

Restart the IoT Edge system services for the changes to both daemons to take effect.

sudo iotedge system restart

Verify that your environment variables and the new configuration are present.

systemctl show --property=Environment aziot-edged
systemctl show --property=Environment aziot-identityd

Windows using IoT Edge for Linux on Windows

Connect-EflowVm

Follow the same steps as the Linux section of this article to configure the IoT Edge daemon.

Windows using Windows containers

Open a PowerShell window as an administrator and run the following command to edit the registry with the new environment variable. Replace <proxy url> with your proxy server address and port.

reg add HKLM\SYSTEM\CurrentControlSet\Services\iotedge /v Environment /t REG_MULTI_SZ /d https_proxy=<proxy URL>

Restart IoT Edge for the changes to take effect.

Restart-Service iotedge

Configure the IoT Edge agent

The IoT Edge agent is the first module to start on any IoT Edge device. This module starts for the first time based on information in the IoT Edge config file. The IoT Edge agent then connects to IoT Hub to retrieve deployment manifests. The manifest declares which other modules the device should deploy.

This step takes place once on the IoT Edge device during initial device setup.

Open the config file on your IoT Edge device: /etc/aziot/config.toml. You need administrative privileges to access the configuration file. On Linux systems, use the sudo command before opening the file in your preferred text editor.
In the config file, find the [agent] section, which contains all the configuration information for the edgeAgent module to use on startup. Check to make sure the [agent] section is without comments. If the [agent] section is missing, add it to the config.toml. The IoT Edge agent definition includes an [agent.env] subsection where you can add environment variables.

Add the https_proxy parameter to the environment variables section, and set your proxy URL as its value.

[agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
# "UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"

The IoT Edge runtime uses AMQP by default to talk to IoT Hub. Some proxy servers block AMQP ports. If that's the case, then you also need to configure edgeAgent to use AMQP over WebSocket. Uncomment the UpstreamProtocol parameter.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```

Add the https_proxy parameter to the environment variables section, and set your proxy URL as its value.

[agent]
name = "edgeAgent"
type = "docker"

[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
# "UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"

The IoT Edge runtime uses AMQP by default to talk to IoT Hub. Some proxy servers block AMQP ports. If that's the case, then you also need to configure edgeAgent to use AMQP over WebSocket. Uncomment the UpstreamProtocol parameter.
```
[agent.config]
image = "mcr.microsoft.com/azureiotedge-agent:1.5"

[agent.env]
# "RuntimeLogLevel" = "debug"
"UpstreamProtocol" = "AmqpWs"
"https_proxy" = "<proxy URL>"
```
Save the changes and close the editor. Apply your latest changes.
```
sudo iotedge config apply
```
Verify that your proxy settings are propagated using docker inspect edgeAgent in the Env section. If not, you must recreate the container.
```
sudo docker rm -f edgeAgent
```
The IoT Edge runtime should recreate edgeAgent within a minute. Once the edgeAgent container is running again, use the docker inspect edgeAgent command to verify that the proxy settings match the configuration file.

Configure deployment manifests

Once you configure your IoT Edge device to work with your proxy server, declare the HTTPS_PROXY environment variable in future deployment manifests. You can edit deployment manifests either using the Azure portal wizard or by editing a deployment manifest JSON file.

Always configure the two runtime modules, edgeAgent and edgeHub, to communicate through the proxy server so they can maintain a connection with IoT Hub. If you remove the proxy information from the edgeAgent module, the only way to reestablish connection is by editing the config file on the device, as described in the previous section.

In addition to the edgeAgent and edgeHub modules, other modules may need the proxy configuration. Modules that need to access Azure resources besides IoT Hub, such as blob storage, must have the HTTPS_PROXY variable specified in the deployment manifest file.

The following procedure is applicable throughout the life of the IoT Edge device.

Azure portal

When you use the Set modules wizard to create deployments for IoT Edge devices, every module has an Environment Variables section where you can configure proxy server connections.

To configure the IoT Edge agent and IoT Edge hub modules, select Runtime Settings on the first step of the wizard.

Screenshot of how to configure advanced Edge Runtime settings.

Add the https_proxy environment variable to both the IoT Edge agent and IoT Edge hub module runtime settings definitions. If you included the UpstreamProtocol environment variable in the config file on your IoT Edge device, add that to the IoT Edge agent module definition too.

All other modules that you add to a deployment manifest follow the same pattern. Select Apply to save your changes.

JSON deployment manifest files

If you create deployments for IoT Edge devices using the templates in Visual Studio Code or by manually creating JSON files, you can add the environment variables directly to each module definition. If you didn't add them in the Azure portal, add them here to your JSON manifest file. Replace <proxy URL> with your own value.

Use the following JSON format:

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    }
}

With the environment variables included, your module definition should look like the following edgeHub example:

"edgeHub": {
    "type": "docker",
    "settings": {
        "image": "mcr.microsoft.com/azureiotedge-hub:1.5",
        "createOptions": "{}"
    },
    "env": {
        "https_proxy": {
            "value": "http://proxy.example.com:3128"
        }
    },
    "status": "running",
    "restartPolicy": "always"
}

If you included the UpstreamProtocol environment variable in the confige.yaml file on your IoT Edge device, add that to the IoT Edge agent module definition too.

"env": {
    "https_proxy": {
        "value": "<proxy URL>"
    },
    "UpstreamProtocol": {
        "value": "AmqpWs"
    }
}

Working with traffic-inspecting proxies

Some proxies like Zscaler can inspect TLS-encrypted traffic. During TLS traffic inspection, the certificate returned by the proxy isn't the certificate from the target server, but instead is the certificate signed by the proxy's own root certificate. By default, IoT Edge modules (including edgeAgent and edgeHub) don't trust this proxy's certificate and the TLS handshake fails.

To resolve the failed handshake, configure both the operating system and IoT Edge modules to trust the proxy's root certificate with the following steps.

Configure proxy certificate in the trusted root certificate store of your host operating system. For more information about how to install a root certificate, see Install root CA to OS certificate store.
Configure your IoT Edge device to communicate through a proxy server by referencing the certificate in the trust bundle. For more information on how to configure the trust bundle, see Manage trusted root CA (trust bundle).

To configure traffic inspection proxy support for containers not managed by IoT Edge, contact your proxy provider.

Fully qualified domain names (FQDNs) of destinations that IoT Edge communicates with

If your proxy's firewall requires you to add all FQDNs to your allowlist for internet connectivity, review the list from Allow connections from IoT Edge devices to determine which FQDNs to add.

Next steps

Learn more about the roles of the IoT Edge runtime.

Troubleshoot installation and configuration errors with Common issues and resolutions for Azure IoT Edge

Zdieľať cez