<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/collectors/network-viewer.plugin/integrations/network_connections.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/collectors/network-viewer.plugin/metadata.yaml"
sidebar_label: "Network Connections"
learn_status: "Published"
learn_rel_path: "Collecting Metrics/Collectors/Networking"
keywords: ['network', 'connections', 'sockets', 'tcp', 'udp', 'ports', 'freebsd', 'macos']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE COLLECTOR'S metadata.yaml FILE"
endmeta-->

# Network Connections


<img src="https://netdata.cloud/img/network.svg" width="150"/>


Plugin: network-viewer.plugin
Module: network-viewer.plugin

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## Overview



This plugin reads the system's socket tables to enumerate all active network connections,
including TCP and UDP sockets in all states, for both IPv4 and IPv6.

On Linux it consumes `NETLINK_INET_DIAG` and the `/proc` socket tables;
on FreeBSD it walks `KERN_PROC_FILEDESC` and consults `net.inet.tcp.pcblist`
to attribute sockets to processes.
On macOS it walks process file descriptors with `libproc` and reads socket
metadata with `PROC_PIDFDSOCKETINFO`. A non-privileged or TCC-restricted
macOS run can omit protected processes; the plugin logs a warning when
permission-denied socket data or truncated process/socket list reads make
results incomplete.


This collector is only supported on the following platforms:

- Linux
- FreeBSD
- macOS

This collector only supports collecting metrics from a single instance of this integration.

The plugin needs privileged access to enumerate all process sockets. On macOS,
non-privileged or TCC-restricted runs can omit protected processes; the plugin
logs a warning when permission-denied socket data or truncated process/socket
list reads make results incomplete.
Grant the Netdata plugin its normal privileged permissions and Full Disk Access
when local policy requires it.


### Default Behavior

#### Auto-Detection

The plugin automatically detects all active network connections on the system.


#### Limits

The default configuration for this integration does not impose any limits on data collection.

#### Performance Impact

On macOS, the current established TCP count for `network-protocols` comes
from a cached live socket inventory because macOS does not expose a cheap
per-state TCP counter equivalent to FreeBSD's `net.inet.tcp.states`.
The cache is held for the Function response update window. Busy hosts
with many processes and file descriptors can make that path heavier than
the FreeBSD and Linux implementations.


## Setup


### Prerequisites

No action required.

### Configuration

#### Options

Optional APPS_LOOKUP cache-warming controls for topology and aggregated network-connection Functions.

<details open><summary>Config options</summary>



| Option | Description | Default | Required |
|:-----|:------------|:--------|:---------:|
| apps lookup cache size | Maximum number of per-PID APPS_LOOKUP cache entries kept by network-viewer.plugin. | 8192 | no |


</details>



#### via File

The configuration file name for this integration is `netdata.conf`.
Configuration for this specific integration is located in the `[plugin:network-viewer]` section within that file.

The file format is a modified INI syntax. The general structure is:

```ini
[section1]
    option1 = some value
    option2 = some other value

[section2]
    option3 = some third value
```
You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

```bash
cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config netdata.conf
```

##### Examples

###### APPS_LOOKUP cache warming

Keep the default APPS_LOOKUP cache size.

<details open><summary>Config</summary>

```yaml
[plugin:network-viewer]
  apps lookup cache size = 8192

```
</details>



## Alerts

There are no alerts configured by default for this integration.



## Metrics

Metrics grouped by *scope*.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.




### Per network-viewer plugin IPC

network-viewer.plugin APPS_LOOKUP client cache-warming health and latency.

This scope has no labels.

Metrics:

| Metric | Description | Dimensions | Unit |
|:------|:------------|:----------|:----|
| netdata.collector.ipc.apps_lookup.client.requests | APPS_LOOKUP client request outcomes | requests_sent, requests_responded, requests_failed | requests/s |
| netdata.collector.ipc.apps_lookup.client.cache | APPS_LOOKUP client cache outcomes | cache_hits, cache_misses_unknown, cache_misses_intake_dropped, cache_evictions_pid_reuse, cache_evictions_lru | events/s |
| netdata.collector.ipc.apps_lookup.client.peer | APPS_LOOKUP client peer connection events | peer_connect_attempts, peer_disconnects | events/s |
| netdata.collector.ipc.apps_lookup.client.worker_request_duration_ms | APPS_LOOKUP worker request duration buckets | le_1ms, le_5ms, le_10ms, le_50ms, le_100ms, le_500ms, le_1000ms, gt_1000ms | requests/s |
| netdata.collector.ipc.apps_lookup.client.function_handler_overhead_ms | APPS_LOOKUP Function handler cache-check and intake-enqueue overhead buckets | le_1ms, le_5ms, le_10ms, le_50ms, le_100ms, le_500ms, le_1000ms, gt_1000ms | calls/s |
| netdata.collector.ipc.apps_lookup.client.intake_depth | APPS_LOOKUP client queued PIDs awaiting worker lookup | intake_depth | pids |



## Live Data

This plugin exposes real-time functions for viewing active network connections and,
on FreeBSD and macOS, system-wide TCP and UDP stack statistics.


### Network Connections

Shows active network connections with protocol details, states, addresses, ports, and performance metrics.

Provides both aggregated and detailed views of TCP and UDP connections for IPv4 and IPv6,
including connection direction (listen, inbound, outbound), process information,
cgroup/container/service enrichment when available, and TCP performance metrics (RTT, retransmissions)
on platforms that expose those TCP details.

On Linux, connections are classified as system or container based on network namespace.
On FreeBSD, namespaces are not exposed to userspace and the classification is omitted.
On macOS, Linux-style namespaces and cgroups are not exposed by the host APIs; sockets
are host/system scoped and container/service identity falls back to process identity.
Non-privileged macOS runs may omit protected processes and log a warning when
permission-denied socket data or truncated process/socket list reads make results
incomplete.


| Aspect | Description |
|:-------|:------------|
| Name | `Network-viewer.plugin:network-connections` |
| Require Cloud | no |
| Performance |  |
| Security |  |
| Availability |  |

#### Prerequisites

No additional configuration is required.

#### Parameters

This function has no parameters.

#### Returns



| Column | Type | Unit | Visibility | Description |
|:-------|:-----|:-----|:-----------|:------------|

### Network Protocols

Shows FreeBSD and macOS TCP and UDP stack statistics grouped by transport protocol.

Each row covers one transport (TCP or UDP) and reports IPv4+IPv6 combined
traffic counters (received, sent, errors), TCP-specific connection counters
(active opens, currently established, passive opens, resets, total segments,
retransmitted segments), and the UDP-specific datagrams-with-no-port counter.

Values are per-second deltas sampled from `net.inet.tcp.stats` and
`net.inet.udp.stats`. The current established TCP count comes from
`net.inet.tcp.states` on FreeBSD and from cached live socket inventory on macOS.
Busy macOS hosts with many processes and file descriptors can make that inventory
path heavier than the FreeBSD counter path.
The first call after the plugin starts returns zeros for delta counters because
there is no previous sample to diff against.


| Aspect | Description |
|:-------|:------------|
| Name | `Network-viewer.plugin:network-protocols` |
| Require Cloud | no |
| Performance |  |
| Security |  |
| Availability | FreeBSD and macOS. |

#### Prerequisites

No additional configuration is required.

#### Parameters

This function has no parameters.

#### Returns



| Column | Type | Unit | Visibility | Description |
|:-------|:-----|:-----|:-----------|:------------|

### Network Connections Topology

Shows active network connections as a topology graph with self, process or container, and endpoint actors.

The group_by selector controls the actor level. process_name groups sockets by process name, pid shows
one actor per PID with scalar per-PID information, and container groups sockets by canonical
container_name. For systemd services, container_name is the service name. For non-container,
non-service processes, container_name falls back to the process name. Unresolved cgroup
namespace-relative paths remain pending or process fallback identities instead of being
displayed as raw `cri-containerd-*.scope` systemd scope names.

Fields that can vary across grouped processes, such as PID, UID, network namespace, command line,
cgroup path, and detailed container metadata, are scalar columns in group_by:pid and merged actor
labels in grouped views. Free-form labels are hidden by default and can be allowed per request with
`labels:<pattern>`, where patterns are pipe-separated. Actor modals also expose producer-declared
Processes and CGroups tables for the selected actor.


| Aspect | Description |
|:-------|:------------|
| Name | `Network-viewer.plugin:topology:network-connections` |
| Require Cloud | no |
| Performance | group_by:container performs APPS_LOOKUP cache reads to derive canonical container_name; cache warming runs asynchronously. |
| Security | Free-form labels are denied by default. Raw cgroup paths may expose operator-chosen path segments and are hidden in table views by default. |
| Availability | container_name uses APPS_LOOKUP data when available, keeps retry-later lookups pending, and falls back to process name for host/root, permanently unknown, and unresolved namespace-relative cgroup cases. |

#### Prerequisites

No additional configuration is required.

#### Parameters

| Parameter | Type | Description | Required | Default | Options |
|:---------|:-----|:------------|:--------:|:--------|:--------|
| Group By | select | Use group_by:process_name, group_by:pid, or group_by:container to select the topology actor level. | no | process_name | process_name (default), pid, container |
| Labels | string | Optional pipe-separated simple-pattern whitelist for free-form actor labels. Omitted means deny all free-form labels. | no |  |  |

#### Returns

Topology payload using netdata.topology.v1.

| Column | Type | Unit | Visibility | Description |
|:-------|:-----|:-----|:-----------|:------------|
| container_name | string |  |  | Canonical container/service actor name used by group_by:container. |
| cgroup_path | string |  |  | Full cgroup path; scalar in group_by:pid and merged as actor labels in grouped views. |
| cgroup_name | string |  |  | Cgroup or container display name; scalar in group_by:pid and merged as actor labels in grouped views. |
| cgroup_status | string |  |  | Cgroup enrichment status: known, host_root, retry_later, unknown_permanent, or unknown. |
| orchestrator | string |  |  | Container/orchestrator family; scalar in group_by:pid and merged as actor labels in grouped views. |
| k8s_pod_name | string |  |  | Kubernetes pod name; scalar in group_by:pid and merged as actor labels in grouped views. |
| k8s_namespace | string |  |  | Kubernetes namespace; scalar in group_by:pid and merged as actor labels in grouped views. |
| k8s_workload | string |  |  | Kubernetes controller name; scalar in group_by:pid and merged as actor labels in grouped views. |
| docker_container_name | string |  |  | Kubernetes container, Docker/Podman container, or cgroup fallback name; scalar in group_by:pid and merged as actor labels in grouped views. |
| docker_image | string |  |  | Docker/Podman image label; scalar in group_by:pid and merged as actor labels in grouped views. |
| systemd_unit_name | string |  |  | systemd unit name; scalar in group_by:pid and merged as actor labels in grouped views. |
| systemd_unit_kind | string |  |  | systemd unit kind such as service, scope, or slice; scalar in group_by:pid and merged as actor labels in grouped views. |
| actor_kind | string |  |  | Producer-derived actor kind used to classify containers, services, slices, scopes, VMs, and process fallbacks. |
