Logs and packet capture API
The diagnostics API reads the live service log, switches debug logging on and off, and starts, stops and downloads packet captures. It backs Monitor › Logs and Monitor › Packet capture in the console. For how to use them when troubleshooting, see Logs and debugging.
Base path and permissions
Section titled “Base path and permissions”Tenant routes are relative to /api/v1/t/{tenant}, where {tenant} is the tenant slug or ID. Platform administrators can call the same routes (except capture-options) under /api/v1/platform with the platform:admin permission; there they cover every tenant’s log records and platform-level cloud captures. See API overview for authentication.
| Route | Permission (tenant) |
|---|---|
GET /diag/logs |
monitor:read |
GET /diag/debug |
monitor:read |
PUT /diag/debug |
admin:write |
GET /diag/capture-options |
admin:read |
GET /diag/captures |
admin:read |
POST /diag/captures |
admin:write |
POST /diag/captures/{id}/stop |
admin:write |
GET /diag/captures/{id}/pcap |
admin:write |
DELETE /diag/captures/{id} |
admin:write |
Airgate keeps the newest 5000 log records of each server instance in memory, each with an increasing id. Records are lost when the service restarts. Tenants see only their own records; platform administrators see all.
GET /diag/logs
Section titled “GET /diag/logs”Permission: monitor:read
| Query | Type | Meaning |
|---|---|---|
q |
string | Searches the message and attribute values. |
level |
string | Lowest level shown: debug, info, warn or error. |
module |
string | Only records of this Airgate module (for example radius). |
after |
integer | Only records newer than this id. Use it to tail the log. |
limit |
integer | Default 500, at most 2000. |
curl -s "$AIRGATE/api/v1/t/$TENANT/diag/logs?level=info&module=radius&limit=100" \ -H "Authorization: Bearer $TOKEN"Response 200:
{"items": [{"id": 8121, "time": "2026-11-19T10:41:07.3Z", "level": "INFO", "module": "radius", "msg": "RADIUS accept", "attrs": {"user": "alice@contoso.com", "nad": "10.0.0.4", "rule": "Staff"}}], "total": 1, "debug_until": null}debug_until is the time debug logging turns itself off, or null when it is off. When the log buffer is not available the request answers 409.
GET /diag/debug
Section titled “GET /diag/debug”Permission: monitor:read
Response 200: {"debug_until": "2026-11-19T11:00:00Z"} or {"debug_until": null}.
PUT /diag/debug
Section titled “PUT /diag/debug”Permission: admin:write
Turns debug logging on for a number of minutes, or off. It turns itself off when the time is up.
| Field | Type | Meaning |
|---|---|---|
minutes |
integer | 0 turns debug logging off; at most 60. Anything else answers 400. |
For a tenant, only that tenant’s debug records are kept; the RADIUS service then logs one line per request with the user, MAC, network device, matched rule, the full policy trace and the reply attributes. On the platform route, every module’s debug records are kept.
curl -s -X PUT "$AIRGATE/api/v1/t/$TENANT/diag/debug" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"minutes":15}'Response 200: {"debug_until": "…"}. The change is audited (object type debug_logging).
Packet captures
Section titled “Packet captures”A capture records the traffic of one protocol (or custom ports), optionally limited to some hosts, for 5–600 seconds or a number of packets, and keeps the pcap file for 24 hours. A capture can run in two places:
- cloud: Airgate’s RADIUS service captures the RADIUS and RadSec traffic your network devices send to the cloud. A tenant’s cloud capture is always limited to the addresses of its network devices that send RADIUS directly (not through a site connector); a host outside them is refused.
- edge: a site connector captures on its own host and uploads the file. The connector needs raw-socket privileges.
Presets
Section titled “Presets”preset |
Traffic |
|---|---|
radius |
UDP 1812, 1813, 1645, 1646, 3799 |
radsec |
radius ports plus TCP 2083 |
tacacs |
TCP 49 |
coa |
UDP 3799, 1700 |
dhcp |
UDP 67, 68 |
syslog |
UDP 514, TCP 514, 6514 |
ldap |
TCP 389, 636, 3268, 3269 |
kerberos |
UDP and TCP 88 |
custom |
The ports you give in udp_ports and tcp_ports. |
The filter matches IPv4 and IPv6 UDP and TCP by port (either direction) and host prefix, including VLAN-tagged frames.
GET /diag/capture-options
Section titled “GET /diag/capture-options”Permission: admin:read
What the capture form can offer.
{"cloud": true, "presets": {"radius": {"udp_ports": [1812, 1813, 1645, 1646, 3799]}, "…": {}}, "edges": [{"id": "7a0c…", "name": "London office", "online": true}], "nads": ["10.0.0.0/24"]}cloud is false when cloud capture is not set up on this deployment. nads lists the prefixes a cloud capture is limited to.
GET /diag/captures
Section titled “GET /diag/captures”Permission: admin:read
The latest 100 captures, newest first. Response 200: {"items": [Capture], "total": N}.
POST /diag/captures
Section titled “POST /diag/captures”Permission: admin:write
| Field | Type | Meaning |
|---|---|---|
name |
string | Label, at most 100 characters. |
target |
string | cloud (default) or edge. |
edge_id |
UUID | The site connector. Required for edge. |
preset |
string | A preset name. Any other value is treated as custom. |
udp_ports, tcp_ports |
string | For custom: ports separated by commas or spaces. At least one port. |
hosts |
string | Addresses or prefixes, comma-separated. Empty: for a tenant cloud capture, all of the tenant’s network device addresses. |
duration_sec |
integer | 5–600. Required. |
max_packets |
integer | Default 10 000, at most 100 000. |
curl -s -X POST "$AIRGATE/api/v1/t/$TENANT/diag/captures" \ -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \ -d '{"name":"Alice laptop","target":"cloud","preset":"radius", "hosts":"10.0.0.4, 10.0.1.0/24","duration_sec":60,"max_packets":10000}'Response 201: the capture.
{"id": "c41d…", "tenant_id": "…", "target": "cloud", "edge_id": null, "name": "Alice laptop", "preset": "radius", "filter": {"udp_ports": [1812, 1813, 1645, 1646, 3799], "hosts": ["10.0.0.4/32", "10.0.1.0/24"]}, "duration_sec": 60, "max_packets": 10000, "status": "running", "packets": 0, "size_bytes": 0, "stopped": "", "error": "", "created_by": "alice@contoso.com", "created_at": "2026-11-19T10:40:00Z", "started_at": "2026-11-19T10:40:00Z", "finished_at": null, "expires_at": "2026-11-20T10:40:00Z"}| Capture field | Meaning |
|---|---|
status |
queued, running, done, failed or cancelled. |
stopped |
Why it ended: duration, packets, size or cancelled. |
edge_name |
Name of the site connector (edge captures). |
error |
Why it failed. |
Errors: 400 for a duration outside 5–600, bad ports or hosts, a host outside your network devices’ addresses, or a missing edge_id; 409 when cloud capture is not set up or the site connector cannot take the job.
POST /diag/captures/{id}/stop
Section titled “POST /diag/captures/{id}/stop”Permission: admin:write
Ends the capture early. The packets captured so far are kept. Response 200: the capture. A capture that has already ended answers 409.
GET /diag/captures/{id}/pcap
Section titled “GET /diag/captures/{id}/pcap”Permission: admin:write
Downloads the capture file (application/vnd.tcpdump.pcap). Open it in Wireshark.
curl -s -o capture.pcap "$AIRGATE/api/v1/t/$TENANT/diag/captures/c41d…/pcap" \ -H "Authorization: Bearer $TOKEN"DELETE /diag/captures/{id}
Section titled “DELETE /diag/captures/{id}”Permission: admin:write
Deletes the capture and its file. Response 204.
Starting, downloading and deleting a capture is audited (object type packet_capture). Captures are deleted automatically 24 hours after they are created.