Pktvisor
pktvisor is a dynamic network observability agent that smartly analyzes network traffic and generates opentelemetry metrics
Install / Use
/learn @netboxlabs/PktvisorREADME
What is pktvisor?
pktvisor (pronounced "packet visor") is an observability agent for analyzing high volume, information dense network data streams and extracting actionable insights directly from the edge while integrating tightly with modern observability stacks.
It is resource efficient and built from the ground up to be modular and dynamically controlled in real time via API and YAML policies. Input and analyzer modules may be dynamically loaded at runtime. Metric output can be used and visualized both on-node via command line UI (for localized, hyper real-time actions) as well as centrally collected into industry standard observability stacks like Prometheus and Grafana..
The input stream system is designed to tap into data streams. It currently supports packet capture, dnstap, sFlow and Netflow/IPFIX and will soon support additional taps such as envoy taps, and eBPF.
The stream analyzer system includes full application layer analysis, and efficiently summarizes to:
- Counters
- Histograms and Quantiles
- Timers and Rates
- Heavy Hitters/Frequent Items/Top N
- Set Cardinality
- GeoIP/ASN
Please see the list of current metrics or the sample metric output.
pktvisor has its origins in observability of critical internet infrastructure in support of DDoS protection, traffic engineering, and ongoing operations.
These screenshots display both the command line and centralized views of the Network and DNS stream processors, and the types of summary information provided:
Get Started
Docker
One of the easiest ways to get started with pktvisor is to use
the public docker image. The image contains the collector
agent (pktvisord), the command line UI (pktvisor-cli) and the pcap and dnstap file analyzer (pktvisor-reader). When running
the container, you specify which tool to run.
- Pull the container
docker pull netboxlabs/pktvisor
or use netboxlabs/pktvisor:latest-develop to get the latest development version.
- Start the collector agent
This will start in the background and stay running. Note that the final two arguments select pktvisord agent and
the eth0 ethernet interface for packet capture. You may substitute eth0 for any known interface on your device.
Note that this step requires docker host networking to observe traffic outside the container, and
that currently only Linux supports host networking:
docker run --net=host -d netboxlabs/pktvisor pktvisord eth0
If the container does not stay running, check the docker logs output.
- Run the command line UI
After the agent is running, you can observe results locally with the included command line UI. This command will run the
UI (pktvisor-cli) in the foreground, and exit when Ctrl-C is pressed. It connects to the running agent locally using
the built in REST API.
docker run -it --rm --net=host netboxlabs/pktvisor pktvisor-cli
Linux Static Binary (AppImage, x86_64)
You may also use the Linux all-in-one binary, built with AppImage, which is available for download on the Releases page. It is designed to work on all modern Linux distributions and does not require installation or any other dependencies.
curl -L http://pktvisor.com/download -o pktvisor-x86_64.AppImage
chmod +x pktvisor-x86_64.AppImage
./pktvisor-x86_64.AppImage pktvisord -h
For example, to run the agent on ethernet interface eth0:
./pktvisor-x86_64.AppImage pktvisord eth0
The AppImage contains the collector agent (pktvisord), the command line UI (pktvisor-cli) and the pcap and dnstap file
analyzer (pktvisor-reader). You can specify which tool to run by passing it as the first argument:
For example, to visualize the running agent started above with the pktvisor command line UI:
./pktvisor-x86_64.AppImage pktvisor-cli
Note that when running the AppImage version of the agent, you may want to use the -d argument to daemonize (run in the
background), and either the --log-file or --syslog argument to record logs.
Also see Advanced Agent Example.
Linux Static Binaries (Stand Alone, x86_64)
Finally, pktvisor also provides statically linked, dependency free Linux binaries for each individual pktvisor tool (pktvisord, pktvisor-cli and pktvisor-reader). These are the smallest, most compact versions of the binaries.
pktvisord:
curl -L http://pktvisor.com/download/pktvisord -o pktvisord-x86_64
chmod +x pktvisord-x86_64
./pktvisord-x86_64 -h
pktvisor-cli:
curl -L http://pktvisor.com/download/cli -o pktvisor-cli-x86_64
chmod +x pktvisor-cli-x86_64
./pktvisor-cli-x86_64 -h
pktvisor-reader:
curl -L http://pktvisor.com/download/reader -o pktvisor-reader-x86_64
chmod +x pktvisor-reader-x86_64
./pktvisor-reader-x86_64 -h
Other Platforms
We are working on support for additional operating systems, CPU architectures and packaging systems. If you do not see your binary available, please see the Build section below to build your own.
If you have a preferred installation method that you would like to see support for, please create an issue.
Execute Pktvisord binary without root
Pktvisord uses libpcap to capture PCAP from the desired interface. To do so, it needs system network capture permissions.
You are able to authorize those specific requirements only once and then be able to run the binary without sudo.
sudo setcap cap_net_raw,cap_net_admin=eip /<full_path>/pktvisord-x86_64
Docs
Agent Usage
Current command line options are described with:
docker run --rm netboxlabs/pktvisor pktvisord --help
or
./pktvisor-x86_64.AppImage pktvisord --help
Usage:
pktvisord [options] [IFACE]
pktvisord (-h | --help)
pktvisord --version
pktvisord summarizes data streams and exposes a REST API control plane for configuration and metrics.
pktvisord operation is configured via Taps and Collection Policies. Taps abstract the process of "tapping into"
input streams with templated configuration while Policies use Taps to instantiate and configure Input and Stream
Handlers to analyze and summarize stream data, which is then made available for collection via REST API.
Taps and Collection Policies may be created by passing the appropriate YAML configuration file to
--config, and/or by enabling the admin REST API with --admin-api and using the appropriate endpoints.
Alternatively, for simple use cases you may specify IFACE, which is either a network interface, an
IP address (4 or 6), or "auto". If this is specified, "default" Tap and Collection Policies will be created with
a "pcap" input stream on the specified interfaced, along with the built in "net", "dns", and "pcap"
Stream Handler modules attached. If "auto" is specified, the most used ethernet interface will be chosen.
Note that this feature may be deprecated in the future.
For more documentation, see https://pktvisor.dev
Base Options:
-d Daemonize; fork and continue running in the background [default: false]
-h --help Show this screen
-v Verbose log output
--no-track Don't send lightweight, anonymous usage metrics
--version Show version
Web Server Options:
-l HOST Run web server on the given host or IP (default: localhost)
-p PORT Run web server on the given port (default: 10853)
--tls Enable TLS on the web server
--tls-cert FILE Use given TLS cert. Required if --tls is enabled.
--tls-key FILE Use given TLS private key. Required if --tls is enabled.
--admin-api Enable admin REST API giving complete control plane functionality [default: false]
