Skip to content

Check network-connections

Overview

Counts system-wide socket connections by type (TCP, TCP6, UDP, UDP6) and state. Output is grouped by connection type and status, ordered by the number of connections (descending). Useful for detecting connection leaks or applications that do not properly close sockets.

Important Notes:

Meaning of connection type --conn-type parameter:

  • tcp: TCP over IPv4
  • tcp6: TCP over IPv6
  • udp: UDP over IPv4
  • udp6: UDP over IPv6

Meaning of connection status --conn-status parameter:

  • CLOSE: Closed. The socket is not being used.
  • CLOSE_WAIT: Remote shutdown; waiting for the socket to close - means the other end of the connection has been closed while the local end is still waiting for the application to close.
  • CLOSING: Closed, then remote shutdown; awaiting acknowledgment.
  • ESTABLISHED: Connection has been established.
  • FIN_WAIT_1: Socket closed; shutting down connection.
  • FIN_WAIT_2: Socket closed; waiting for shutdown from remote.
  • IDLE: Idle, opened but not bound.
  • LAST_ACK: Remote shutdown, then closed; awaiting acknowledgment.
  • LISTEN: Listening for incoming connections.
  • NONE: For UDP sockets this is always going to be "None".
  • SYN_RECV: Active/initiate synchronization received and the connection under way.
  • SYN_SENT: Actively trying to establish connection.
  • TIME_WAIT: Wait after close for remote shutdown retransmission.

Data Collection:

  • Uses psutil.net_connections() to enumerate all system-wide network connections
  • Connections can be filtered by --conn-type (tcp, tcp6, udp, udp6) and --conn-status (established, listen, close_wait, etc.)

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/network-connections
Nagios/Icinga Check Name check_network_connections
Check Interval Recommendation Every minute
Can be called without parameters Yes
Runs on Cross-platform
Compiled for Windows Yes
3rd Party Python modules psutil

Help

usage: network-connections [-h] [-V]
                           [--conn-status {all,close,close_wait,closing,established,fin_wait1,fin_wait2,last_ack,listen,none,syn_recv,syn_sent,time_wait}]
                           [--conn-type {all,tcp,tcp6,udp,udp6}] [-c CRIT]
                           [--test TEST] [-w WARN]

Counts system-wide socket connections by type (TCP, TCP6, UDP, UDP6) and
state. Alerts when the total number of connections in a specific state exceeds
the configured thresholds. Useful for detecting connection leaks or
applications that do not properly close sockets.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit
  --conn-status {all,close,close_wait,closing,established,fin_wait1,fin_wait2,last_ack,listen,none,syn_recv,syn_sent,time_wait}
                        Filter connections by status. Can be specified
                        multiple times. Default: None
  --conn-type {all,tcp,tcp6,udp,udp6}
                        Filter connections by family/type. Can be specified
                        multiple times. Default: None
  -c, --critical CRIT   CRIT threshold for the number of connections. Default:
                        None
  --test TEST           For unit tests. Needs "path-to-stdout-file,path-to-
                        stderr-file,expected-retc".
  -w, --warning WARN    WARN threshold for the number of connections. Default:
                        None

Usage Examples

Just get network statistics and do not alert on anything:

./network-connections

Output:

tcp ESTABLISHED: 19, udp NONE: 16, tcp LISTEN: 9, udp6 NONE: 5, tcp CLOSE WAIT: 4, tcp6 LISTEN: 4, tcp TIME WAIT: 1, tcp6 CLOSE WAIT: 1

Alert if number of established TCP (v4) connections is higher than 200:

./network-connections --conn-type=tcp --conn-status=established --warning=200

Output:

tcp ESTABLISHED: 260 [WARNING]

Alert if number of any established connection is not between 30 and 40:

./network-connections --conn-type=all --conn-status=established --warning=30:40

Output:

tcp ESTABLISHED: 26 [WARNING]

Use repeating parameter:

./network-connections --conn-type=tcp6 --conn-status=established --conn-status=closing --warning=30:40

Output:

No connections of type "tcp6" in status "established,closing" found.

States

  • OK if no thresholds are configured, or if all connection counts are within the given ranges.
  • WARN or CRIT if the number of connections found does not fit into the given ranges.

Perfdata / Metrics

Depends on your connections. <prefix> represents the status of a tcp or tcp6 connection. For UDP sockets this is always going to be udp_NONE / udp6_NONE.

Name Type Description
\<prefix>_BOUND Number Solaris only
\<prefix>_CLOSE Number
\<prefix>_CLOSE_WAIT Number
\<prefix>_CLOSING Number
\<prefix>_DELETE_TCB Number Windows only
\<prefix>_ESTABLISHED Number
\<prefix>_FIN_WAIT1 Number
\<prefix>_FIN_WAIT2 Number
\<prefix>_IDLE Number Solaris only
\<prefix>_LAST_ACK Number
\<prefix>_LISTEN Number
\<prefix>_NONE Number
\<prefix>_SYN_RECV Number
\<prefix>_SYN_SENT Number
\<prefix>_TIME_WAIT Number

Credits, License