Prototype: network_connections()

Return type: data

Description: Return the list of current network connections.

The returned data container has four keys:

  • tcp has all the TCP connections over IPv4
  • tcp6 has all the TCP connections over IPv6
  • udp has all the UDP connections over IPv4
  • udp6 has all the UDP connections over IPv6

Under each key, there's an array of connection objects that all look like this:

code
{
  "local": {
    "address": "...source address...",
    "port": "...source port..."
  },
  "remote": {
    "address": "...remote address...",
    "port": "...remote port..."
  },
  "state": "...connection state..."
}

The address will be either IPv4 or IPv6 as appropriate. The port will be an integer stored as a string. The state will be a string like UNKNOWN.

Note: This function is supported on Linux.

On Linux, usually a state of UNKNOWN and a remote address 0.0.0.0 or 0:0:0:0:0:0:0:0 with port 0 mean this is a listening IPv4 and IPv6 server. In addition, usually a local address of 0.0.0.0 or 0:0:0:0:0:0:0:0 means the server is listening on every IPv4 or IPv6 interface, while 127.0.0.1 (the IPv4 localhost address) or 0:100:0:0:0:0:0:0 means the server is only listening to connections coming from the same machine.

A state of ESTABLISHED usually means you're looking at a live connection.

On Linux, all the data is collected from the files /proc/net/tcp, /proc/net/tcp6, /proc/net/udp, and /proc/net/udp6.

Example:

code
vars:
  "connections" data => network_connections();

Output:

The SSH daemon:

code
{
  "tcp": [
   {
     "local": {
       "address": "0.0.0.0",
       "port": "22"
     },
     "remote": {
       "address": "0.0.0.0",
       "port": "0"
     },
     "state": "UNKNOWN"
   }
 ]
}

The printer daemon listening only to local IPv6 connections on port 631:

code
 "tcp6": [
   {
     "local": {
       "address": "0:100:0:0:0:0:0:0",
       "port": "631"
     },
     "remote": {
       "address": "0:0:0:0:0:0:0:0",
       "port": "0"
     },
     "state": "UNKNOWN"
   }
]

An established connection on port 2200:

code
 "tcp": [
  {
    "local": {
      "address": "192.168.1.33",
      "port": "2200"
    },
    "remote": {
      "address": "1.2.3.4",
      "port": "8533"
    },
    "state": "ESTABLISHED"
  }
]

History: Introduced in CFEngine 3.9

See also: sys.inet, sys.inet6.