# 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](/monitors/certificates). 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

| Setting | Values | Default |
|---|---|---|
| **Target** | `host:port` | |
| **TLS** | **None** or **TLS** | **None** |
| **Connection timeout** | 1 to 60 seconds, for the TCP connection only | The value of **Timeout** |
| **Banner keyword** | Up to 255 characters | Empty |
| **Invert keyword check** | On or off | Off |
| **Allow invalid certificates** | On or off. Only with **TLS**. | Off |

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`.