Reference · for Administrators, Engineers
Troubleshoot gateways
What the edge gateway statuses and install messages mean, why a gateway is offline or refused, and how its buffer keeps data while the hub is away.
An edge gateway reads the devices and sends their data to the hub. When it is not connected, its devices, rules, functions and pipelines do not report to the hub. This page explains each gateway status and install message.
Gateway status
Connect > Edge Gateways shows one status per gateway:
| Status | Meaning | What to check |
|---|---|---|
Online (for <time>) | Connected. The gateway sent its figures in the last minute. | |
Never connected | The gateway was created in the hub but has never connected. | Install it: see Install a gateway. |
Last seen <time> ago | The connection closed. The detail gives the reason, for example The connection closed on <time>: it stopped answering (network or host down). Check the host and that it reaches the hub on port 7422. | Is the host running? Is the gateway container running (docker ps)? Can the host reach the hub on port 7422? |
Not responding | The connection to the hub is up, but the gateway sends nothing. Its logs on the host show why (docker logs). | docker logs of the gateway container on its host. |
Connection refused | Something on the network tries to connect as this gateway with a key the hub does not accept. | See Refused connections. |
Access revoked | Access was revoked on <date> by <user>. | To connect it again, choose Install and run the new command on its host. |
A gateway counts as connected when its latest report is less than 60 seconds old. Gateways report every 10 seconds ([EdgeGateway] EdgeMetricsTransmissionInterval).
The reasons given for a closed connection:
| Reason | Meaning |
|---|---|
the gateway closed it (stopped or restarted) | Normal during an update or restart. |
it stopped answering (network or host down) | The host or the network went away. |
network error | The connection broke. |
its access was revoked | Someone revoked the gateway in the hub. |
its credentials expired | Reinstall the gateway with a new command. |
the hub's NATS server stopped | The problem is on the hub: check the hub-server container. |
A gateway does not connect after the upgrade to 2.0.0
Since 2.0.0, the hub's message server accepts only TLS connections, checked against the platform CA. A gateway installed before 2.0.0 does not have these settings and stays disconnected.
- In Connect > Edge Gateways, open the gateway and select Install.
- Run the new command on the gateway's host.
The gateway kept reading its devices meanwhile. It sends the buffered data once it is connected (see The buffer).
Also check that the hub's message server was restarted once after the upgrade (docker restart hub-server, or the hub-server pods on Kubernetes). See Upgrade.
The gateway reaches the hub under an address the certificate does not cover
The gateway checks that the hub's NATS certificate covers the address it connects to. The address you choose when you create the install command is added to that certificate automatically. If gateways reach the hub under another name, for example a DNS alias or the address of a NAT that was added later, the TLS check fails and the gateway does not connect.
Add the name to [NATS] TlsHostNames or [Service] PublicHostNames in the hub's configuration, separated by commas, and restart the hub. Or create a new install command for that address.
Refused connections
The host <address> keeps trying to connect with a key that was revoked or replaced (<n> attempts). Reinstall it with a new command, or stop it.An old installation of this gateway is still running somewhere, for example after the gateway was reinstalled on another host. Stop the old one.A host at <address> tries to connect as this gateway with a key the hub does not know (<n> attempts).Check that host. To install this gateway there, choose Install.
Installing a gateway
The install command from Install works once and for one hour. The install dialog follows the host through these stages: Installer downloaded on the host, Gateway key registered with the hub, Gateway image downloaded, Gateway started, Connected to this hub.
The host needs: Docker 20.10 or later with the Compose plugin, ports 8083, 1883 and 8883 free, and access to the hub on ports 7422 and 8443 (or the hub's HTTP port 8080, when HTTPS is off on the hub).
| Message | Meaning | What to do |
|---|---|---|
Proxus: This install link was already used. | The command ran before. | Create a new command in the hub: Edge Gateways, Install. |
Proxus: This install link has expired. | More than an hour passed. | Create a new command. |
Proxus: This install link is not valid. | The link was mistyped or cut. | Copy the whole command again. |
Docker is not installed. Install Docker 20.10 or later and run the command again. | Install Docker. | |
Docker is installed but not running, or this user cannot use it. Start Docker, or run the command with sudo. | Start Docker, or use sudo. | |
Docker Compose is not available. Install the Docker Compose plugin and run the command again. | Install the Compose plugin. | |
Port <port> is already used by the container <name> on this host. or ...by another program on this host. | 8083, 1883 or 8883 is taken, often by an earlier gateway. | Stop or remove it, then run a new command from the hub. |
curl fails with an error about the pinned public key. | The command is pinned to the hub's HTTPS key, and the hub's HTTPS certificate changed after the command was created (for example after Set as Default or Renew). | Create a new command. |
The image could not be downloaded. Check that this host can reach Docker Hub. | No internet access or a proxy blocks it. | Allow access to Docker Hub, or load the images first: see Install without internet access. |
The gateway key could not be created. or The hub did not accept this gateway. Create a new command in the hub and run it again. | Registration with the hub failed, usually because the command was used or expired. | Create a new command. |
The containers could not be started. The output above shows why. | Read the terminal output on the host. |
When it works, the host prints Proxus: edge gateway started. It appears as connected in the hub within a minute. If the dialog then stays at Gateway started, the host cannot reach the hub on port 7422.
The buffer: when the hub is unreachable
A gateway keeps reading its devices when it loses the hub. It stores what it could not deliver on its own disk and sends it when the connection is back.
- Buffer Retention (hours) on the gateway sets how long it keeps undelivered data: 1 to 720 hours, default 48. Older data is dropped first. The gateway needs disk space for that many hours of its data.
- Lowering the value drops buffered data older than the new limit.
- The setting is not shown for the hub's own gateway, SYSTEM, which runs next to the hub.
Outbound targets that a gateway sends to directly have their own buffering; see Outbound targets.
Configuration that does not reach a gateway
After you change a device, rule, function or pipeline, the hub sends it to the gateway and waits for the gateway to confirm. The operational graph and Health checks show the result per object:
| Shown | Meaning |
|---|---|
In sync | The gateway runs what is configured. |
Waiting, gateway offline | It will be applied when the gateway connects. |
Published, never applied | Sent, but the gateway did not confirm. Check that the gateway is online and its logs. |
Edge runs a different revision | The gateway runs an older or newer version. Deploy again. |
Failed to apply | The gateway refused it. The error is on the object. |
Partly applied, Not confirmed by edge | Some parts were confirmed, others not yet. |
Related
Was this page helpful?
Evaluating Proxus? See it on your own machines in a 30-minute technical session.