Viewing Netify Version v5

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 with bandwidth usage statistics and key network metrics.

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.

License

The Netify Aggregator 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

×

sudo apt-get update
sudo apt-get -y install curl gnupg2
sudo curl https://download.netify.ai/5/debian/netify-archive-keyring.gpg -o /usr/share/keyrings/netify-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netify-archive-keyring.gpg] http://download.netify.ai/5/debian/12/ /' | sudo tee /etc/apt/sources.list.d/netify.list

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 apt-get update
sudo apt-get -y install curl gnupg2
sudo curl https://download.netify.ai/5/debian/netify-archive-keyring.gpg -o /usr/share/keyrings/netify-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netify-archive-keyring.gpg] http://download.netify.ai/5/debian/11/ /' | sudo tee /etc/apt/sources.list.d/netify.list

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 apt-get update
sudo apt-get -y install curl gnupg2
sudo curl https://download.netify.ai/5/debian/netify-archive-keyring.gpg -o /usr/share/keyrings/netify-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netify-archive-keyring.gpg] http://download.netify.ai/5/debian/10/ /' | sudo tee /etc/apt/sources.list.d/netify.list

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 apt-get update
sudo apt-get -y install curl gnupg2
sudo curl https://download.netify.ai/5/ubuntu/netify-archive-keyring.gpg -o /usr/share/keyrings/netify-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netify-archive-keyring.gpg] http://download.netify.ai/5/ubuntu/noble/ /' | sudo tee /etc/apt/sources.list.d/netify.list

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 apt-get update
sudo apt-get -y install curl gnupg2
sudo curl https://download.netify.ai/5/ubuntu/netify-archive-keyring.gpg -o /usr/share/keyrings/netify-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netify-archive-keyring.gpg] http://download.netify.ai/5/ubuntu/jammy/ /' | sudo tee /etc/apt/sources.list.d/netify.list

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 apt-get update
sudo apt-get -y install curl gnupg2
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

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 http://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify http://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.6/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/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 yum update
sudo yum 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 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/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

To use the Netify Aggregator plugin, ensure your license.json includes the netify-proc-aggregator entitlement.

All plugins are disabled by default, and the Netify Aggregator plugin is no different. Use netifyd's --enable-plugin and --disable-plugin flags to enable or disable the plugin.

Terminal - Netify

×

netifyd --enable-plugin proc-aggregator  # Enables loader
netifyd --disable-plugin proc-aggregator # Disables loader

For orchestration tools or manual setup, you can also directly update configuration file in the plugins.d subdirectory and set enable to yes.

See the advanced configuration section for details on instantiating multiple instances of the plugin.

Terminal - Netify

×

$ cat 10-netify-proc-aggregator.conf
[proc-aggregator]
enable = yes
plugin_library = /usr/lib64/libnetify-proc-aggregator.so.0.0.0
conf_filename = ${path_state_persistent}/netify-proc-aggregator.json

AI Integration

For AI integration and machine learning models, the Netify Aggregator Configuration JSON schema is available for reference.

Main Configuration

The plugin is configured via the JSON file referenced by its loader (typically /etc/netifyd/netify-proc-aggregator.json ). The format and compressor properties define global defaults, which can be overridden per channel. See the examples below for how to apply channel-level overrides.

aggregator

integer

Aggregator format type.

Reference:

Aggregator telemetry formats

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.

format

string

Default payload format used for all outputs unless overridden in sinks.

Options:

json msgpack

compressor

string

Default compression policy used for all outputs unless overridden in sinks.

Options:

none gz

batched_rows

integer

Limits the number of aggregate records processed in a single batch. Use 0 for unlimited.

Default:

0

nested

boolean

Layout format for aggregate rows. 'true' for nested objects, 'false' for flat key-value pairs.

Default:

false

Reference:

Flat versus nested information

criteria

object

An object array of supported flow criteria expressions.

Reference:

See Expression Engine documentation

sinks

object

Sink configuration.

Reference:

See Sink Configuration section below

Example: Aggregate Data to a Log

This example sends uncompressed Type 1 aggregate data to the log every 15 seconds. The channel is named aggregate to distinguish it from other logged telemetry streams. By applying the criteria attribute, we can restrict what flow data to include in the aggregate payload.

Aggregator Configuration: netify-proc-aggregator.json

{
  "aggregator": 1,
  "log_interval": 15,
  "privacy_mode": false,
  "format": "json",
  "compressor": "gz",
  "batched_rows": 0,
  "nested": false,
  "criteria": [
    "ip_nat == false;",
    "vlan_id == 10;"
  ],
  "sinks": {
    "sink-log": {
      "aggregate": {
        "format": "json",
        "compressor": "none"
      }
    }
  }
}

Example: Aggregate Data to a Log and Message Queue

This example shows uncompressed aggregate type 2 data sent to both a log and a message queue every 60 seconds. Both channels are named aggregate . The log file receives uncompressed JSON formatted data, while the message queue is configured to received compressed MessagePack data.

Aggregator Configuration: netify-proc-aggregator.json

{
  "aggregator": 2,
  "log_interval": 60,
  "privacy_mode": false,
  "format": "json",
  "compressor": "gz",
  "batched_rows": 0,
  "nested": false,
  "sinks": {
    "sink-log": {
      "aggregate": {
        "format": "json",
        "compressor": "none"
      }
    },
    "sink-mqtt": {
      "aggregate": {
        "format": "msgpack",
        "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

enable

boolean

Enables or disables this specific sink channel.

Default:

true

format

string

The serialization format for the data payload.

Options:

json msgpack

compressor

string

The compression algorithm applied to the payload.

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.

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

Flat vs. Nested Formats

The aggregator formats are available in two different formats. The flat format is well suited for importing into databases, creating CSVs, and managing other row-based solutions. The nested format is well suited for cache keys, internal data structures in memory, and other key-based solutions.

See the aggregator type documentation above for a detailed breakdown of each format.

Flat

{
    "key1": "key value1",
    "key2": "key value2",
    "key3": "key value3",
    "data1": "aggregate data1",
    "data2": "aggregate data2",
    "data3": "aggregate data3"
}

Nested

{
    "key value1": {
        "key value2": {
            "key value3": {
                "data1": "aggregate data1",
                "data2": "aggregate data2",
                "data3": "aggregate data3"
            }
        }
    }
}