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
This is the beginning of the README. Read the rest at the original. Read the full README ↗
