CGN#
Carrier-grade NAT (NAT44): status, IP groups (public pools), live bindings, and binding identity enrichment.
10 operations. Roles, error format and pagination are common to the whole API — see the REST API overview.
Authentication
Use a named bearer token. Every endpoint except POST /api/v1/auth/login,
POST /api/v1/auth/enrol and GET /api/v1/system/health requires one. A super-user creates a
token with POST /api/v1/auth/tokens; the plaintext (bngtok_…) is returned exactly once at
creation and only a SHA-256 hash is stored on the appliance, so a lost token is replaced rather
than recovered. Send it on every request:
Each token carries a fixed role (read-only, operator or super-user) and is exempt from CSRF
checks. This is the single credential you need for scripts, integrations and monitoring.
Accounts and tokens share one identity model with the appliance CLI (login.users). Repeated
authentication failures lock the account/source-IP pair out temporarily (HTTP 423 on login).
Session cookies (bundled web UI only)
The appliance also accepts an interactive session cookie, which is how the bundled web UI authenticates. It is documented for completeness — API clients should not use it. It is bound to a login session and obliges the caller to manage a CSRF token, neither of which suits automation.
POST /api/v1/auth/login with username + password (and a TOTP code when enrolled) sets the
bng_session cookie and returns a csrfToken (also available from GET /api/v1/auth/whoami).
Cookie-authenticated mutating requests (anything other than GET/HEAD/OPTIONS) must also send
that value in the X-CSRF-Token header or they are rejected with 403.
One endpoint refuses the cookie outright: GET /api/v1/metrics, the Prometheus scrape, accepts a
bearer token only, so that a scraper can never keep a login session alive.
NetavoBNG Management API v1#
Contact: Netavo
CGN#
GET /api/v1/cgn/bindings#
List live NAT bindings (filtered, paged).
Description
Filters combine with AND: group and vrf are exact (case-insensitive; "default"
matches the default table), ip is a prefix match against both the inside and the public
address. running: false means CGN isn't active — the list is then empty.
Fleet-proxyable.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
group |
query | string | No | Filter by CGN IP group name. | |
ip |
query | string | No | Prefix match on the inside or public IPv4 address. | |
limit |
query | 100 | No | Page size, clamped to 1–1000 (default 100). | |
offset |
query | 0 | No | Rows to skip (default 0). | |
vrf |
query | string | No | Filter by inside VRF name. |
Responses
{
"running": true,
"total": 1842,
"offset": 0,
"limit": 50,
"items": [
{
"bindingIndex": 10427,
"group": "cgn-public-a",
"insideVrf": "residential",
"insideIp": "100.64.12.37",
"publicIp": "45.84.200.113",
"sessionId": 40213,
"subscriberId": "alice@example.net",
"autoLearned": false,
"portBlocks": [
"21504-22015",
"22016-22527"
],
"chunkSize": 512,
"portCap": 4096,
"createdUtc": "2026-08-03T10:24:00Z"
}
]
}
Schema of the response body
{
"required": [
"running",
"total",
"offset",
"limit",
"items"
],
"type": "object",
"properties": {
"running": {
"type": "boolean",
"description": "Whether CGN is active in this control-plane process."
},
"total": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings matching the filters (before paging).",
"format": "int32"
},
"offset": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The offset this page was taken at.",
"format": "int32"
},
"limit": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "The effective page size (after clamping).",
"format": "int32"
},
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CgnBindingRow"
},
"description": "The page of binding rows."
}
},
"description": "GET /api/v1/cgn/bindings page. Running=false means CGN isn't active (rows empty).",
"example": {
"running": true,
"total": 1842,
"offset": 0,
"limit": 50,
"items": [
{
"bindingIndex": 10427,
"group": "cgn-public-a",
"insideVrf": "residential",
"insideIp": "100.64.12.37",
"publicIp": "45.84.200.113",
"sessionId": 40213,
"subscriberId": "alice@example.net",
"autoLearned": false,
"portBlocks": [
"21504-22015",
"22016-22527"
],
"chunkSize": 512,
"portCap": 4096,
"createdUtc": "2026-08-03T10:24:00Z"
}
]
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/cgn/bindings/{bindingIndex}/identify#
Attach a subscriber identity to an auto-learned binding.
Description
Auto-learned bindings start anonymous; this enriches one with the subscriber identity used in compliance/abuse-resolution logging (an Identify event is emitted per port block, and the acting principal is audited). Only auto-learned bindings can be identified. Super-user only; local appliance only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
bindingIndex |
path | No | The binding's index (from the bindings list). |
Request body
Responses
{
"bindingIndex": 10427,
"group": "cgn-public-a",
"insideVrf": "residential",
"insideIp": "100.64.12.37",
"publicIp": "45.84.200.113",
"sessionId": 40213,
"subscriberId": "alice@example.net",
"autoLearned": false,
"portBlocks": [
"21504-22015",
"22016-22527"
],
"chunkSize": 512,
"portCap": 4096,
"createdUtc": "2026-08-03T10:24:00Z"
}
Schema of the response body
{
"required": [
"bindingIndex",
"group",
"insideVrf",
"insideIp",
"publicIp",
"sessionId",
"subscriberId",
"autoLearned",
"portBlocks",
"chunkSize",
"portCap",
"createdUtc"
],
"type": "object",
"properties": {
"bindingIndex": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Stable index of the binding — the key for the identify endpoint.",
"format": "uint32"
},
"group": {
"type": "string",
"description": "CGN IP group the public address came from."
},
"insideVrf": {
"type": "string",
"description": "Inside VRF of the subscriber (\"default\" = global table)."
},
"insideIp": {
"type": "string",
"description": "Subscriber's inside IPv4 address."
},
"publicIp": {
"type": "string",
"description": "Public IPv4 address the subscriber is translated to."
},
"sessionId": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Associated BNG session id (0 for anonymous auto-learned bindings).",
"format": "uint32"
},
"subscriberId": {
"type": "string",
"description": "Subscriber identity for compliance logging, or null if not identified.",
"nullable": true
},
"autoLearned": {
"type": "boolean",
"description": "True when the binding was auto-learned rather than session-driven."
},
"portBlocks": {
"type": "array",
"items": {
"type": "string"
},
"description": "Allocated port ranges, as \"start-end\" strings."
},
"chunkSize": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Ports per block for this binding.",
"format": "uint16"
},
"portCap": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Port cap in force for this binding.",
"format": "uint16"
},
"createdUtc": {
"type": "string",
"description": "UTC time the binding was created.",
"format": "date-time"
}
},
"description": "One live NAT binding (a subscriber's inside address mapped to a public address with\n one or more port blocks).",
"example": {
"bindingIndex": 10427,
"group": "cgn-public-a",
"insideVrf": "residential",
"insideIp": "100.64.12.37",
"publicIp": "45.84.200.113",
"sessionId": 40213,
"subscriberId": "alice@example.net",
"autoLearned": false,
"portBlocks": [
"21504-22015",
"22016-22527"
],
"chunkSize": 512,
"portCap": 4096,
"createdUtc": "2026-08-03T10:24:00Z"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/cgn/groups#
List CGN IP groups (public address pools) with live utilisation.
Description
One row per configured group; utilisation and activeBindings are live values
(null/0 when CGN isn't running or the group was added since startup). Fleet-proxyable.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
[
{
"name": "cgn-public-a",
"description": "Residential CGN pool",
"outsideVrf": "internet",
"publicSubnets": [
"45.84.200.0/24"
],
"chunkSize": 512,
"portCap": 4096,
"setupsPerSec": 200,
"bindingTimeoutSeconds": 300,
"quarantineSeconds": 120,
"bypassPrefixes": [
"100.64.0.0/10"
],
"autoLearn": [
{
"insideVrf": "residential",
"prefixes": [
"100.64.0.0/12"
]
}
],
"timeouts": {
"tcpEstablished": 7440,
"tcpTransitory": 240,
"udp": 300,
"icmp": 60,
"udpDns": 30
},
"activeBindings": 1842,
"utilisation": {
"totalChunks": 9000,
"freeChunks": 712,
"usedChunks": 8192,
"quarantinedChunks": 96
},
"outbound": {
"blockStandard": true,
"blockPrivate": false,
"blockPorts": [
"tcp/23"
],
"blockPrefixes": [],
"allowPrefixes": [
"192.0.2.25/32"
]
}
}
]
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/cgn/groups#
Create a CGN IP group.
Description
Commits through the configuration store. A new group is read at startup: the
response carries restartRequired: true and the group only becomes active after a
control-plane restart. Super-user only; local appliance only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
{
"name": "cgn-public-a",
"description": "Residential CGN pool",
"outsideVrf": "internet",
"publicSubnets": [
"45.84.200.0/24"
],
"chunkSize": 512,
"portCap": 4096,
"setupsPerSec": 200,
"bindingTimeoutSeconds": 300,
"quarantineSeconds": 120,
"bypassPrefixes": [
"100.64.0.0/10"
],
"autoLearn": [
{
"insideVrf": "residential",
"prefixes": [
"100.64.0.0/12"
]
}
],
"timeouts": {
"tcpEstablished": 7440,
"tcpTransitory": 240,
"udp": 300,
"icmp": 60,
"udpDns": 30
},
"outbound": {
"blockStandard": true,
"blockPrivate": false,
"blockPorts": [
"tcp/23"
],
"blockPrefixes": [],
"allowPrefixes": [
"192.0.2.25/32"
]
}
}
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"name",
"description",
"outsideVrf",
"publicSubnets",
"chunkSize",
"portCap",
"setupsPerSec",
"bindingTimeoutSeconds",
"quarantineSeconds",
"bypassPrefixes",
"autoLearn",
"timeouts"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Group name — the immutable key (service plans reference it)."
},
"description": {
"type": "string",
"description": "Free-text description.",
"nullable": true
},
"outsideVrf": {
"type": "string",
"description": "VRF holding the public side (null/empty = default table).",
"nullable": true
},
"publicSubnets": {
"type": "array",
"items": {
"type": "string"
},
"description": "Public IPv4 subnets (CIDR) the group allocates from.",
"nullable": true
},
"chunkSize": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Ports per allocated port block.",
"format": "int32"
},
"portCap": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Maximum ports one subscriber may hold before extensions stop.",
"format": "int32"
},
"setupsPerSec": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Per-subscriber NAT setup rate limit.",
"format": "int32"
},
"bindingTimeoutSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Idle teardown for auto-learned bindings.",
"format": "int32"
},
"quarantineSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Quarantine before a freed port block is reused.",
"format": "int32"
},
"bypassPrefixes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Destinations that bypass NAT (CIDR).",
"nullable": true
},
"autoLearn": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CgnAutoLearn"
},
"description": "Auto-learn scopes (inside VRF + prefixes).",
"nullable": true
},
"timeouts": {
"oneOf": [
{
"nullable": true
},
{
"$ref": "#/components/schemas/CgnTimeouts"
}
]
},
"outbound": {
"oneOf": [
{
"nullable": true
},
{
"$ref": "#/components/schemas/CgnOutbound"
}
]
}
},
"description": "Request body for CGN IP group create/update.",
"example": {
"name": "cgn-public-a",
"description": "Residential CGN pool",
"outsideVrf": "internet",
"publicSubnets": [
"45.84.200.0/24"
],
"chunkSize": 512,
"portCap": 4096,
"setupsPerSec": 200,
"bindingTimeoutSeconds": 300,
"quarantineSeconds": 120,
"bypassPrefixes": [
"100.64.0.0/10"
],
"autoLearn": [
{
"insideVrf": "residential",
"prefixes": [
"100.64.0.0/12"
]
}
],
"timeouts": {
"tcpEstablished": 7440,
"tcpTransitory": 240,
"udp": 300,
"icmp": 60,
"udpDns": 30
},
"outbound": {
"blockStandard": true,
"blockPrivate": false,
"blockPorts": [
"tcp/23"
],
"blockPrefixes": [],
"allowPrefixes": [
"192.0.2.25/32"
]
}
}
}
Responses
{
"status": "committed",
"name": "cgn-public-a",
"committedUtc": "2026-08-03T10:24:11Z",
"restartRequired": true
}
Schema of the response body
{
"required": [
"status",
"name",
"committedUtc",
"restartRequired"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Always \"committed\"."
},
"name": {
"type": "string",
"description": "The group/settings object the commit touched."
},
"committedUtc": {
"type": "string",
"description": "UTC timestamp the new configuration version became active.",
"format": "date-time",
"nullable": true
},
"restartRequired": {
"type": "boolean",
"description": "True when the commit changed something the CGN engine reads only\n at startup (a group added or removed; its public subnets, outside VRF, chunk size, bypass or\n auto-learn prefixes; cgn enabled, max-bindings, max-flows or logger), so it takes full effect\n after a control-plane restart. False when it changed only a group's limits and timers, which\n apply at once (existing bindings keep their limits until re-applied)."
}
},
"description": "Result of a CGN configuration commit.",
"example": {
"status": "committed",
"name": "cgn-public-a",
"committedUtc": "2026-08-03T10:24:11Z",
"restartRequired": true
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
PUT /api/v1/cgn/groups/{name}#
Update a CGN IP group.
Description
Full-replace semantics (the name in the URL is the immutable key). While the
group carries live bindings, structural fields (chunk size, public subnets, outside VRF)
cannot change — drain the pool first. The group's limits and timers (description, port
cap, setups/s, binding timeout, quarantine, flow timeouts) apply on commit: new bindings
take them at once, and existing bindings keep theirs until POST
/api/v1/sessions/reapply. restartRequired is true only when the edit also changed
something read at startup (public subnets, outside VRF, chunk size, bypass or auto-learn
prefixes). Super-user only; local appliance only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
name |
path | string | No | The IP group to update. |
Request body
{
"name": "cgn-public-a",
"description": "Residential CGN pool",
"outsideVrf": "internet",
"publicSubnets": [
"45.84.200.0/24"
],
"chunkSize": 512,
"portCap": 4096,
"setupsPerSec": 200,
"bindingTimeoutSeconds": 300,
"quarantineSeconds": 120,
"bypassPrefixes": [
"100.64.0.0/10"
],
"autoLearn": [
{
"insideVrf": "residential",
"prefixes": [
"100.64.0.0/12"
]
}
],
"timeouts": {
"tcpEstablished": 7440,
"tcpTransitory": 240,
"udp": 300,
"icmp": 60,
"udpDns": 30
},
"outbound": {
"blockStandard": true,
"blockPrivate": false,
"blockPorts": [
"tcp/23"
],
"blockPrefixes": [],
"allowPrefixes": [
"192.0.2.25/32"
]
}
}
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"name",
"description",
"outsideVrf",
"publicSubnets",
"chunkSize",
"portCap",
"setupsPerSec",
"bindingTimeoutSeconds",
"quarantineSeconds",
"bypassPrefixes",
"autoLearn",
"timeouts"
],
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Group name — the immutable key (service plans reference it)."
},
"description": {
"type": "string",
"description": "Free-text description.",
"nullable": true
},
"outsideVrf": {
"type": "string",
"description": "VRF holding the public side (null/empty = default table).",
"nullable": true
},
"publicSubnets": {
"type": "array",
"items": {
"type": "string"
},
"description": "Public IPv4 subnets (CIDR) the group allocates from.",
"nullable": true
},
"chunkSize": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Ports per allocated port block.",
"format": "int32"
},
"portCap": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Maximum ports one subscriber may hold before extensions stop.",
"format": "int32"
},
"setupsPerSec": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Per-subscriber NAT setup rate limit.",
"format": "int32"
},
"bindingTimeoutSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Idle teardown for auto-learned bindings.",
"format": "int32"
},
"quarantineSeconds": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Quarantine before a freed port block is reused.",
"format": "int32"
},
"bypassPrefixes": {
"type": "array",
"items": {
"type": "string"
},
"description": "Destinations that bypass NAT (CIDR).",
"nullable": true
},
"autoLearn": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CgnAutoLearn"
},
"description": "Auto-learn scopes (inside VRF + prefixes).",
"nullable": true
},
"timeouts": {
"oneOf": [
{
"nullable": true
},
{
"$ref": "#/components/schemas/CgnTimeouts"
}
]
},
"outbound": {
"oneOf": [
{
"nullable": true
},
{
"$ref": "#/components/schemas/CgnOutbound"
}
]
}
},
"description": "Request body for CGN IP group create/update.",
"example": {
"name": "cgn-public-a",
"description": "Residential CGN pool",
"outsideVrf": "internet",
"publicSubnets": [
"45.84.200.0/24"
],
"chunkSize": 512,
"portCap": 4096,
"setupsPerSec": 200,
"bindingTimeoutSeconds": 300,
"quarantineSeconds": 120,
"bypassPrefixes": [
"100.64.0.0/10"
],
"autoLearn": [
{
"insideVrf": "residential",
"prefixes": [
"100.64.0.0/12"
]
}
],
"timeouts": {
"tcpEstablished": 7440,
"tcpTransitory": 240,
"udp": 300,
"icmp": 60,
"udpDns": 30
},
"outbound": {
"blockStandard": true,
"blockPrivate": false,
"blockPorts": [
"tcp/23"
],
"blockPrefixes": [],
"allowPrefixes": [
"192.0.2.25/32"
]
}
}
}
Responses
{
"status": "committed",
"name": "cgn-public-a",
"committedUtc": "2026-08-03T10:24:11Z",
"restartRequired": true
}
Schema of the response body
{
"required": [
"status",
"name",
"committedUtc",
"restartRequired"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Always \"committed\"."
},
"name": {
"type": "string",
"description": "The group/settings object the commit touched."
},
"committedUtc": {
"type": "string",
"description": "UTC timestamp the new configuration version became active.",
"format": "date-time",
"nullable": true
},
"restartRequired": {
"type": "boolean",
"description": "True when the commit changed something the CGN engine reads only\n at startup (a group added or removed; its public subnets, outside VRF, chunk size, bypass or\n auto-learn prefixes; cgn enabled, max-bindings, max-flows or logger), so it takes full effect\n after a control-plane restart. False when it changed only a group's limits and timers, which\n apply at once (existing bindings keep their limits until re-applied)."
}
},
"description": "Result of a CGN configuration commit.",
"example": {
"status": "committed",
"name": "cgn-public-a",
"committedUtc": "2026-08-03T10:24:11Z",
"restartRequired": true
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
DELETE /api/v1/cgn/groups/{name}#
Delete a CGN IP group.
Description
Refused while the group carries live bindings (a restart with subscribers still mapped through the pool would strand their NAT state). Restart-required like create. Super-user only; local appliance only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
name |
path | string | No | The IP group to delete. |
Responses
{
"status": "committed",
"name": "cgn-public-a",
"committedUtc": "2026-08-03T10:24:11Z",
"restartRequired": true
}
Schema of the response body
{
"required": [
"status",
"name",
"committedUtc",
"restartRequired"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Always \"committed\"."
},
"name": {
"type": "string",
"description": "The group/settings object the commit touched."
},
"committedUtc": {
"type": "string",
"description": "UTC timestamp the new configuration version became active.",
"format": "date-time",
"nullable": true
},
"restartRequired": {
"type": "boolean",
"description": "True when the commit changed something the CGN engine reads only\n at startup (a group added or removed; its public subnets, outside VRF, chunk size, bypass or\n auto-learn prefixes; cgn enabled, max-bindings, max-flows or logger), so it takes full effect\n after a control-plane restart. False when it changed only a group's limits and timers, which\n apply at once (existing bindings keep their limits until re-applied)."
}
},
"description": "Result of a CGN configuration commit.",
"example": {
"status": "committed",
"name": "cgn-public-a",
"committedUtc": "2026-08-03T10:24:11Z",
"restartRequired": true
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
POST /api/v1/cgn/reclaim#
Give back unused CGN port blocks.
Description
Gives back a binding's empty port blocks at the top of its list, never the first
block, to the pool's quarantine (quarantineSeconds), and logs a Dealloc with reason
"reclaimed" for each. The data plane judges each block empty under the binding's locks, so
a port taken meanwhile keeps its block; translations in the blocks kept are untouched.
Either one inside address (insideIp, optionally vrf), all: true (every binding
with more than one block, one at a time) or group (the same, for one CGN IP group). Each binding's result says what was released or
why nothing was: nothing reclaimable, busy, pending (an earlier reclaim's answer from the
data plane was lost and is being resolved; the binding is not written until it is) or
failed. For all and group, bindings with nothing reclaimable are counted, not listed. Like the CLI
request cgn reclaim-blocks. Requires the operator role (or above); local appliance
only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
Responses
{
"blocksReleased": 2,
"bindingsReleased": 1,
"nothingReclaimable": 0,
"pending": 0,
"failed": 0,
"notAttempted": 0,
"bindings": [
{
"bindingIndex": 10427,
"insideIp": "100.64.3.17",
"insideVrf": "residential",
"outcome": "released",
"heldBefore": 4,
"heldAfter": 2,
"released": [
"9216-9727",
"8704-9215"
],
"detail": null
}
]
}
Schema of the response body
{
"required": [
"blocksReleased",
"bindingsReleased",
"nothingReclaimable",
"pending",
"failed",
"notAttempted",
"bindings"
],
"type": "object",
"properties": {
"blocksReleased": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Port blocks given back, over every binding.",
"format": "int32"
},
"bindingsReleased": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings that gave back at least one block.",
"format": "int32"
},
"nothingReclaimable": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings with no empty block at the top to give back.",
"format": "int32"
},
"pending": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings whose outcome is not known yet (an answer from the data plane\n was lost; resolved by asking it again — nothing is released until then).",
"format": "int32"
},
"failed": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Bindings for which nothing was given back, for the reason given.",
"format": "int32"
},
"notAttempted": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "For `all`: bindings not tried because an earlier one found the data\n plane not answering (each read is bounded at 250 ms and the run stops at the first).",
"format": "int32"
},
"bindings": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CgnReclaimBinding"
},
"description": "Each binding's result; for `all`, only those that released something,\n were busy, pending or failed."
}
},
"description": "Result of POST /api/v1/cgn/reclaim (#519).",
"example": {
"blocksReleased": 2,
"bindingsReleased": 1,
"nothingReclaimable": 0,
"pending": 0,
"failed": 0,
"notAttempted": 0,
"bindings": [
{
"bindingIndex": 10427,
"insideIp": "100.64.3.17",
"insideVrf": "residential",
"outcome": "released",
"heldBefore": 4,
"heldAfter": 2,
"released": [
"9216-9727",
"8704-9215"
],
"detail": null
}
]
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/cgn/settings#
Read the section-level CGN settings.
Description
The configured (not necessarily running) values. Fleet-proxyable.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
Schema of the response body
{
"required": [
"enabled",
"maxBindings",
"maxFlows",
"loggerSpoolSize"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether CGN activates at control-plane start."
},
"maxBindings": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Global cap on concurrent NAT bindings (table size).",
"format": "int32"
},
"maxFlows": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Global cap on concurrent NAT flows (table size).",
"format": "int32"
},
"loggerSpoolSize": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Compliance-logger spool size (events buffered per driver).",
"format": "int32"
}
},
"description": "Section-level CGN settings (also the PUT body).",
"example": {
"enabled": true,
"maxBindings": 65536,
"maxFlows": 2097152,
"loggerSpoolSize": 16384
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
PUT /api/v1/cgn/settings#
Update the section-level CGN settings.
Description
Commits through the configuration store; restart-required (the tables are sized at startup). Super-user only; local appliance only.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Request body
Other accepted types: application/*+json, text/json
Schema of the request body
{
"required": [
"enabled",
"maxBindings",
"maxFlows",
"loggerSpoolSize"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether CGN activates at control-plane start."
},
"maxBindings": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Global cap on concurrent NAT bindings (table size).",
"format": "int32"
},
"maxFlows": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Global cap on concurrent NAT flows (table size).",
"format": "int32"
},
"loggerSpoolSize": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Compliance-logger spool size (events buffered per driver).",
"format": "int32"
}
},
"description": "Section-level CGN settings (also the PUT body).",
"example": {
"enabled": true,
"maxBindings": 65536,
"maxFlows": 2097152,
"loggerSpoolSize": 16384
}
}
Responses
{
"status": "committed",
"name": "cgn-public-a",
"committedUtc": "2026-08-03T10:24:11Z",
"restartRequired": true
}
Schema of the response body
{
"required": [
"status",
"name",
"committedUtc",
"restartRequired"
],
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Always \"committed\"."
},
"name": {
"type": "string",
"description": "The group/settings object the commit touched."
},
"committedUtc": {
"type": "string",
"description": "UTC timestamp the new configuration version became active.",
"format": "date-time",
"nullable": true
},
"restartRequired": {
"type": "boolean",
"description": "True when the commit changed something the CGN engine reads only\n at startup (a group added or removed; its public subnets, outside VRF, chunk size, bypass or\n auto-learn prefixes; cgn enabled, max-bindings, max-flows or logger), so it takes full effect\n after a control-plane restart. False when it changed only a group's limits and timers, which\n apply at once (existing bindings keep their limits until re-applied)."
}
},
"description": "Result of a CGN configuration commit.",
"example": {
"status": "committed",
"name": "cgn-public-a",
"committedUtc": "2026-08-03T10:24:11Z",
"restartRequired": true
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
GET /api/v1/cgn/status#
CG-NAT status: configuration, live binding counts, and counters.
Description
Merges the configured CGN section (enabled flag, limits, IP groups) with live
state: binding counts, per-group pool utilisation, native data-plane counters, and
compliance-logger loss counters. running: false means CGN is configured but not active
in this control-plane process (it activates at startup) — the config half still renders.
Fleet-proxyable.
Input parameters
| Parameter | In | Type | Default | Nullable | Description |
|---|---|---|---|---|---|
bearerToken |
header | string | N/A | No | Named API token — the recommended credential for automation. See Authentication in the API overview. |
Responses
{
"enabled": true,
"running": true,
"maxBindings": 65536,
"maxFlows": 2097152,
"activeBindings": 1842,
"autoLearnedBindings": 37,
"groups": [
{
"name": "cgn-public-a",
"description": "Residential CGN pool",
"outsideVrf": "internet",
"publicSubnets": [
"45.84.200.0/24"
],
"chunkSize": 512,
"portCap": 4096,
"setupsPerSec": 200,
"bindingTimeoutSeconds": 300,
"quarantineSeconds": 120,
"bypassPrefixes": [
"100.64.0.0/10"
],
"autoLearn": [
{
"insideVrf": "residential",
"prefixes": [
"100.64.0.0/12"
]
}
],
"timeouts": {
"tcpEstablished": 7440,
"tcpTransitory": 240,
"udp": 300,
"icmp": 60,
"udpDns": 30
},
"activeBindings": 1842,
"utilisation": {
"totalChunks": 9000,
"freeChunks": 712,
"usedChunks": 8192,
"quarantinedChunks": 96
},
"outbound": {
"blockStandard": true,
"blockPrivate": false,
"blockPorts": [
"tcp/23"
],
"blockPrefixes": [],
"allowPrefixes": [
"192.0.2.25/32"
]
}
}
],
"nativeCounters": {
"autolearnMisses": 18342,
"noMapping": 407,
"extensionWanted": 1265,
"eventRingDrops": 0
},
"eventsLostByDriver": {
"syslog": 0
}
}
Schema of the response body
{
"required": [
"enabled",
"running",
"maxBindings",
"maxFlows",
"activeBindings",
"autoLearnedBindings",
"groups",
"nativeCounters",
"eventsLostByDriver"
],
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"description": "Whether CGN is enabled in configuration."
},
"running": {
"type": "boolean",
"description": "Whether CGN is active in this control-plane process (activates at startup)."
},
"maxBindings": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Configured global cap on concurrent NAT bindings.",
"format": "int32"
},
"maxFlows": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Configured global cap on concurrent NAT flows.",
"format": "int32"
},
"activeBindings": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "Live NAT bindings right now (0 when not running).",
"format": "int32"
},
"autoLearnedBindings": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"description": "How many of the live bindings were auto-learned.",
"format": "int32"
},
"groups": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CgnGroup"
},
"description": "The configured IP groups merged with live utilisation."
},
"nativeCounters": {
"$ref": "#/components/schemas/CgnNativeCounters"
},
"eventsLostByDriver": {
"type": "object",
"additionalProperties": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int64"
},
"description": "Compliance-log events lost per logger driver (null when the\n logger pump isn't running).",
"nullable": true
}
},
"description": "GET /api/v1/cgn/status.",
"example": {
"enabled": true,
"running": true,
"maxBindings": 65536,
"maxFlows": 2097152,
"activeBindings": 1842,
"autoLearnedBindings": 37,
"groups": [
{
"name": "cgn-public-a",
"description": "Residential CGN pool",
"outsideVrf": "internet",
"publicSubnets": [
"45.84.200.0/24"
],
"chunkSize": 512,
"portCap": 4096,
"setupsPerSec": 200,
"bindingTimeoutSeconds": 300,
"quarantineSeconds": 120,
"bypassPrefixes": [
"100.64.0.0/10"
],
"autoLearn": [
{
"insideVrf": "residential",
"prefixes": [
"100.64.0.0/12"
]
}
],
"timeouts": {
"tcpEstablished": 7440,
"tcpTransitory": 240,
"udp": 300,
"icmp": 60,
"udpDns": 30
},
"activeBindings": 1842,
"utilisation": {
"totalChunks": 9000,
"freeChunks": 712,
"usedChunks": 8192,
"quarantinedChunks": 96
},
"outbound": {
"blockStandard": true,
"blockPrivate": false,
"blockPorts": [
"tcp/23"
],
"blockPrefixes": [],
"allowPrefixes": [
"192.0.2.25/32"
]
}
}
],
"nativeCounters": {
"autolearnMisses": 18342,
"noMapping": 407,
"extensionWanted": 1265,
"eventRingDrops": 0
},
"eventsLostByDriver": {
"syslog": 0
}
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
Schema of the response body
{
"type": "object",
"properties": {
"type": {
"type": "string",
"nullable": true
},
"title": {
"type": "string",
"nullable": true
},
"status": {
"pattern": "^-?(?:0|[1-9]\\d*)$",
"format": "int32",
"nullable": true
},
"detail": {
"type": "string",
"nullable": true
},
"instance": {
"type": "string",
"nullable": true
}
},
"example": {
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "VRF not found",
"status": 404,
"detail": "No VRF named 'wholesale-b' is configured.",
"instance": "/api/v1/vrfs/wholesale-b"
}
}
Schemas#
CgnAutoLearn#
| Name | Type | Description |
|---|---|---|
insideVrf |
string | null | Inside VRF the prefixes apply to (null = default table). |
prefixes |
Array<string> | Inside-subscriber prefixes eligible for auto-learned bindings. |
CgnBindingRow#
| Name | Type | Description |
|---|---|---|
autoLearned |
boolean | True when the binding was auto-learned rather than session-driven. |
bindingIndex |
Stable index of the binding — the key for the identify endpoint. | |
chunkSize |
Ports per block for this binding. | |
createdUtc |
string(date-time) | UTC time the binding was created. |
group |
string | CGN IP group the public address came from. |
insideIp |
string | Subscriber's inside IPv4 address. |
insideVrf |
string | Inside VRF of the subscriber ("default" = global table). |
portBlocks |
Array<string> | Allocated port ranges, as "start-end" strings. |
portCap |
Port cap in force for this binding. | |
publicIp |
string | Public IPv4 address the subscriber is translated to. |
sessionId |
Associated BNG session id (0 for anonymous auto-learned bindings). | |
subscriberId |
string | null | Subscriber identity for compliance logging, or null if not identified. |
CgnBindingsPage#
| Name | Type | Description |
|---|---|---|
items |
Array<CgnBindingRow> | The page of binding rows. |
limit |
The effective page size (after clamping). | |
offset |
The offset this page was taken at. | |
running |
boolean | Whether CGN is active in this control-plane process. |
total |
Bindings matching the filters (before paging). |
CgnCommitResult#
| Name | Type | Description |
|---|---|---|
committedUtc |
string(date-time) | null | UTC timestamp the new configuration version became active. |
name |
string | The group/settings object the commit touched. |
restartRequired |
boolean | True when the commit changed something the CGN engine reads only at startup (a group added or removed; its public subnets, outside VRF, chunk size, bypass or auto-learn prefixes; cgn enabled, max-bindings, max-flows or logger), so it takes full effect after a control-plane restart. False when it changed only a group's limits and timers, which apply at once (existing bindings keep their limits until re-applied). |
status |
string | Always "committed". |
CgnGroup#
| Name | Type | Description |
|---|---|---|
activeBindings |
Live bindings currently in this group. | |
autoLearn |
Array<CgnAutoLearn> | Auto-learn scopes (inside VRF + prefixes). |
bindingTimeoutSeconds |
Idle teardown for auto-learned bindings. | |
bypassPrefixes |
Array<string> | Destinations that bypass NAT (CIDR). |
chunkSize |
Ports per allocated port block. | |
description |
string | Free-text description. |
name |
string | Group name (the key; service plans reference it). |
outbound |
CgnOutbound | |
outsideVrf |
string | null | VRF holding the public side, or null for the default table. |
portCap |
Maximum ports one subscriber may hold. | |
publicSubnets |
Array<string> | Public IPv4 subnets (CIDR) the group allocates from. |
quarantineSeconds |
Quarantine before a freed port block is reused. | |
setupsPerSec |
Per-subscriber NAT setup rate limit. | |
timeouts |
CgnTimeouts | |
utilisation |
CgnGroupUtilisation#
| Name | Type | Description |
|---|---|---|
freeChunks |
Blocks free for allocation. | |
quarantinedChunks |
Recently-freed blocks still in reuse quarantine. | |
totalChunks |
Total port blocks in the pool. | |
usedChunks |
Blocks currently allocated to subscribers. |
CgnGroupWrite#
| Name | Type | Description |
|---|---|---|
autoLearn |
Array<CgnAutoLearn> | Auto-learn scopes (inside VRF + prefixes). |
bindingTimeoutSeconds |
Idle teardown for auto-learned bindings. | |
bypassPrefixes |
Array<string> | Destinations that bypass NAT (CIDR). |
chunkSize |
Ports per allocated port block. | |
description |
string | null | Free-text description. |
name |
string | Group name — the immutable key (service plans reference it). |
outbound |
||
outsideVrf |
string | null | VRF holding the public side (null/empty = default table). |
portCap |
Maximum ports one subscriber may hold before extensions stop. | |
publicSubnets |
Array<string> | Public IPv4 subnets (CIDR) the group allocates from. |
quarantineSeconds |
Quarantine before a freed port block is reused. | |
setupsPerSec |
Per-subscriber NAT setup rate limit. | |
timeouts |
CgnIdentifyBinding#
| Name | Type | Description |
|---|---|---|
sessionId |
BNG session id to associate, when known. | |
subscriberId |
string | null | Subscriber identity for compliance logging (≤ 256 chars). |
CgnNativeCounters#
| Name | Type | Description |
|---|---|---|
autolearnMisses |
Reverse-path misses eligible for auto-learn classification. | |
eventRingDrops |
NAT events dropped because the event ring was full. | |
extensionWanted |
Port-exhaustion events requesting an extension port block. | |
flowCapDrops |
Creates refused by the dynamic per-binding flow cap. | |
mappingCapDrops |
Creates refused because the mapping table was full. | |
noMapping |
Packets to a configured public address dropped for lack of a mapping. |
CgnOutbound#
| Name | Type | Description |
|---|---|---|
allowPrefixes |
Array<string> | Destinations (CIDR) exempt from every block. |
blockPorts |
Array<string> | Further ports, as tcp/23 or udp/137-138. |
blockPrefixes |
Array<string> | Further destinations (CIDR). |
blockPrivate |
boolean | null | Block RFC 1918 and RFC 6598 destinations; on a write, null keeps the existing value. |
blockStandard |
boolean | null | Block SMTP and the Windows RPC, NetBIOS and SMB ports; on a write, null keeps the existing value. |
CgnReclaimBinding#
| Name | Type | Description |
|---|---|---|
bindingIndex |
The binding (as in /api/v1/cgn/bindings). | |
detail |
string | null | Why nothing was given back; null when blocks were. |
heldAfter |
Blocks held now. | |
heldBefore |
Blocks held before. | |
insideIp |
string | null | |
insideVrf |
string | |
outcome |
string | "released", "nothing-reclaimable", "busy" (the top block was taken before the data plane judged it), "pending", "failed" or "not-attempted". |
released |
Array<string> | The port ranges given back, top first. |
CgnReclaimRequest#
| Name | Type | Description |
|---|---|---|
all |
boolean | null | Every binding that holds more than one block, instead of one address. |
group |
string | null | Every binding of this CGN IP group that holds more than one block, instead of one address (the group name in any case). |
insideIp |
string | null | The subscriber's inside IPv4 address. |
vrf |
string | null | Only its binding in this inside VRF ("default" for the global table). |
CgnReclaimResult#
| Name | Type | Description |
|---|---|---|
bindings |
Array<CgnReclaimBinding> | Each binding's result; for `all`, only those that released something, were busy, pending or failed. |
bindingsReleased |
Bindings that gave back at least one block. | |
blocksReleased |
Port blocks given back, over every binding. | |
failed |
Bindings for which nothing was given back, for the reason given. | |
notAttempted |
For `all`: bindings not tried because an earlier one found the data plane not answering (each read is bounded at 250 ms and the run stops at the first). | |
nothingReclaimable |
Bindings with no empty block at the top to give back. | |
pending |
Bindings whose outcome is not known yet (an answer from the data plane was lost; resolved by asking it again — nothing is released until then). |
CgnSettings#
| Name | Type | Description |
|---|---|---|
enabled |
boolean | Whether CGN activates at control-plane start. |
loggerSpoolSize |
Compliance-logger spool size (events buffered per driver). | |
maxBindings |
Global cap on concurrent NAT bindings (table size). | |
maxFlows |
Global cap on concurrent NAT flows (table size). |
CgnStatus#
| Name | Type | Description |
|---|---|---|
activeBindings |
Live NAT bindings right now (0 when not running). | |
autoLearnedBindings |
How many of the live bindings were auto-learned. | |
enabled |
boolean | Whether CGN is enabled in configuration. |
eventsLostByDriver |
Compliance-log events lost per logger driver (null when the logger pump isn't running). | |
groups |
Array<CgnGroup> | The configured IP groups merged with live utilisation. |
maxBindings |
Configured global cap on concurrent NAT bindings. | |
maxFlows |
Configured global cap on concurrent NAT flows. | |
nativeCounters |
CgnNativeCounters | |
running |
boolean | Whether CGN is active in this control-plane process (activates at startup). |
CgnTimeouts#
| Name | Type | Description |
|---|---|---|
icmp |
Idle timeout for ICMP (echo) flows. | |
tcpEstablished |
Idle timeout for established TCP flows. | |
tcpTransitory |
Timeout for transitory TCP states (handshake/teardown). | |
udp |
Idle timeout for UDP flows. | |
udpDns |
Idle timeout for UDP flows a subscriber opens to port 53 (DNS lookups); never longer than `udp`. Always present in a response. Omitted or null in a request, the group keeps the value it has (30 for a new group). |
ProblemDetails#
| Name | Type | Description |
|---|---|---|
detail |
string | null | |
instance |
string | null | |
status |
||
title |
string | null | |
type |
string | null |
Security schemes#
| Name | Type | Scheme | Description |
|---|---|---|---|
| bearerToken | http | bearer | Named API token — the recommended credential for automation. See Authentication in the API overview. |
| sessionCookie | apiKey | Interactive session cookie used by the bundled web UI. Not the integration path for API clients — use a bearer token. See Authentication in the API overview. |
Tags#
| Name | Description |
|---|---|
| CGN | Carrier-grade NAT (NAT44): status, IP groups (public pools), live bindings, and binding identity enrichment. |