API

API

• Introduction
• Configuration
• Client Requests
• Server Responses
• Interactive Sessions
• API Command Reference
• Examples
• Further Reading

Introduction

The API was first introduced in version 5.2 as an initial foundation for external interaction with the daemon. 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 daemon’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 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 to the main configuration file ( netifyd.conf ), or a profile configuration, if preferred ( ./profiles.d/*.conf).

[netifyd]
path_server_socket = ${path_state_volatile}/netifyd.sock

Requests

The minimal structure of a Client Request is:

{
    "command": "command"
}

Depending on the command type, there may be additional required fields. The most common one being a data field. Generally a 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 that was given contained one or more data entries, the Agent will include a summary of the number of entries received as a total , along with the number of entries that were not successfully processed, errors . For example:

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

Interative Sessions

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

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.1.26-master-2797-f854102c (ubuntu; linux-gnu; x86_64; conntrack; netlink; dns-cache; tpv3; nfqueue; regex; nlm)",
        "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 add 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 ipset and adds them to an address group called printers.

#!/bin/bash
#
# Push IPs from ipset "printers" to Netify daemon 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 daemon socket
echo "$PAYLOAD" | nc -NU "$SOCKET_PATH"

Further Reading

• Address groups