Copy page

Secure Tunnel

Troubleshoot a Tunnel

A tunnel spans your network and Zuplo's, so traffic often fails to reach its destination on the first attempt. The cause is usually a configuration in your own network — a firewall, VPC route, security group, or IAM rule — rather than the tunnel itself.

Work through the checks on this page in order. Each one narrows down which part of the path is failing.

Confirm the tunnel is connected

Start here. If the tunnel isn't connected, nothing else matters.

Code
# The commands below assume you exported your API key:
# export ZUPLO_API_KEY=zpka_d67b7e241bb948758f415b79aa8exxxx_2efbxxxx

zuplo tunnel list
zuplo tunnel describe --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx

Check the status field in the output of zuplo tunnel describe.

If the status is down:

• Wait a few seconds. A newly created tunnel takes a moment to register the first time it connects.
• Check the container or process for errors. A container that exits immediately usually indicates a bad or missing TUNNEL_TOKEN.
• Confirm the token matches the tunnel. Re-run zuplo tunnel describe and compare it against the value your container receives. If the token was rotated, the old value no longer establishes new connections.
• Verify the host has outbound internet access. The tunnel connects outbound on TCP port 7844, and the zuplo/tunnel image uses HTTP/2 rather than QUIC, so outbound UDP isn't required. An egress firewall or proxy that blocks that port prevents the tunnel from connecting.
• Confirm the host runs Linux. See tunnel requirements.

Check the service configuration

A connected tunnel that returns errors is often missing a service, or has one that's scoped to a different environment.

Code
zuplo tunnel services describe --tunnel-id tnl_TRMZwunq2PLNQDwhu6A04Bmx

Compare the output against the service:// URL your gateway calls:

• The service name matches exactly. service://payments-api requires a service named payments-api. Names are case-sensitive and don't allow partial matches.
• Your project is listed. A project absent from a service's configurations can't reach it.
• Your environment is allowed. Check that accessibleBy includes the environment you're testing from: production, preview, or working-copy. A service scoped to production returns an error when called from a preview build.
• The configuration is the one you meant to upload. Each zuplo tunnel services update replaces the whole configuration, so a partial file removes services you left out.

For the meaning of each property, see Service configuration reference.

Enable debug logging

If the tunnel is connected and the services look right but traffic still doesn't arrive, raise the log level to see what the tunnel does with each request.

Set TUNNEL_LOGLEVEL to debug on your tunnel instance:

Code
TUNNEL_LOGLEVEL=debug

How you set the variable depends on where you deployed. For a container, set it as a container environment variable and restart the instance. Consult your platform's documentation for the specific mechanism.

Debug logs show each connection attempt the tunnel makes to your internal endpoint, which distinguishes the two common failures:

• No attempt logged. The request isn't reaching the tunnel. Recheck the service configuration and the service:// URL in your gateway.
• An attempt that fails. The tunnel is working and can't reach your backend. Continue to Check connectivity to your backend.

Return the log level to info or error when you finish. Debug logging is verbose.

Check connectivity to your backend

The tunnel reaches your backend the same way any other process in the same network position would, so reproduce the request from there.

The tunnel image is distroless and has no shell, so you can't exec into it. Run a debug container in the same network instead:

Code
docker run --rm --network container:zuplo-tunnel curlimages/curl \
  -sv http://payments.internal:8080/health

On Kubernetes, run the equivalent pod in the same namespace as the tunnel:

Code
kubectl run tunnel-debug --rm -it --image=curlimages/curl --restart=Never \
  -- -sv http://payments.internal:8080/health

Use the exact endpoint value from your service configuration. Common failures:

• DNS doesn't resolve. The tunnel host can't see your internal DNS zone. On Kubernetes, confirm the service name and namespace. On ECS, check that service discovery is configured for the tunnel's task.
• The connection times out. A security group, network ACL, or firewall rule blocks traffic from the tunnel to the backend. The tunnel's host needs egress to your backend's port.
• The connection is refused. The backend isn't listening on that host and port, or it binds only to localhost. A backend bound to 127.0.0.1 isn't reachable from a separate container or host.
• TLS fails. If the endpoint uses https with an internal certificate authority, the tunnel must trust that certificate authority. Use http for internal traffic that's already isolated, or contact support to discuss certificate options.

Check the gateway side

If the tunnel reaches your backend directly but requests through the gateway still fail, the problem is in your Zuplo project rather than the tunnel:

• Confirm the route's rewrite URL or fetch call uses the service:// scheme, not an internal hostname. Your gateway can't resolve internal DNS names directly.
• If the URL comes from an environment variable, confirm the variable is set in the environment you're testing and holds the full service:// prefix.
• Check your gateway logs for the actual error status and message.

Get help

If you've worked through these checks and traffic still doesn't arrive, contact Zuplo support. Include:

• Your tunnel ID.
• The output of zuplo tunnel describe and zuplo tunnel services describe.
• Tunnel logs at debug level covering a failed request.
• The service:// URL your gateway calls and the environment you called it from.