TCP Port

The TCP Port check opens a TCP connection from the agent device to one or more targets and measures how long the connection takes to establish. Use it to see whether a service such as a mail, web, or database server is reachable on its port and responds quickly enough. The check sends no data and does not inspect a protocol response; it only checks whether the port accepts a connection. It runs on Windows, Linux, and macOS (each in x64 and Arm64 builds) every 5 minutes by default; the interval is not user-configurable.

Prerequisites

• The device that runs the check needs a connected octoja agent.
• The targets must be reachable from that device. Firewalls along the way must allow outbound connections to the relevant port.

Steps

1. Open the device.
2. Go to the Checks tab and click Add Check → TCP Port.
3. Enter the endpoints to probe under Targets (host:port) and adjust the thresholds if needed.

To roll the check out to many devices, use a config package: Assign checks with config packages.

Settings

Thresholds

• The check splits host and port at the last colon in the entry.
• If Warning connect time (ms) is greater than Error connect time (ms), the check swaps the two values before evaluation.
• If Timeout (ms) is lower than Error connect time (ms), the connection attempt is cancelled first and the target becomes Critical because of the timeout.
• Up to ten targets are probed in parallel.

Results

Each target is graded on its own. The check's overall result is the worst result across all targets.

If Targets (host:port) contains no non-blank entry at all, the check reports Warning.

The check collects:

• Host and port per target
• Whether the connection was established
• Connect time in milliseconds
• Failure reason per target: invalid target, timeout, or connection refused or unreachable

Related articles

• Set up alerts for a check