firewall¶
ibox.firewall in the library, ibox firewall in the CLI.
Firewall rules, DMZ, and port-forwarding settings.
status ¶
Get firewall status, including whether UPnP port forwarding is on (UpnpPortForwardingEnable)
set_upnp_enabled ¶
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 ¶
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()).
set_dmz ¶
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 |
set_level ¶
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 |
set_ipv6_level ¶
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 |
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 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 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 ¶
Get whether the router answers pings from the internet, over IPv4 ("enableIPv4") and IPv6 ("enableIPv6").
set_respond_to_ping ¶
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 ¶
Get the protocol forwarding rules: whole IP protocols, e.g. GRE, forwarded from the internet to a device.
set_protocol_forwarding ¶
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 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 ¶
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 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 ¶
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 ¶
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 ¶
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 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 ¶
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 |