Troubleshooting Agent Connections

By design, agents need a direct connection to the CloudSoda Controller. Several factors, particularly related to firewalls, may hinder agents from connecting to one another. This section outlines agent commands for troubleshooting connection issues, along with recommended firewall configurations to ensure the successful formation of an agent mesh.

Agent commands

Run the following agent commands from the CloudSoda agent's workstation. On macOS or Linux, some commands may require the use of sudo to execute successfully.

Log command

The log command records all agent commands and results to a file. To follow the log stream, use the -f flag. To return all flags that can be used with the log command, run the soda log --help command. 

soda log 

Curl debug commands

The curl debug commands enable and disable debugging on the CloudSoda agent. To log debugging output, pair the soda log command with the curl debug commands. 

curl http://127.0.0.1:8498/enable-debug 

or

curl http://127.0.0.1:8498/disable-debug

Alternatively, you can manage agent debugging by configuring soda.conf.

Netcheck command

The netcheck command generates a report with workstation network details, including UDP availability, IP addresses, and NAT mapping values.

soda netcheck

NAT mapping value

The NAT mapping value as provided by running soda netcheck indicates if the agent can successfully open a tunnel over NAT to allow WAN connections to the agent. If the NAT mapping value is yes, then other agents cannot make an incoming connection to the agent over the WAN. However, the agent may be able to make an outgoing connection to another agent.

• If two agents have this setting: NAT mapping varies: Yes
  They cannot connect over the WAN and you must provide a direct connection between their IP addresses.
• If one agent has this setting: NAT mapping varies: No
  Other agents can make an incoming connection to this agent over the WAN. However, other factors may prevent a successful agent-to-agent connection over the WAN. For additional details, see Firewall Compatibility and Workarounds below.

NOTE: The following commands include a candidate address, which is the IP/port combination that the agent listens for incoming requests from other agents.

Probe command

The probe command checks if an agent can connect to another agent. The command results will be either success or a timeout.

soda probe  

Curl API commands

The curl api node-info command shows the candidate addresses of the agent along with its ID.

curl http://127.0.0.1:8498/api/node-info

The curl api mesh.txt command shows the agent mesh network from the viewpoint of the agent, including other agents it knows about and their candidate addresses, and it lists all connections the agent can make.

curl http://127.0.0.1:8498/api/mesh

To check if the agent can connect to another agent, use this command with the soda probe command.

Firewall Compatibility and Workarounds

Your organization may have a firewall in place to protect its network from unsolicited, unnecessary or malicious traffic. We recommend evaluating your security requirements and carefully considering the risks of implementing a firewall workaround to allow CloudSoda agents to establish direct connections, as this could potentially expose your network to unwanted traffic.

Specifically, consider the following impacts:

• Enabling NAT-PMP and UPnP protocols will allow your network to accept and forward all traffic.

• Opening a firewall port will permit traffic on a specific port, subject to defined rules for outgoing traffic. It is important to restrict traffic to only what is essential to support the firewall workaround.

The table below outlines various firewall brands, their compatibility with CloudSoda agents, and the recommended workarounds to enable direct agent connections. If direct connections aren’t possible, an alternative connection method via NAT traversal is available.

{// ACLs and other configurations
"randomizeClientPort":true}