Netify Netify logo Contact Us
Products Resources Documentation Blog Sign In

Netify Aggregator Plugin

The Aggregator Processor plugin creates structured telemetry by aggregating individual flow records from the Netify Agent's memory. This aggregated data is typically used for high-level dashboards and usage statistics for data centers and SD-WAN aggregation points.

The plugin emits several predefined summary formats (see the Telemetry section). Each format provides aggregated metrics - counts, bytes, and flow totals - plus metadata such as application, protocol, IPs, MACs, ports, VLAN, and interface statistics. Choose the output format with aggregator and route results using sinks .

License

Netify Flow Actions Plugin is a proprietary plugin requiring a license. Please contact us for details.

Installation

Netify plugins are distributed through the same packaging workflow as the Netify Agent, allowing for a consistent installation experience using standard package manager syntax. While pre-compiled binaries are readily available for x86_64 architectures via our public mirrors, support for ARM, MIPS, and other specialized architectures is available upon request. Please contact us for details.

Step 1 - Select your installation target:

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/debian/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/debian/12/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/debian/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/debian/11/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/debian/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/debian/10/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/ubuntu/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/ubuntu/noble/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/ubuntu/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/ubuntu/jammy/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
curl -fsSL https://download.netify.ai/5/ubuntu/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/ubuntu/focal/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/24.10/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
opkg update
opkg install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/23.05/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
opkg update
opkg install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/22.03/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
opkg update
opkg install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/21.02/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
opkg update
opkg install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/19.07/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
opkg update
opkg install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
sudo rpm --import https://download.netify.ai/5/opensuse/15.5/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/opensuse/netify.repo -o /etc/zypp/repos.d/repo-netify.repo

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo zypper update
sudo zypper install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
sudo rpm --import https://download.netify.ai/5/almalinux/9/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/almalinux/9/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
sudo rpm --import https://download.netify.ai/5/almalinux/8/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/almalinux/8/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo apt update
sudo apt install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
sudo rpm --import http://download.netify.ai/5/rockylinux/9/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/rockylinux/9/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo yum update
sudo yum install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
sudo rpm --import http://download.netify.ai/5/rockylinux/8/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/rockylinux/8/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
sudo yum update
sudo yum install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/opnsense/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/opnsense/25.7",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
pkg update
pkg install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/opnsense/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/opnsense/24.7",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
pkg update
pkg install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/freebsd/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/freebsd/15.0",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
pkg update
pkg install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/freebsd/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/freebsd/14.0",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
pkg update
pkg install netify-proc-aggregator

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
× 
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/freebsd/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/freebsd/14.0",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Aggregator:

Terminal - Netify
× 
pkg update
pkg install netify-proc-aggregator

Setup

All plugins are disabled by default, and the Netify Aggregator Processor plugin is no different. Use the --enable-plugin and --disable-plugin parameters to enable/disable the plugin:

Terminal - Netify
× 
netifyd --enable-plugin proc-aggregator
netifyd --disable-plugin proc-aggregator

Alternatively, you can edit /etc/netifyd/plugins.d/10-netify-proc-aggregator.conf and set enable to yes.

Terminal - Netify
× 
[proc-aggregator]
enable = yes
plugin_library = /usr/lib64/libnetify-proc-aggregator.so.0.0.0
conf_filename = ${path_state_persistent}/netify-proc-aggregator.json

Main Configuration

Once the plugin has been enabled, it can be configured using the defined JSON configuration file specified in the plugin loader configuration. Let's look at a configuration sample to review the syntax and parts of the file.

aggregator

integer

Aggregator format type - see the types section for more information.

log_interval

integer

Interval in seconds between aggregate summary reports.

Default
60

privacy_mode

boolean

If true, aggregation will not include breakdowns by MAC address or IP address.

Options
true, false

batched_rows

integer

Limits the number of aggregate records processed in a single batch. For high-volume deployments, set batched_rows to split output into multiple sink payloads. For example, with 1,000 aggregate rows and batched_rows set to 100, the plugin will generate and dispatch 10 sink payloads. This reduces memory and CPU usage for both the Agent and receiving applications. Set batched_rows to zero (default) to process all records in a single payload.

Default
0

nested

boolean

When encoding the aggregated rows into a sink payload, two layout formats are supported: nested and flat (default). In nested mode, the keys that are used for aggregation become the nesting levels.

Default
false
Options
true, false

format

string

Default payload format.

Options
json, msgpack

compressor

string

Default compression policy.

Options
none, gz

sinks

object

An object array of Netify Sink objects

Reference
See Sink Configuration section below

Example Aggregator Plugin Configuration

{
    "aggregator": 1,
    "log_interval": 60,
    "privacy_mode": false,
    "format": "json",
    "compressor": "gz",
    "batched_rows": 0,
    "nested": false,
    "sinks": {
        "sink-log": {
            "default": {
                "format": "json",
                "compressor": "gz"
            }
        }
    }
}

Sink Configuration

We need to send our telemetry to a configured output using a Sink Plugin: log, socket, message queue, etc. This sink configuration is highly flexible, but it can also be easy to misconfigure if the relationships between components are not clear. Let's get started.

Sink Tag - First Level Key

The Aggregator Processor’s sinks object determines which sinks (outputs) receive the telemetry data and how the data should be sent to each one. A single processor can send data to multiple sinks, but in this example it is configured to send to only one.

The sink tag is the first-level key under the sinks property. This key must match the section name defined by the corresponding plugin loader. In our example, the sink tag is sink-log , which must exactly match the loader section name sink-log as shown below:

Sinks Configuration - Overview

"sinks": {
    "sink-log": {
        "aggregate": {
            "enable": true,
            ... other properties ...
        }
    }
}
Terminal - Netify
× 
$ cat /etc/netifyd/plugins.d/10-netify-sink-log.conf
[sink-log]
enable = yes
plugin_library = /usr/lib64/libnetify-sink-log.so.0.0.0
conf_filename = ${path_state_persistent}/netify-sink-log.json

Here we can see that the section name [sink-log] matches the sink tag used in the Aggregator configuration. The presence of this configuration file indicates that the plugin has been installed, and the enable = yes setting confirms that it is currently enabled. The loader configuration also specifies the sink’s runtime configuration file through the conf_filename property.

This mapping is critical: if the names do not match, the processor will not be able to deliver data to the sink.

The Channel - Second Level Key

The second-level key in JSON configuration is the channel. Sink output channels provide a way to separate different types of telemetry into different output targets. For example, you can send:

  • aggregator data to /tmp/netify-aggregate-x
  • interface statistics to /tmp/netify-interface-stats-x
  • intelligence detections to /tmp/netify-intelligence-x

This channel must be configured in the target sink configuration as shown.

Refer to the relevant Sink Plugin configuration for channel configuration details.

Sink Log Config: /etc/netifyd/netify-sink-log.json

{
    "overwrite": false,
    "log_path": "/tmp",
    "channels": {
        "aggregate": {
            "overwrite": true,
            "log_path": "/tmp",
            "log_name": "netify-aggregate-"
        }
    }
}

Channel Properties

{sink-tag}.{channel}.enable

boolean

Flag to enable/disable the channel.

{sink-tag}.{channel}.format

string

The data format - overrides default.

Options
json, msgpack

{sink-tag}.{channel}.compressor

string

The compression policy - overrides default.

Options
none, gz

Example Sinks Configuration

{
    ...
    "sinks": {
        "sink-log": {
            "aggregate": {
                "enable": true,
                "format": "json",
                "compressor": "none"
            }
        }
    }
}

Telemetry

The aggregator plugin provides a number of different aggregation types. Please contact us if you have custom requirements. The above Sink Configuration provides details on how to configure your telemetry outputs. The next section provides additional examples on configuring outputs.

Aggregator Type 1
Stats by application, protocol, local IP and local MAC
Aggregator Type 2
Stats by application, protocol, local IP, local MAC, other IP and IP protocol
Aggregator Type 3
Stats by a condensed flow summary that excludes ephemeral local ports
Aggregator Type 4
Stats by application, protocol, other IP, other port, VLAN, and IP protocol
Aggregator Type 5
Stats and performance data by network interface

Examples

Send Aggregate Data to a Log

Send uncompressed aggregate type 1 data every 15 seconds to the Sink Log plugin to a channel named aggregate .

Requirements:

{
    "aggregator": 1,
    "log_interval": 60,
    "privacy_mode": false,
    "format": "json",
    "compressor": "gz",
    "batched_rows": 0,
    "nested": false,
    "sinks": {
        "sink-log": {
            "aggregate": {
                "log_interval": 15,
                "format": "json",
                "compressor": "none"
            }
        }
    }
}

Send Aggregate Data to a Message Queue

Every 60 seconds, send aggregator type 2 data compressed with gzip and formatted using Message Pack to the Sink Message Queue plugin to a channel named telemetry .

Requirements:

{
    "aggregator": 2,
    "log_interval": 60,
    "privacy_mode": false,
    "format": "json",
    "compressor": "gz",
    "batched_rows": 0,
    "nested": false,
    "sinks": {
        "sink-mqtt": {
            "telemetry": {
                "format": "msgpack",
                "compressor": "gz"
            }
        }
    }
}