Skip to content

firewall

ibox.firewall in the library, ibox firewall in the CLI.

Firewall rules, DMZ, and port-forwarding settings.

status

status() -> str

Get firewall status, including whether UPnP port forwarding is on (UpnpPortForwardingEnable)

set_upnp_enabled

set_upnp_enabled(enable: bool) -> str

Turn UPnP port forwarding on or off, like the UPnP switch in the web UI's port forwarding settings.

With UPnP on, devices such as game consoles open ports to the internet themselves.

Parameters:

Name Type Description Default
enable bool

True to turn UPnP on, False to turn it off.

required

Returns:

Name Type Description
str str

response content

upnp_description

upnp_description() -> str

Get how the router presents itself to devices over UPnP: its name ("FriendlyName"), model and provider, and whether its UPnP service runs ("Enable"). Whether devices may open ports with UPnP is separate (see status()).

dmz

dmz() -> str

Get DMZ status

set_dmz

set_dmz(destination_ip: str) -> str

Expose a device to the internet (DMZ host).

Incoming connections that no port forwarding rule matches go to this device instead of being blocked. Only use it for a device that is safe to expose directly to the internet.

Parameters:

Name Type Description Default
destination_ip str

LAN IP address of the device, e.g. "192.168.1.20".

required

Returns:

Name Type Description
str str

response content

delete_dmz

delete_dmz() -> str

Remove the DMZ host set in the web UI or with set_dmz.

level

level() -> str

Get IPv4 firewall level

set_level

set_level(level: Literal['Low', 'Medium', 'High', 'Custom']) -> str

Set the IPv4 firewall level.

Parameters:

Name Type Description Default
level str

"Low" (Off in the web UI), "Medium" (Balanced), "High" (Strict) or "Custom" (custom rules).

required

Returns:

Name Type Description
str str

response content

ipv6_level

ipv6_level() -> str

Get IPv6 firewall level

set_ipv6_level

set_ipv6_level(level: Literal['Off', 'Medium', 'High', 'Custom']) -> str

Set the IPv6 firewall level.

Parameters:

Name Type Description Default
level str

"Off", "Medium" (Balanced in the web UI), "High" (Strict) or "Custom" (custom rules).

required

Returns:

Name Type Description
str str

response content

port_forwarding

port_forwarding() -> str

Get port forwarding rules

set_port_forwarding

set_port_forwarding(name: str, destination_ip: str, external_port: str, internal_port: str | None = None, protocol: Literal['tcp', 'udp', 'both'] = 'both', enabled: bool = True) -> str

Add a port forwarding rule, or update the rule with this name.

The rule shows up in the web UI like rules created there, with the ID webui_<name>.

Parameters:

Name Type Description Default
name str

rule name, e.g. "minecraft".

required
destination_ip str

LAN IP address of the device to forward to, e.g. "192.168.1.20".

required
external_port str

port on the internet side, e.g. "25565", or a range such as "8000-8010".

required
internal_port str | None

port on the device. Default is the same as external_port. For a range of external ports, give the same range, or a single port to send the whole range to it.

None
protocol str

"tcp", "udp" or "both". Default is "both".

'both'
enabled bool

whether the rule is active. Default is True.

True

Returns:

Name Type Description
str str

response content, including the stored rule

delete_port_forwarding

delete_port_forwarding(name: str) -> str

Delete a port forwarding rule created in the web UI or with set_port_forwarding.

Parameters:

Name Type Description Default
name str

rule name, or its ID as listed by port_forwarding() (e.g. "webui_minecraft").

required

Returns:

Name Type Description
str str

response content

delete_all_port_forwarding

delete_all_port_forwarding() -> str

Delete all port forwarding rules created in the web UI or with set_port_forwarding(). They can't be brought back. Ports that devices opened themselves with UPnP stay open.

Returns:

Name Type Description
str str

response content

respond_to_ping

respond_to_ping() -> str

Get whether the router answers pings from the internet, over IPv4 ("enableIPv4") and IPv6 ("enableIPv6").

set_respond_to_ping

set_respond_to_ping(enable: bool, ip_version: Literal[4, 6] | None = None) -> str

Choose whether the router answers pings from the internet.

Parameters:

Name Type Description Default
enable bool

True to answer pings, False to ignore them.

required
ip_version int | None

4 or 6 to change only IPv4 or IPv6. Default: both.

None

Returns:

Name Type Description
str str

response content

protocol_forwarding

protocol_forwarding() -> str

Get the protocol forwarding rules: whole IP protocols, e.g. GRE, forwarded from the internet to a device.

set_protocol_forwarding

set_protocol_forwarding(name: str, destination_ip: str, protocol: str, enabled: bool = True) -> str

Forward a whole IP protocol from the internet to a device, or update the rule with this name.

Port forwarding forwards TCP and UDP ports; this forwards protocols without ports, e.g. GRE for a PPTP VPN server or ESP for an IPsec one.

Parameters:

Name Type Description Default
name str

rule name, e.g. "vpn".

required
destination_ip str

LAN IP address of the device to forward to, e.g. "192.168.1.20".

required
protocol str

a protocol number from 0 to 255 or "gre", "esp" or "ah", or several separated by commas, e.g. "esp,ah".

required
enabled bool

whether the rule is active. Default is True.

True

Returns:

Name Type Description
str str

response content

delete_protocol_forwarding

delete_protocol_forwarding(name: str) -> str

Delete a protocol forwarding rule.

Parameters:

Name Type Description Default
name str

rule name, as given to set_protocol_forwarding().

required

Returns:

Name Type Description
str str

response content

ipv6_pinholes

ipv6_pinholes() -> str

Get the IPv6 pinholes: ports open from the internet to a device's IPv6 address.

set_ipv6_pinhole

set_ipv6_pinhole(name: str, destination_ip: str, port: str, protocol: Literal['tcp', 'udp', 'both'] = 'both', enabled: bool = True) -> str

Open a port from the internet to a device's IPv6 address (a pinhole), or update the pinhole with this name.

IPv6 needs no port forwarding: devices have their own public IPv6 addresses, which the firewall protects. A pinhole lets connections to one port of one address through.

Parameters:

Name Type Description Default
name str

pinhole name, e.g. "minecraft".

required
destination_ip str

the device's public IPv6 address, e.g. "2001:db8::20". devices.summary() and get() list devices' addresses.

required
port str

port, e.g. "25565", or a range such as "8000-8010".

required
protocol str

"tcp", "udp" or "both". Default is "both".

'both'
enabled bool

whether the pinhole is open. Default is True.

True

Returns:

Name Type Description
str str

response content

delete_ipv6_pinhole

delete_ipv6_pinhole(name: str) -> str

Delete an IPv6 pinhole.

Parameters:

Name Type Description Default
name str

pinhole name, as given to set_ipv6_pinhole().

required

Returns:

Name Type Description
str str

response content

custom_rule

custom_rule(chain: Literal['Custom', 'Custom_V6Out', 'Custom_V6In'] | None = None) -> str

Get the custom firewall rules of a chain: "Custom" (IPv4, the default), "Custom_V6Out" or "Custom_V6In" (IPv6).

custom_rules() lists the rules of all three chains in short form.

custom_rules

custom_rules() -> str

A short list of the custom firewall rules, IPv4 and IPv6, like the web UI's list.

Custom rules only apply while the firewall level is "Custom" (see level() and ipv6_level()). Traffic that no rule matches gets the basic action in custom_policy().

Returns:

Name Type Description
str str

a JSON array, e.g. [{"name": "Telnet", "port": "23", "action": "block", "ip_version": 4, "direction": "outbound", "protocol": "tcp", "device": null, "enabled": true, "id": "1732101234567_1", "chain": "Custom"}]

set_custom_rule

set_custom_rule(name: str, port: str, action: Literal['allow', 'block'], ip_version: Literal[4, 6] = 4, direction: Literal['outbound', 'inbound'] = 'outbound', protocol: Literal['tcp', 'udp', 'both'] = 'both', device: str | None = None, enabled: bool = True) -> str

Add a custom firewall rule, or change the rule with this name, like the web UI's custom firewall.

The rule only applies while the firewall level of its IP version is "Custom" (see set_level() and set_ipv6_level()). Outbound rules allow or block traffic from your devices to these ports on the internet; inbound rules (IPv6 only) traffic from the internet to these ports on your devices.

Parameters:

Name Type Description Default
name str

rule name, 1 to 40 letters, digits, spaces or symbols, e.g. "Telnet".

required
port str

destination port, e.g. "23", or a range such as "8000-8010".

required
action str

"allow" or "block".

required
ip_version int

4 or 6. Default is 4.

4
direction str

"outbound" or "inbound". IPv4 rules are outbound only. Default is "outbound".

'outbound'
protocol str

"tcp", "udp" or "both". Default is "both".

'both'
device str | None

MAC address of the only device the rule applies to. Default: all devices.

None
enabled bool

whether the rule is on. Default is True.

True

Returns:

Name Type Description
str str

response content, with the rule's ID. A changed rule gets a new ID, as in the web UI.

Raises:

Type Description
ValueError

if the web UI would refuse the rule: for instance because it overlaps another rule of the same IP version and direction, or covers all ports (1-65535) with the opposite of the basic action in custom_policy().

enable_custom_rule

enable_custom_rule(name: str, enable: bool = True) -> str

Turn a custom firewall rule on or off, like its switch in the web UI.

Parameters:

Name Type Description Default
name str

rule name, as listed by custom_rules().

required
enable bool

True to turn the rule on, False to turn it off. Default is True.

True

Returns:

Name Type Description
str str

response content

delete_custom_rule

delete_custom_rule(name: str) -> str

Delete a custom firewall rule.

Parameters:

Name Type Description Default
name str

rule name, as listed by custom_rules().

required

Returns:

Name Type Description
str str

response content

custom_policy

custom_policy() -> str

What the custom firewall does with traffic that no custom rule matches: "allow" or "block".

This is the basic setting of the web UI's custom firewall, for IPv4 and for each IPv6 direction. It only applies while the firewall level is "Custom".

Returns:

Name Type Description
str str

a JSON object, e.g. {"ipv4": "allow", "ipv6_outbound": "allow", "ipv6_inbound": "block"}

set_custom_policy

set_custom_policy(action: Literal['allow', 'block'], ip_version: Literal[4, 6] = 4, direction: Literal['outbound', 'inbound'] = 'outbound') -> str

Set what the custom firewall does with traffic that no custom rule matches, like its basic setting in the web UI.

It only applies while the firewall level of this IP version is "Custom". Blocking outbound traffic then cuts devices off the internet, except for the ports that custom rules allow.

Parameters:

Name Type Description Default
action str

"allow" or "block".

required
ip_version int

4 or 6. Default is 4.

4
direction str

"outbound" or "inbound" (IPv6 only). Default is "outbound".

'outbound'

Returns:

Name Type Description
str str

response content