Agent doesn't connect to the dashboard

Quick troubleshooting procedure

An agent may not be able to connect to the NetBeez server for various reasons, such as:

  1. The agent is not powered on
    1. Check the status lights on hardware agents
  2. The agent can't resolve the server's address (FQDN)
    1. Ping the server
  3. A network firewall is blocking the agent
    1. Telnet to the server port 20018
  4. The server doesn't have a valid license or maxed out
    1. Check the license in the NetBeez settings
  5. The agent is faulty
    1. Open an RMA case with NetBeez support


Detailed troubleshooting procedure

Step 1 - Agent is powered up and shows activity

This step applies to hardware sensors. If you are troubleshooting a software or virtual agent, verify that the host or virtual appliance is powered up.

If you are troubleshooting a Fast Ethernet and WiFi beez

These sensors are based on the Raspberry Pi platform. The Raspberry Pi has two LEDs:

Power Led - Solid, it signals that the unit is receiving power via power supply or PoE.

Activity Led - Blinking based on SD card activity.


A unit where the red led is solid, but the green one doesn’t show any activity for around 10 seconds may be faulty. In this case, open an RMA to support [at] netbeez [dot] net.

If you are troubleshooting a GigE beez

Gigabit Ethernet sensors are based on the Intel Up-Board platform. The Up-Board has one blue LED that is visible from the top of the case. You can verify that the blue light is one, and eventually that there's network activity on the Ethernet interface:

IMG_2999.JPG           IMG_3001.JPG

A unit where the blue light is not visible, or the Ethernet doesn't show any activity, may be faulty. In this case, open an RMA to support [at] netbeez [dot] net.


Step 2 - Get troubleshooting information by initiating an ssh session

If there is routing between your machine and the agent and port 22 is not blocked and you know the agent's IP, you can get useful troubleshooting information if you try to initiate an ssh session with the agent. By doing that you will get an output similar to this one:

$> ssh Tue May 19 13:00:18 EDT 2020 Agent version: 1.0.0 Linux Kernel: Linux nbagent 4.1.19-v7+ #858 SMP Tue Mar 15 15:56:00 GMT 2016 armv7l GNU/Linux$ OS: Debian GNU/Linux 7.11 (wheezy) eth0: MAC: b8:27:eb:31:42:4a, IP:, status: up, configuration: static, type: wired iface eth0 inet static address netmask gateway dns-nameservers Host: Unencrypted port: 20019 (default route:heartbeat detected, eth0:open) Encrypted port: 20018 (heartbeat:detected on default route, eth0:open) Dashboard port: 443 (eth0:open) Websocket port: 443 (eth0:open)

You don't need to have any credentials or login user name and password or key to get this output. You should be able to get information by using any kind of ssh utility (e.g. putty) or console.


Step 3 - Is the network configured to enable agent-server communication?

For an agent to successfully connect to the dashboard, the network must be configured to resolve the server's Fully Qualified Domain Name (FQDN) and allow the agent to establish a TCP connection to port 20018. If you are able to ssh to a NetBeez agent you can perform the following two tests. If you are not, you'd be able to get the most reliable information if you performed these steps on a host in the same subnet with the agent in question. 

1- Verify that the agent is able to resolve the server's fully qualified domain name (FQDN):

ping <server_FQDN>

2- Verify with telnet that no network firewalls are blocking agent's connection to the NetBeez server:

telnet <server_FQDN> 20018


Step 4 - Is the agent receiving a DHCP lease?

Check the logs of your DHCP server and verify that the server offers an IP address to the agent’s MAC address. The agent's MAC address can be located on the case.


Step 5 - Check the NetBeez license file

Check your license file by clicking the NetBeez Settings gear icon in the upper right corner and then the License tab.
Check if you are licensed for the agent you trying to connect to your dashboard. For example, if you are licensed for three virtual agents and you already have three virtual agents connected, then any additional virtual agents trying to connect to your dashboard will be rejected.
If you would like to replace a virtual agent with a new one, you must delete an existing virtual agent and then spin up the new virtual agent. For instructions for deleting an agent, please see the following article:
Agent Configuration - Delete Agent


Other checks 

  • If you are able to ssh or console to the agent, please send to support [at] netbeez [dot] net the last 100 lines of the agent log file with the following command:
tail -n 100 /var/log/netbeez/agent-agent.log
Have more questions? Submit a request


Please sign in to leave a comment.