Agent API

Netify Agent version 5 includes a local API socket for status, automation, and runtime control. This page documents request/response format and command examples.

The API was first introduced in version 5.2 as an initial foundation for external interaction with the agent. In its early form, the API provides only basic functionality - enough to enable simple integrations and proof-of-concept use cases.

Over time, the API is expected to evolve into a core interface for managing, querying, and extending the agent's capabilities. Future releases will expand its coverage, improve efficiency, and enable deeper integration with external systems and applications.

Configuration

The API is disabled by default. An API socket path must be configured to enable the service. The socket path is created with permissions mode 600: rw-rw---- . Only the same user or a user in the agent group will have permission to access it. The socket path can be added or updated in the profile configuration in ./profiles.d/*.conf .

Terminal - Netify

# Example: /etc/netifyd/profiles.d/00-default.conf
[netifyd]
path_server_socket = ${path_state_volatile}/netifyd.sock

If you are upgrading from 5.1 or an earlier version, you may have configured a file socket using the Sink Socket plugin. To prevent conflicts, make sure to rename the socket file for one of the components if both are running on the same system. Failing to do so may cause collisions or unexpected behavior.

Requests

The minimal structure of a client API request is:

{
    "command": "command"
}

Depending on the command type, there may be additional required fields, the most common being a data field. Generally, the data field is an array of items to process or a single item as a string, such as:

{
    "command": "command",
    "data": "some data"
}

{
    "command": "command",
    "data": [
        "some data",
        "more data"
    ]
}

Responses

The agent will respond with a minimal code/message structure, such as:

{
    "code": 100,
    "message": "Ok."
}

When the command includes one or more data entries, the agent includes a summary of the total number of entries received, along with the number of entries that were not successfully processed (errors). For example:

{
    "code": 100,
    "message": "Ok.",
    "data": {
        "errors": 0,
        "total": 1
    }
}

Interactive Sessions

Netcat can be used to bind to the socket for an interactive session.

Terminal - Netify

sudo nc -NU /var/run/netifyd/netifyd.sock
{ "command": "add-group-address", "group": "games", "data": "23.62.104.113" }

{
    "code": 100,
    "data": {
        "errors": 0,
        "total": 1
    },
    "message": "Ok."
}

# CTRL-C to exit...

API Command Reference

Agent Status

To retrieve an overview of the current status of the running agent instance, the following command can be sent:

{
    "command": "status"
}

An example response:

{
    "code": 100,
    "data": {
        "agent_version": "Netify Agent/5.2.0...",
        "cpu_cores": 16,
        "cpu_system": 0.950186,
        "cpu_system_prev": 0.941235,
        "cpu_user": 2.400082,
        "cpu_user_prev": 2.361822,
        "dhc_status": true,
        "fhc_status": true,
        "flow_count": 162,
        "flow_count_prev": 187,
        "flows_active": 57,
        "flows_expired": 101,
        "flows_expiring": 6,
        "flows_in_use": 35,
        "flows_purged": 31,
        "maxrss_kb": 242688,
        "maxrss_kb_prev": 241024,
        "memrss_kb": 242688,
        "memrss_kb_prev": 241024,
        "timestamp": 1762615485,
        "update_imf": 1,
        "update_interval": 15,
        "uptime": 1065
    },
    "message": "Ok."
}

Address Groups

Managing the Address Groups feature of the Netify DPI agent can be done through the API.

Add Address Group

To add an address (MAC, IPv4, IPv6) to a new or existing group, the following command structures can be sent. If the address group does not already exist, it will be created dynamically:

{
    "command": "add-group-address",
    "group": "printers",
    "data": "192.168.1.100"
}

To add multiple entries in one command, send an array of values:

{
    "command": "add-group-address",
    "group": "printers",
    "data": [
        "10.0.0.101",
        "10.0.0.220"
    ]
}

Remove Group Addresses

To remove addresses from a group, use the following structures:

{
    "command": "remove-group-address",
    "group": "printers",
    "data": "192.168.1.100"
}

To remove multiple entries in one command, send an array of values:

{
    "command": "remove-group-address",
    "group": "printers",
    "data": [
        "10.0.0.101",
        "10.0.0.220"
    ]
}

Delete Address Group

To delete an address group:

{
    "command": "flush-group-addresses",
    "group": "printers"
}

Address Group Statefulness

To make an existing in-memory address group stateful so that it will be recalled on machine reboot or agent restart:

{
    "command": "save-address-group",
    "group": "printers"
}

Examples

Bash

The following sample script extracts IP addresses from an IP set and adds them to an address group called printers .

Terminal - Netify

#!/bin/bash
#
# Push IPs from ipset "printers" to Netify agent via Unix socket
#

IPSET_NAME="printers"
SOCKET_PATH="/var/run/netifyd/netifyd.sock"

# Check if ipset exists
if ! ipset list -n | grep -q "^${IPSET_NAME}$"; then
    echo "Error: ipset '${IPSET_NAME}' does not exist."
    exit 1
fi

# Get IPs from ipset (IPv4, IPv6, MAC, etc.) using 'ipset save'
IPS=$(ipset save "$IPSET_NAME" | awk '/^add / {print $3}')

if [ -z "$IPS" ]; then
    echo "No IPs found in ipset '${IPSET_NAME}'."
    exit 0
fi

# Convert IPs into quoted, comma-separated JSON array
JSON_IPS=$(printf '"%s",' $IPS | sed 's/,$//')

# Build JSON payload
PAYLOAD="{\"command\": \"add-group-address\", \"group\": \"${IPSET_NAME}\", \"data\": [${JSON_IPS}]}"

# Send payload to Netify agent socket
echo "$PAYLOAD" | nc -NU "$SOCKET_PATH"