Everything you can do in the firewall pages of the Web console can be done through the REST API of the Artica service: the console itself uses it. Use it to script the firewall, or to manage several appliances from one tool.
curl -s --unix-socket /usr/share/artica-postfix/bin/run/articarest.sock http://localhost/firewall/config/rulesX-API-Key header. The service, its port, its key and the networks allowed to reach it are configured as described in The Web API Service.curl -s -H "X-API-Key: <key>" http://192.168.1.10:9503/firewall/config/rulesDo not expose the API port to the Internet. Each write is recorded in the security audit trail; send an
X-Artica-Actorheader (letters, digits,_.@-) to record who made the change.
Success:
{"success": true, "data": …}Failure (HTTP 400, 404 or 500), with one entry per invalid field:
{"success": false, "errors": [{"field": "eth", "error": "{fw_iface_unknown}", "detail": "eth9"}]}PUT requests are partial: only the fields you send are changed.GET /firewall/config/apply-status tells you when.| Method and path | Purpose |
|---|---|
GET /firewall/config/rules | List the rules, with the problems that prevent a rule from being applied. |
GET /firewall/config/rules/{id} | One rule. |
POST /firewall/config/rules | Create a rule; returns its id. |
PUT /firewall/config/rules/{id} | Modify a rule. |
DELETE /firewall/config/rules/{id} | Delete a rule. |
POST /firewall/config/rules/{id}/enable | Body {"enabled": 0} or {"enabled": 1}. |
POST /firewall/config/rules/{id}/move | Body {"dir": "up"} or {"dir": "down"}. |
PUT /firewall/config/rules/{id}/services | The services of the rule (Firewall services tab). |
PUT /firewall/config/rules/{id}/time | The time restriction. |
PUT /firewall/config/rules/{id}/options | The options of the action (mark, port…). |
GET|POST /firewall/config/rules/{id}/ndpi, DELETE …/ndpi/{nid} | Application protocols (deep packet inspection). |
GET /firewall/config/rules/problems | Only the rules that cannot be applied, with the reason. |
GET /firewall/config/rules/sections | The sections already used, sorted. |
GET /firewall/rules/usage | Last use of each rule: first_seen, last_hit (unix time, 0 = never) and unused (no traffic for 30 days). |
Fields of a rule:
| Field | Value |
|---|---|
rulename | Name, required (128 characters at most). |
eth | Interface name (eth0), empty for all interfaces, or a NAT entry (DNAT:3, SNAT:2…). |
service | A service name of GET /firewall/config/services, or all. |
accepttype | ACCEPT, DROP, LOG (Log only), RETURN (stop checking), MARK, TPROXY, NEXTHOPE, MIRROR. On a NAT entry: ACCEPT or DROP only. |
isclient | 1 for an outgoing rule, 0 for an incoming rule. |
jlog | 1 to log every matching packet (Log All Events). |
enabled | 0 or 1. |
description, section | Free text (500 and 64 characters at most). Changing only them does not rebuild the firewall. |
family | both (default), ipv4 or ipv6. |
conn_limit, rate_limit, rate_unit | Connection limits per source of an ACCEPT rule: simultaneous connections (1–65535), new connections (1–10000) per second or minute; 0 = no limit. |
expires | Unix time at which a temporary rule is disabled, 0 = permanent. |
Example — log the DNS queries sent by the appliance:
curl -s --unix-socket /usr/share/artica-postfix/bin/run/articarest.sock \
-X POST -H "Content-Type: application/json" \
-d '{"rulename":"Log outgoing DNS queries","eth":"eth0","service":"dns","accepttype":"LOG","isclient":1,"enabled":1}' \
http://localhost/firewall/config/rules
{"data":{"id":3},"success":true}| Method and path | Purpose |
|---|---|
GET /firewall/config/nics/{iface}/firewall | Firewall settings of an interface. |
PUT /firewall/config/nics/{iface}/firewall | Change them: isFW (linked to the firewall, 0/1), firewall_policy and firewall_policy_out (incoming and outgoing default policy: accept or reject), firewall_behavior (0 not defined, 1 LAN, 2 WAN), firewall_ping (accept, trusted, deny), firewall_artica, denydhcp, AntiDDOS, firewall_masquerade, xtIpv4options (0/1). |
# Link eth1 to the firewall, deny by default, keep the Web console reachable
curl -s --unix-socket /usr/share/artica-postfix/bin/run/articarest.sock -X PUT \
-H "Content-Type: application/json" \
-d '{"isFW":1,"firewall_policy":"reject","firewall_artica":1}' \
http://localhost/firewall/config/nics/eth1/firewallUnless stated otherwise, each one has GET (list), GET /{id}, POST (create), PUT /{id} and DELETE /{id}. Masquerade entries, bandwidth limits, connectors, links and dynamic DNS lists also have POST /{id}/enable (body {"enabled": 0|1}); a NAT entry is switched off with PUT and {"enabled": 0}.
| Path | Object |
|---|---|
/firewall/config/nat | NAT entries: rulename, nat_type (0 destination NAT, 1 source NAT, 2 redirect to the node, 3 route to a node), nic, dstaddr (address or host name), dstaddrport, jlog, enabled, reflection (1: reachable from the internal network) and reflection_addr (public address to target instead of the addresses of the interface). |
/firewall/config/masquerade | Masquerade entries: nic, enabled, include_src and exclude_dst (lists of addresses, networks or ranges; PUT only). |
/firewall/config/services | Services (the path parameter is the service name; create and delete only). |
/firewall/config/shaping | Bandwidth limits. |
/firewall/config/bridges | Interface connectors, and their sources (/{id}/sources). |
POST /firewall/test-packet | Packet tester: verdict and deciding rule for a packet, from the rules actually applied (read-only). Rules accept expires (unix time, 0 = permanent); PUT /firewall/config/rules/{id}/expires extends or removes it. |
/firewall/config/versions | Configuration history: list, differences, restore, POST …/versions/confirm and …/cancel. A change made through the API must be confirmed, or it is rolled back when the delay ends. |
/firewall/config/linkbalance | Link balancer links; GET /firewall/config/linkbalance/status gives the live state of each link. |
/firewall/config/itself | Published servers the appliance must always reach (list, create and delete only). |
/firewall/config/cognix | Dynamic DNS allow lists. |
These settings are versioned: write them through these routes, never through /setinfo, so that the change is recorded and waits for confirmation.
| Method and path | Purpose |
|---|---|
GET / PUT /firewall/config/transit | Unauthorized transit traffic: {"policy": "accept"} or {"policy": "reject"}. |
GET / PUT /firewall/config/ipv6 | IPv6 filtering: {"filtering": 0|1}. |
GET / PUT /firewall/config/autoban | Automatic blocking: {"enabled": 1, "hits": 20, "window": 300, "time": 3600}. |
| Method and path | Purpose |
|---|---|
GET /firewall/config/draft, POST …/draft/open|apply|discard|resume, GET|POST …/draft/preview | Draft and preview. While a draft is open, every write of this API goes into the draft and nothing is applied. |
GET /firewall/config/export | The configuration as an export file (save the response unchanged). |
POST /firewall/config/import/analyze, POST /firewall/config/import/apply | Import a configuration into a draft, with an interface mapping. |
| Method and path | Purpose |
|---|---|
GET /firewall/config/apply-status | state: idle, pending (a change waits for the rebuild) or running; last: the last rebuild and the rules the kernel refused; last_commit: whether the last rule set was accepted. |
GET /firewall/rules/status | Status and packet counters of each rule, as shown in the rules table. |
GET /firewall/events/top?hours=24 | Most active rules, most rejected sources and ports over 1 to 168 hours (Top tab of the events). |
GET /firewall/kernel-modules | The kernel modules and their state (Modules tab). |
GET /firewall/fqdn/status | Resolution state of each name of the host-name objects: last success, last error, number of addresses. |
GET /firewall/autoban, DELETE /firewall/autoban/{ip} | The addresses banned by the automatic blocking; unban one. |
GET /firewall/reconfigure | Rebuild the firewall now (button Apply Firewall rules). |
{"data":{"state":"idle",
"last":{"started":"2026-10-15T03:10:44+02:00","duration_ms":394,"ok":true,"failed":null},
"last_commit":{"at":"2026-10-15T03:10:44+02:00","ok":true,"lines":108,"excluded":null,"duration_ms":165}},
"success":true}If last_commit.ok is false, the kernel refused the new rule set and the previous rules are still in force: see How the firewall applies your rules.