create_firewall_rule

create_firewall_rule

Create a firewall rule on the controller.

Side effects:

• Adds a new rule into the named ruleset at the given rule_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

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

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.