Listening services

To allow agents to tunnel SSH connections over different transports, the server must expose the corresponding service, then decapsulate the traffic and forward it to the SSHD server.

Quick choice

Enable only the listeners required by the agent transport order:

SSH

No encapsulation, directly exposed.

Configuration

• --sshd-listen-addr: The address the SSHD server will listen to. Format: [IP]:[PORT].

TLS

Configuration

• --https-listen-addr: the address the TLS server will listen to. Format: [IP]:[PORT].
• --http-domain: the domain(s) on which the web server will respond (accepts a comma-separated list of multiple domains).
• --tls-domain: the domain(s) on which the SSH over TLS listener will respond (accepts a comma-separated list of multiple domains).
• --tls/--no-tls: Enable/Disable the TLS listener. Note that it impacts both the HTTPS web server and the SSH over TLS listener.

TLS keys

The server allows two ways of providing the TLS certificate:

• Either provide a custom certificate
  • --tls-key: path to the TLS certificate key
  • --tls-cert: path to the TLS certificate
• Let the server handle the certificate:
  • --letsencrypt-email: the mail used by the ACME protocol

QUIC

Configuration

• --quic-listen-addr: the address the QUIC server will listen to. Format: [IP]:[PORT].
• --quic/--no-quic: Enable/Disable the QUIC listener. Requires --tls to also be enabled: the QUIC listener does not start otherwise.

HTTP

Configuration

• --http-listen-addr: the address the plain HTTP server (serving both the HTTP and WebSocket transports) will listen to. Format: [IP]:[PORT].

SSH over HTTP is available at: http://[HTTP_DOMAIN]/sshttp/ and https://[HTTP_DOMAIN]/sshttp/

WebSocket

The WebSocket listener is served by the same HTTP server as the HTTP listener above, and shares its --http-listen-addr configuration. There is no separate flag dedicated to the WebSocket listener.

Agent SSH over WebSocket is available at: ws://[HTTP_DOMAIN]/wssh/{agent-id} and wss://[HTTP_DOMAIN]/wssh/{agent-id}.

The operator-facing SSH-over-WebSocket bridge is a separate endpoint, /ssh-ws/, and is enabled with --ssh-websocket. It is protected by the access token and IP allowlist; see Access control.

DNS

The DNS server acts as an authoritative server and responds to DNS queries that match the SSH-over-DNS format.

Configuration

• --dns-listen-addr: DNS server listen address. Use port 53 for compatibility with recursive DNS resolvers.
• --dns-domain: DNS domain for queries. Use the shortest domain possible to maximize throughput.
• --dns/--no-dns: Enable/Disable the DNS listener.

Internal control channel

Agent control traffic uses Socket.IO independently from the SSH data connection. Socket.IO can use HTTP long polling, WebSocket over HTTP(S), or a WebSocket connection encapsulated over DNS. Direct SSH, TLS, and QUIC are SSH data transports; they do not carry Socket.IO by themselves.

For normal HTTP(S) control, expose the HTTP or HTTPS listener. In a DNS-only deployment, enable the DNS listener and configure the agent’s DNS control path.

SSH authentication roles

The shared SSHD accepts two distinct authentication roles:

• Agents authenticate with their registered public key and agent ID. Their connection may request only reverse port forwarding (tcpip-forward and cancellation) plus keepalive messages. Agent-authenticated connections cannot open operator sessions, direct-tcpip channels, or other client features.
• Operators authenticate with the agent’s password and agent name. This is the role used by tealc for SSH sessions, port access, file transfer, proxies, and management operations. The /ssh-ws/ endpoint is only a transport bridge; after it reaches SSHD, the password-authenticated connection is identified as an operator connection in exactly the same way as direct SSH.

The server records the public source IP of agent connections in the agent database. For HTTP/WebSocket transports it uses the HTTP peer address, or a validated X-Forwarded-For value when the peer is listed in --trusted-proxies; raw SSH, TLS, QUIC, and DNS transports use their actual transport peer address. The same address is carried into the SSH connection so registration and connection state report the transport’s real source rather than an internal tunnel or client-ID address.

Flag summary