Tunnel troubleshooting

Setup noticeCopy Anchor Link

If the dashboard says tunnel setup is unavailable, contact Loclix support with the message. Check that your website has completed DNS and certificate setup before testing a published hostname.

No active connectionsCopy Anchor Link

1. Check the connector service logs with journalctl -u loclix-connector@ACCOUNT-ID.TUNNEL-ID.service.
2. Check the account and tunnel IDs in connector.json.
3. Check that the token file is readable only by its owner.
4. Allow outbound HTTPS to your dashboard host.
5. Allow outbound UDP and TCP port 443 to waf-ingress.loclix.network.

A network proxy that replaces the ingress certificate prevents the connector from verifying Loclix. Allow the connector's TLS connection to pass through without interception.

Credential permission errorsCopy Anchor Link

Older connectors can report Tunnel token file requires mode 0600 or stricter when reading a systemd credential. Release 0.18.5 fixes the permission check for systemd's access-control lists.

Enable automatic updates and run the update check:

sudo systemctl start loclix-connector-update@ACCOUNT-ID.TUNNEL-ID.service

Keep source credential files under /etc/loclix-connector/ at mode 0600. Do not change systemd's runtime credential permissions. This update does not require a new activation code.

UDP buffer warningCopy Anchor Link

A receive-buffer warning can limit QUIC throughput without preventing a connection. Run the current installation command to configure the host's receive and send limits. Restricted containers may need these settings applied on their host.

Restart the connector after changing buffer limits:

sudo loclix-connector restart

Pending destination changesCopy Anchor Link

Dashboard-managed services require connector release 0.19.0 or later. Check the reported address and pending destination in Tunnels. If reports are missing, check that the connector is online and can reach your dashboard host.

A saved address becomes active only after the connector applies it. See Local services for replica behavior. Contact support if the dashboard reports that service management is unavailable.

HTTP/2 connectionsCopy Anchor Link

The connector uses QUIC when it can establish a UDP connection. If that fails, it uses encrypted HTTP/2 over TCP. An HTTP/2 connection is a supported working state.

Check outbound UDP port 443 if you expect QUIC. The connector tries QUIC again when it next reconnects.

Service errorsCopy Anchor Link

Security rules or Zero Trust can reject a request before it reaches the tunnel. Use its request ID in Monitoring to inspect the decision.

Repeated disconnectionsCopy Anchor Link

Check for token replacement, a paused connector, or failed update restarts. A credential change affects every replica. Also check connectivity to the dashboard host: authorization expires after 60 seconds without renewal.

If the issue persists, send support the request ID and relevant log errors. Exclude tokens, activation commands, and private keys.

Unmatched pathsCopy Anchor Link

A prefix of /admin does not match /administrator. Review path matching and check that the route is enabled. Unmatched paths use the website's other origin routes.