deepflow icon indicating copy to clipboard operation
deepflow copied to clipboard
verified publisher icon deepflowio

Question: Is a MAC address strictly required for agent-server communication over L3 VPN tunnels?

Open sujoshua opened this issue 6 months ago • 3 comments

Search before asking

  • [x] I had searched in the issues and found no similar feature requirement.

DeepFlow Component

Server

What you expected to happen

Hello DeepFlow Team,

I am trying to use DeepFlow to manage a fleet of bare-metal servers. These servers are located in different geographical regions and are connected using a WireGuard (L3) VPN tunnel to form a private network.

My Environment Setup

  • Infrastructure: A group of geographically distributed bare-metal servers.

  • Networking: All servers are interconnected via a WireGuard tunnel, each having a private IP address within the VPN. The connectivity between nodes over this private network is working correctly.

  • DeepFlow Server: The DeepFlow server components are running on one of these servers, deployed via docker-compose, and are exposed on the server's private WireGuard IP address.

  • Verification: I have confirmed that the nodes can communicate with each other over the WireGuard network. The deepflow-ctl command also works correctly, indicating that the basic control plane communication is functional.

  • Agent Configuration: The controller-ip and port in /etc/deepflow-agent.yaml are correctly configured to point to the DeepFlow server's WireGuard IP.

The Problem

When I try to start the deepflow-agent on any of the nodes, it fails to initialize and enters a restart loop. The log shows the following critical error:

Error: get ctrl ip and mac failed: environment error: failed getting control ip and mac, deepflow-agent restart...

This error suggests that the agent is attempting to resolve the MAC address of the network interface associated with the controller-ip. However, WireGuard creates a pure L3 virtual interface (e.g., wg0), which does not have a MAC address.

This leads me to believe that the agent's startup process has a hard dependency on a Layer 2 MAC address, which makes it incompatible with L3 VPN tunneling solutions like WireGuard out-of-the-box.

My Questions

  1. MAC Address Requirement: Does the deepflow-agent strictly require the network interface it uses to communicate with the controller to have a physical MAC address?

  2. Agent-Side Requirement: Similarly, does the interface that the agent binds to on its own host also need to have a MAC address?

  3. Potential Workarounds:

  • Is there a configuration option in deepflow-agent.yaml to bypass this MAC address check?

  • Alternatively, is it possible to manually specify a dummy/virtual MAC address in the configuration file to satisfy this startup requirement?

My goal is to monitor traffic within this VPN-interconnected environment, and this initial startup failure is the primary blocker. Any guidance or potential solution would be greatly appreciated.

Thank you for your time and help!

DeepFlow version

v7.1.2

Kubernetes CNI

docker compose way

Operation-System/Kernel version

debian 13 6.12.41+deb13-cloud-amd64

Code of Conduct

sujoshua avatar Oct 10 '25 06:10 sujoshua

That’s an interesting scenario. DeepFlow is designed for large-scale, multi-tenant cloud environments, and from the very beginning, we considered the possibility of IP address conflicts across different VPCs. Therefore, we use a combination of IP + MAC address as the unique identifier for each agent.

At the same time, we recognized that in some environments this level of complexity might not be necessary, so we provided a local configuration option for the agent: https://github.com/deepflowio/deepflow/blob/main/agent/config/deepflow-agent.yaml#L42

You can try changing this config to ip and see if it resolves your issue.

However, when we introduced this configuration option, we might not have fully accounted for cases where the agent is unable to obtain the MAC address. In such cases, a minor code modification might be required. Please let us know whether the configuration works for you.

sharang avatar Oct 17 '25 02:10 sharang

Thanks for your detailed reply.

Using a combination of IP + MAC as the unique identifier for large-scale, multi-tenant environments with potential IP conflicts makes perfect sense to me. A configuration switch for simpler environments is a great idea for flexibility.

As you suggested, I modified the local /etc/deepflow-agent.yaml file and added the agent-unique-identifier: ip option.

However, the issue persists. The agent still fails to start and enters a restart loop with the same error message:

Error: get ctrl ip and mac failed: environment error: failed getting control ip and mac, deepflow-agent restart...

It appears that the get_ctrl_ip_and_mac() function is being called regardless of the agent-unique-identifier setting. The agent is still attempting to fetch the MAC address even when the configuration is set to use only the IP address as the identifier.

Let me know if there's any other information I can provide to help troubleshoot. Thanks again for your help.

sujoshua avatar Oct 18 '25 14:10 sujoshua

Hi Joshua,

These's a way to configure control interface by setting environment variable CTRL_NETWORK_INTERFACE to the interface name by executing

CTRL_NETWORK_INTERFACE=$if_name deepflow-agent

or by adding it in systemd service file.

And could you provide

  1. Agent log with the error
  2. The output of ip addr on your host

rvql avatar Oct 20 '25 11:10 rvql