Crate netls 

netls is a network connections viewer for daily use and automation.

This crate exposes the same functionality as the netls CLI tool through a programmatic API. The entry points are snapshot (gathered with a Filter) and the various enrich_* functions that populate optional fields on each Connection.

Re-exports

pub use dns::resolve_dns;

Modules

dns

Reverse-DNS resolution helpers.

docker

Docker container metadata for connection enrichment.

output

Output renderers (table, JSON, CSV, summary, grouped).

platform

Per-platform connection collection (Linux /proc, macOS libproc).

services

Well-known port → service-name lookups (/etc/services plus a builtin map).

tui

Interactive --tui mode.

tui_common

Shared helpers used by both --tui and --watch modes.

watch

Live --watch mode (refresh + diff).

Structs

Connection

A single network connection.

Filter

Builder-style filter for snapshot.

Summary

Aggregated counts of connections by protocol and TCP state. Returned by summary.

Enums

Error

Errors returned by netls library functions.

Proto

Transport protocol of a connection.

State

TCP connection state. Mirrors the standard TCP state machine (RFC 793). Only meaningful for Proto::Tcp.

Constants

NO_PERMISSION

Displayed when a connection’s process/PID cannot be read (insufficient privileges).

Functions

compact_addr

Replace verbose IPv6 addresses with human-friendly aliases. [::1]:port → localhost:port, [::]:port / [0:…:0]:port → *:port

diff_connections

Compute the diff between two connection snapshots.

enrich_age

Populate age_secs for each connection by reading the mtime of the socket fd in /proc/<pid>/fd/. Uses the stored inode to find the exact fd symlink. Linux only - no clean equivalent on macOS.

enrich_cmdline

Populate cmdline field for each connection. On Linux: reads /proc/<pid>/cmdline (full args joined with spaces). On macOS: uses pidpath() to get the full binary path.

enrich_fd

Populate fd_usage for each connection: (open_fds, soft_limit). On Linux: reads /proc/<pid>/fd/ and /proc/<pid>/limits. On macOS: uses listpidinfo::<ListFDs> and getrlimit.

enrich_process_tree

Populate parent_chain for each connection. On Linux: walks PPid links in /proc/<pid>/status. On macOS: uses BSDInfo.pbi_ppid via libproc. Result format: “parent <- grandparent <- …” (up to 4 levels).

enrich_systemd

Populate systemd_unit for each connection from /proc/<pid>/cgroup. Extracts the last path component ending in “.service”, “.scope”, or “.slice”. Not applicable on macOS (uses launchd).

fmt_age

Format age in seconds as a human-readable string: “5s”, “3m12s”, “2h34m”, “1d3h”.

format_process_text

Format the process column text, including proxy chain info when available.

resolve_docker_name

If the process is docker-proxy, resolve the container IP from its cmdline and return a label like "docker-proxy (frontend)". Returns None if not applicable or resolution fails.

resolve_proxy_origins

For each external connection that passes through a local proxy, return the name of the real originating process.

snapshot

Return a snapshot of current network connections, optionally filtered.

snapshot_all

Return all connections without any filtering. Used internally for proxy chain analysis which needs the full picture.

snapshot_with_containers

Collect connections from inside all running Docker containers. Appends to an existing slice (pass host connections to merge them). Linux only - Docker runs in a VM on macOS; namespace trick does not apply.

sort_connections

Sort connections by the given column name. Valid values: “proto”, “local”, “remote”, “state”, “pid”, “process”, “port”. Unknown column - no-op.

summary

Return a summary of connections grouped by proto and state.

top_connections

Return top N processes by connection count. Each entry: (process_name, count).

Type Aliases

Result

Convenience alias for std::result::Result<T, netls::Error>.