Troubleshooting on Goauld

Diagnose an agent

Mon, 01 Jan 0001 00:00:00 +0000

Use this checklist when an agent does not appear in the client, repeatedly disconnects, or accepts control traffic but cannot open an SSH session.

1. Check that the server is reachable

Verify the listener used by the agent. For a direct SSH listener:

nc -vz SERVER_HOST 2222

Expected output:

TODO_PLACEHOLDER_HERE

For HTTP or HTTPS, request the server URL from the same network where the agent runs:

curl -I https://SERVER_HOST/

Expected output:

The agent does not appear

Mon, 01 Jan 0001 00:00:00 +0000

An agent must complete its outbound control connection and registration before it appears in tealc list or the TUI.

Check these in order:

Confirm that the process is running on the target machine.
Confirm that the target resolves the configured server hostname.
Test the configured egress port from the target machine.
Confirm that the agent’s public age key matches the server’s private key.
Confirm the server address, port, and access token in the agent build configuration.
Read the agent log for the selected transport and registration error.
Read the server log for a rejected connection or authentication failure.

On the operator workstation, verify that the client is using the same server and access token:

Control works, but SSH fails

Mon, 01 Jan 0001 00:00:00 +0000

If the agent is visible in tealc list but tealc ssh AGENT_NAME fails, the control path is working and the problem is probably in the data path.

Check:

the agent’s SSH service is enabled;
the server SSH listener or ssh-websocket endpoint is enabled;
the client is using the intended --ssh-server or --ws mode;
the agent’s SSH port matches the server configuration; and
the operator IP is allowed by allowed-ips.

Run the client with verbose logging:

The agent repeatedly reconnects

Mon, 01 Jan 0001 00:00:00 +0000

Repeated reconnects usually indicate an unstable egress path, an expired working window, a proxy interruption, or an agent process restart.

Example healthy connection log:

TODO_PLACEHOLDER_HERE

Example reconnect/failure log:

TODO_PLACEHOLDER_HERE

Compare the agent and server logs and check:

heartbeat RTT and timeout messages;
reconnect count and transport failures in metrics;
agent process restarts;
proxy authentication or idle timeout messages;
TLS certificate validity and clock skew; and
working-days and killswitch settings.

Try one transport at a time when isolating the problem. Start with the simplest path available, then test the configured fallback transports. Record which transport remains stable before changing the deployment permanently.