create_firewall_rule
create_firewall_rule
Section titled “create_firewall_rule”Create a firewall rule on the controller.
Side effects:
- Adds a new rule into the named
rulesetat the givenrule_index. Rules with lower indexes evaluate first. - Takes effect immediately on the next packet hitting the affected datapath.
- Mutates controller state. Use dry_run=True to preview the change without applying.
Example
Section titled “Example”create_firewall_rule(name="Allow IoT to Plex", ruleset="LAN_IN", action="accept", protocol="tcp", src_networkconf_id="65f...", dst_networkconf_id="65a...", dst_port="32400")Parameters
Section titled “Parameters”| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
name |
string |
yes | — | Display name for the rule (e.g. "Block iot to LAN"). |
ruleset |
string |
yes | — | Where the rule is enforced. Common values: "LAN_IN", "LAN_OUT", "LAN_LOCAL", "WAN_IN", "WAN_OUT", "WAN_LOCAL", "GUEST_IN", "GUEST_OUT", "GUEST_LOCAL". |
action |
string |
yes | — | "accept", "drop", or "reject". |
rule_index |
integer |
no | 20000 | Evaluation order. Lower = evaluated first. On UniFi Network 9.x (Zone-Based Firewall), user-defined LAN_IN rules live at 20000 and above; lower bands are reserved by the controller and will fail with api.err.FirewallRuleIndexOutOfRange. 20000 is the safe default. (Older controllers used 2000-3999.) |
protocol |
string |
no | “all” | "all", "tcp", "udp", "icmp", etc. Port matches require "tcp" or "udp". |
src_address |
string |
no | “” | Source CIDR (e.g. "10.50.0.0/24"). Empty = any. |
dst_address |
string |
no | “” | Destination CIDR. Empty = any. |
src_networkconf_id |
string |
no | “” | Source network _id. Use this OR src_address. |
dst_networkconf_id |
string |
no | “” | Destination network _id. Use this OR dst_address. |
src_networkconf_type |
string |
no | “NETv4” | Discriminator that pairs with src_networkconf_id. UniFi Network 9.x ZBF requires this whenever a rule references a network conf by _id and returns api.err.FirewallRuleNetworkConfTypeRequired otherwise. Defaults to "NETv4" (IPv4 network). Only emitted to the controller when src_networkconf_id is set. |
dst_networkconf_type |
string |
no | “NETv4” | Discriminator that pairs with dst_networkconf_id. Same semantics as src_networkconf_type. Defaults to "NETv4". |
src_port |
string |
no | “” | Source port match. Single port ("443"), CSV ("80,443"), or range ("3000-3100"). Empty = any. Requires protocol set to "tcp" or "udp". |
dst_port |
string |
no | “” | Destination port match. Same syntax as src_port. The headline use case: dst_port="32400" with protocol="tcp" to allow IoT→Plex without opening the rest of MGMT. |
enabled |
boolean |
no | true | False creates the rule disabled for staging. |
controller |
string |
no | “default” | Name of the UniFi controller to target. Defaults to "default". |
dry_run |
boolean |
no | false | Preview the change without applying it. Returns the predicted change set. |