Troubleshoot your IoT Edge for Linux on Windows networking

Article
11/19/2024

Applies to: IoT Edge 1.5

Important

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

If you experience networking issues using Azure IoT Edge for Linux on Windows (EFLOW) in your environment, use this article as a guide for troubleshooting and diagnostics. Also, check Troubleshoot your IoT Edge for Linux on Windows device for more EFLOW virtual machine troubleshooting help.

Isolate the issue

When troubleshooting IoT Edge for Linux on Windows networking, there are four network features that could be causing issues:

IP addresses configuration
Domain Name System (DNS) configuration
Firewall and port configurations
Other components

For more information about EFLOW networking concepts, see IoT Edge for Linux on Windows networking. Also, for more information about EFLOW networking configurations, see Networking configuration for Azure IoT Edge for Linux on Windows.

Check IP addresses

Your first step when troubleshooting IoT Edge for Linux on Windows networking should be to check the VM IP address configurations. If IP communication is misconfigured, then all inbound and outbound connections fail.

Start an elevated PowerShell session using Run as Administrator.
Check the IP address returned by the VM lifecycle agent. Make note of the IP address and compare it with the one obtained from inside the VM in the later steps.
```
Get-EflowVmAddr
```
Connect to the EFLOW virtual machine.
```
Connect-EflowVm
```

Check the eth0 VM network interface configuration.

 ifconfig eth0

In the output, you should see the eth0 configuration information. Ensure that the inet address is correctly set.

eth0: flags=4163<UP,BROADCAST,RUNNING,MULTICAST>  mtu 1500
    inet 172.31.100.171  netmask 255.255.240.0  broadcast 172.31.111.255
    inet6 fe80::215:5dff:fe2a:2f62  prefixlen 64  scopeid 0x20<link>
    ether 00:15:5d:2a:2f:62  txqueuelen 1000  (Ethernet)
    RX packets 115746  bytes 11579209 (11.0 MiB)
    RX errors 0  dropped 0  overruns 0  frame 0
    TX packets 976  bytes 154184 (150.5 KiB)
    TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0

If the inet IP address is blank or different from the one provided by using the Get-EflowVmAddr cmdlet, you need to troubleshoot why the EFLOW VM has an invalid or no IP address assigned. Use the following table to troubleshoot the issue:

Virtual Switch	IP Address Assignation	Troubleshoot
External	Static IP	Ensure that the IP configuration is correctly set up. All three parameters ip4Address, ip4GateWayAddress, and ip4PrefixLength should be used. The IP address assigned to the VM should be valid and not being used by other device on the external network. You can check EFLOW VM interface configurations by checking the files under `/etc/systemd/network/`.
External	DHCP	Ensure that there's a DHCP server on the external network. If no DHCP server is available, then use static IP configurations. Also, make sure that DHCP server has no firewall policy regarding MAC addresses. If it has, you can get the EFLOW MAC address by using the `Get-EflowVmAddr` cmdlet.
Default switch	DHCP	Generally, the issue is related to a malfunction of the default switch. Try rebooting the Windows host OS. If the problem persists, try disabling and enabling Hyper-V
Internal	Static IP	Ensure that the IP configuration is correctly set up. All three parameters ip4Address, ip4GateWayAddress, and ip4PrefixLength should be used. The IP address assigned to the VM should be valid and not being used by other device on the internal network. Also, to get connected to internet, you'll need to set up a NAT table. Follow the NAT configuration steps in Azure IoT Edge for Linux on Windows virtual switch creation.
Internal	DHCP	Ensure that there's a DHCP server on the internal network. To set up a DHCP server and a NAT table on Windows Server, follow the steps in Azure IoT Edge for Linux on Windows virtual switch creation. If no DHCP server is available, then use static IP configurations.

Warning

In some cases, if you are using the external virtual switch on a Windows Server or client VM, you may need some extra configurations. For more information about nested virtualization configurations, see Nested virtualization for Azure IoT Edge for Linux on Windows.

If you're still having issues with the IP address assignation, try setting up another Windows or Linux virtual machine and assign the same switch and IP configuration. If you have the same issue with the new non-EFLOW VM, the issue is likely with the virtual switch or IP configuration and it's not specific to EFLOW.

Check Domain Name System (DNS) configuration

Your second step when troubleshooting IoT Edge for Linux on Windows networking should be to check the DNS servers assigned to the EFLOW VM. To check the EFLOW VM DNS configuration, see Networking configuration for Azure IoT Edge for Linux on Windows. If address resolution is working, then the issue is likely related to firewall or security configurations on the network.

The EFLOW VM uses the systemd-resolved service to manage the DNS resolution. For more information about this service, see Systemd-resolved. To set up a specific DNS server address, you can use the Set-EflowVmDnsServers cmdlet. If you need further information about the DNS configuration, you can check the /etc/systemd/resolved.conf and the system-resolved service using the sudo systemctl status systemd-resolved command. Also, you can set a specific DNS server as part of the module configuration, see Option 2: Set DNS server in IoT Edge deployment per module.

The address resolution could fail for multiple reasons. First, the DNS servers could be configured correctly, however they can't be reached from the EFLOW VM. If the DNS servers respond to ICMP ping traffic, you can try pinging the DNS servers to check network connectivity.

Start an elevated PowerShell session using Run as Administrator.
Connect to the EFLOW virtual machine.
```
Connect-EflowVm
```
Ping the DNS server address and check the response.
```
ping <DNS-Server-IP-Address>
```
Tip

If the server is reachable, you should get a response, and your issue may be related to other DNS server configurations. If there's no response, then you probably have a connection issue to the server.

Second, some network environments will limit the access of the DNS servers to specific allowlist addresses. If so, first make sure that you can access the DNS server from the Windows host OS, and then check with your networking team if you need to add the EFLOW IP address to an allowlist.

Finally, some network environments block public DNS servers, like Google DNS (8.8.8.8 and 8.8.4.4). If so, talk with your network environment team to define a valid DNS server, and then set it up using the Set-EflowVmDnsServers cmdlet.

Check your firewall and port configuration rules

Azure IoT Edge for Linux on Windows allows communication from an on-premises server to Azure cloud using supported Azure IoT Hub protocols. For more information about IoT Hub protocols, see choosing a communication protocol. For more information about IoT Hub firewall and port configurations, see Troubleshoot your IoT Edge device.

The IoT Edge for Linux on Windows is still dependent on the underlying Windows host OS and the network configuration. Hence, it's imperative to ensure proper network and firewall rules are set up for secure edge to cloud communication. The following table can be used as a guideline when configuration firewall rules for the underlying servers where Azure IoT Edge for Linux on Windows runtime is hosted:

Protocol	Port	Incoming	Outgoing	Guidance
MQTT	8883	BLOCKED (Default)	BLOCKED (Default)	Configure Outgoing (Outbound) to be Open when using MQTT as the communication protocol. 1883 for MQTT isn't supported by IoT Edge. - Incoming (Inbound) connections should be blocked.
AMQP	5671	BLOCKED (Default)	OPEN (Default)	Default communication protocol for IoT Edge. Must be configured to be Open if Azure IoT Edge isn't configured for other supported protocols or AMQP is the desired communication protocol. 5672 for AMQP isn't supported by IoT Edge. Block this port when Azure IoT Edge uses a different IoT Hub supported protocol. Incoming (Inbound) connections should be blocked.
HTTPS	443	BLOCKED (Default)	OPEN (Default)	Configure Outgoing (Outbound) to be Open on port 443 for IoT Edge provisioning. This configuration is required when using manual scripts or Azure IoT Device Provisioning Service (DPS). Incoming (Inbound) connection should be Open only for two specific scenarios: 1. If you have a transparent gateway with downstream devices that may send method requests. In this case, port 443 doesn't need to be open to external networks to connect to IoT Hub or provide IoT Hub services through Azure IoT Edge. Thus the incoming rule could be restricted to only open Incoming (Inbound) from the internal network. 2. For client to device (C2D) scenarios. 80 for HTTP isn't supported by IoT Edge. If non-HTTP protocols (for example, AMQP or MQTT) can't be configured in the enterprise; the messages can be sent over WebSockets. Port 443 is used for WebSocket communication in that case.

Note

If you are using an external virtual switch, make sure to add the appropriate firewall rules for the module port mappings you're using inside the EFLOW virtual machine.

For more information about EFLOW VM firewall, see IoT Edge for Linux on Windows Security. To check the EFLOW virtual machine rules, use the following steps:

Start an elevated PowerShell session using Run as Administrator.
Connect to the EFLOW virtual machine.
```
Connect-EflowVm
```
List the iptables firewall rules.
```
sudo iptables -L
```

To add a firewall rule to the EFLOW VM, you can use the EFLOW Util - Firewall Rules sample PowerShell cmdlets. Also, you can achieve the same rules creation by following these steps:

Start an elevated PowerShell session using Run as Administrator.
Connect to the EFLOW virtual machine
```
Connect-EflowVm
```
Add a firewall rule to accept incoming traffic to <port> of <protocol> ( udp or tcp) traffic.
```
sudo iptables -A INPUT -p <protocol> --dport <port> -j ACCEPT
```
Finally, persist the rules so that they're recreated on every VM boot
```
sudo iptables-save | sudo tee /etc/systemd/scripts/ip4save
```

Check other configurations

There are multiple other reasons why network communication could fail. The following section will just list a couple of issues that users have encountered in the past.

EFLOW virtual machine won't respond to ping (ICMP traffic) requests.

By default ICMP ping traffic response is disabled on the EFLOW VM firewall. To respond to ping requests, allow the ICMP traffic by using the following PowerShell cmdlet:

Invoke-EflowVmCommand "sudo iptables -A INPUT -p icmp --icmp-type 8 -s 0/0 -m state --state NEW,ESTABLISHED,RELATED -j ACCEPT"
Failed device discovery using multicast traffic.

First, to allow device discovery via multicast, the Hyper-V VM must be configured to use an external switch. Second, the IoT Edge custom module must be configured to use the host network via the container create options:
```
{
  "HostConfig": {
    "NetworkMode": "host"
  },
  "NetworkingConfig": {
    "EndpointsConfig": {
      "host": {}
    }
  }
}
```
Firewall rules added, but traffic still not able to reach the IoT Edge module.

If communication is still not working after addling the appropriate firewall rules, try completely disabling the firewall to troubleshoot.
```
sudo iptables -F
sudo iptables -X
sudo iptables -P INPUT ACCEPT
sudo iptables -P OUTPUT ACCEPT
sudo iptables -P FORWARD ACCEPT
```
Once finished, reboot the VM (Stop-EflowVm and Start-EflowVm) to get the EFLOW VM firewall back to normal state.
Can't connect to internet when using multiple NICs.

Generally, this issue is related to a routing problem. Check How to configure Azure IoT Edge for Linux on Windows Industrial IoT & DMZ configuration to set up a static route.

Next steps

Do you think that you found a bug in the IoT Edge platform? Submit an issue so that we can continue to improve.

If you have more questions, create a Support request for help.

Share via