TCP monitors

Checking that a TCP port accepts a connection.

Purpose

A TCP monitor checks that a specific port on a host accepts a connection. It says nothing about the protocol spoken on that port — only that something is listening and willing to complete the TCP handshake.

Use cases

A database, message queue, or other service with no HTTP interface of its own.
Confirming a specific port stays open and accepts connections. This is the monitor's only supported semantic: it asserts that a port is open and accepting, never that a port is correctly closed or filtered. A deliberately closed or filtered port produces the same DOWN result (tcp_refused or tcp_timeout) as a genuinely broken service, so pointing a TCP monitor at a port that is supposed to stay closed produces incidents rather than confirming the policy; monitoring that a port stays closed needs a different supported semantic than this monitor type has.
A quick reachability check for a service whose protocol handshake is expensive to perform, when connection acceptance alone is the signal that matters.

Configuration

Required:

Target — a bare host: a hostname or an IP address literal (including IPv6). It is never a URL and never a host:port pair — the host and the port are two separate fields, because the colon in a host:port string would be ambiguous with an IPv6 address's own colons.
Port — 1 through 65535.
Interval and timeout — see Concepts: states.

Defaults

None beyond the interval and timeout every monitor type shares; the port has no default and must be stated.

Validation

The target must be non-blank, 255 characters or fewer, and must not contain any of / \ (space) tab CR LF ? # @. A target that parses as an IP literal (IPv4 or IPv6) is accepted as it stands; anything else containing a colon is refused, since a colon in a hostname is otherwise always a mistake rather than an address. The port must be between 1 and 65535.

Probe behavior

The probe attempts a TCP connection to the target and port within the monitor's timeout, then closes the connection without sending or expecting any protocol data.

Success

The check is UP when the connection completes within the timeout.

Failure

A failed TCP check states one of these causes:

Cause	Meaning
`invalid_target`	The probe could not even form a connection attempt from the configuration — an invalid host or an invalid port.
`dns`	The target did not resolve.
`tcp_refused`	The host answered, and refused the connection — nothing is listening on that port.
`tcp_unreachable`	The host or an intermediate network could not be reached at all.
`tcp_timeout`	The connection neither completed nor was refused within the timeout.
`network`	The connection attempt failed for a reason other than refusal, unreachability, or timeout.

tcp_refused and tcp_timeout are different operational facts and are kept separate rather than folded into one generic failure: a refused connection means something is there and answering "no," while a timeout means nothing answered at all — a distinction that matters when deciding whether a service crashed or a network path is broken.

Evidence

A check result records the cause if it failed and the connection latency if it succeeded.

Latency interpretation

Latency is the time to complete the TCP handshake — it says nothing about how quickly the service behind the port would respond to an actual request, only how quickly it accepts a connection.

Consensus interaction

A TCP monitor's states, and how its assigned nodes' observations become one published state, follow the same rules every monitor type does — see Concepts: consensus.

Common mistakes

Writing the target as host:port — refused; the port is its own field.
Expecting a TCP monitor to validate anything about the protocol on the port — it validates only that a connection was accepted, nothing about what the service says once connected.

Troubleshooting

Result is tcp_refused but the service is running — confirm the service is actually bound to the port and host you configured, and that a firewall between the probing node and the target is not itself answering with a refusal on the service's behalf.
Result is tcp_timeout from some nodes and not others — this is a per-node network path fact; see Enrolling nodes for how placement spreads a monitor's assigned nodes, and treat a node-specific timeout as a network path issue for that node rather than the target being down.

Security and network considerations

The probe runs from the nodes assigned to the monitor, so it opens a TCP connection to the target from wherever those nodes are, exactly as any other client at that node's network location would. A monitor cannot see through a firewall it does not have a route through: consistent tcp_unreachable results from every assigned node are as likely to describe network policy as they are to describe the target host.

Example

target: db.internal.example.com
port: 5432
interval_seconds: 60
timeout_seconds: 5

TLS monitors — for a port that also terminates TLS and whose certificate lifetime matters.
ICMP monitors — for basic host reachability apart from any one port.
Concepts: states

This article is part of this repository and is served by the same binary, so what you read here is the documentation for the version you are running.