Network Connections

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

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.

Config options

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

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:

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

[section2]
    option3 = some third value

You can edit the configuration file using the edit-config script from the Netdata config directory.

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.

Config

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

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	Dimensions	Unit
netdata.collector.ipc.apps_lookup.client.requests	requests_sent, requests_responded, requests_failed	requests/s
netdata.collector.ipc.apps_lookup.client.cache	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	peer_connect_attempts, peer_disconnects	events/s
netdata.collector.ipc.apps_lookup.client.worker_request_duration_ms	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	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	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.