Copy page

Uptime monitors

TCP monitors

A TCP monitor opens a connection to a host and port, for example a database, an SSH server or a message broker. The check passes when the port accepts the connection. You can also make the monitor do a TLS handshake, and look for a keyword in the first data the server sends.

Add a TCP monitor

1. In the sidebar, select Monitors.
2. Select Create monitor.
3. Under Type, select TCP.
4. In Target, enter the host and port, for example db.example.com:5432.
5. Under TLS, select None or TLS.
6. Select Create and start.

The port is required. For an IPv6 address, put the address in brackets: [2001:db8::10]:5432.

What a check does

1. The Spectate checker looks up the host name. It tries the IPv4 addresses first, then the IPv6 addresses, until one accepts the connection.
2. If TLS is TLS, the checker does a TLS handshake and verifies the certificate.
3. If the monitor has a Banner keyword, the checker reads what the server sends and looks for the keyword.

The check fails if any of these is true:

• The host name does not resolve, or resolves to a private or reserved address.
• No address accepts the connection before Connection timeout ends.
• The TLS handshake fails, or the certificate is not valid and Allow invalid certificates is off.
• The banner keyword check fails.
• The check takes longer than Timeout.

The response time covers the DNS lookup, the connection, the TLS handshake and the banner read.

TLS

With TLS set to TLS, the checker starts TLS at the first byte. It verifies the certificate against its trust store and the host name of the target. It uses TLS 1.2 or newer.

Select Allow invalid certificates to count the check as up when the certificate does not verify. Use it for self-signed certificates or an internal certificate authority.

A TCP monitor with TLS can also have certificate checks. They alert before the certificate expires.

Banner keyword

Many servers send a line of text, the banner, after they accept a connection. SSH servers send a line such as SSH-2.0-OpenSSH_9.6. Enter text from that line in Banner keyword, for example SSH-2.0. The match is case-sensitive.

The checker reads up to 4 KiB. It stops reading when the server sends nothing for 500 milliseconds, closes the connection, or the timeout ends. It also stops when it finds the keyword.

Select Invert keyword check to fail the check when the banner contains the keyword.

If the server sends nothing until the client speaks first, leave Banner keyword empty. A keyword check on such a server always fails. The monitor Overview shows the banner of the latest check.

Settings

These settings are in the Connection section of the monitor settings. In the API, they are uri, advanced_settings.tls_mode (none or tls), advanced_settings.connection_timeout, advanced_settings.keyword, advanced_settings.keyword_inverted and allow_insecure_requests.