Manage IP firewall rules

These methods manage the rules of the IP Firewall in System Management: which source addresses may reach the web interface, SIP, SSH, TFTP and the database. Use them to keep the allowed addresses in sync with your own inventory, for example to add the address of a new partner automatically. How the types, the default rules and the order work is explained in Set up the firewall.

Only the root customer may call these methods. They return status set to OK, not result.

Rule structure

listFirewallRules returns the rules as structs with these members. addFirewallRule and updateFirewallRule take the same names.

Name	Type	Description
i_firewall_rule	int	ID of the rule
type	string	Name of the type, for example Web. The description of the type in listFirewallTypes
system	boolean	True for the built-in default rule of the type. It cannot be deleted or moved; only allow can change
ip	string	IPv4 address, for example 203.0.113.0
netmask	string	Netmask in dotted-decimal form, for example 255.255.255.0. 255.255.255.255 is a single address, 0.0.0.0 any address
allow	boolean	True allows the addresses, False denies them. Rule in the panel
order_num	int	Position of the rule within its type, from 1. Lower numbers are checked first
description	string	Free text
last_rule	boolean	True for the rule with the highest order_num of its type, the default rule included

listFirewallTypes

Lists the firewall types, one per service the firewall protects. The IDs differ between switches, so read them before you add a rule.

Parameters

None.

Returns

Name	Type	Description
status	string	OK
types	array	Structs with i_firewall_type (int) and description (string), sorted by description

Example

request

call("listFirewallTypes", {})

response

{
    "status": "OK",
    "types": [
        {"i_firewall_type": 5, "description": "DB"},
        {"i_firewall_type": 2, "description": "SIP"},
        {"i_firewall_type": 4, "description": "SSH"},
        {"i_firewall_type": 3, "description": "TFTP"},
        {"i_firewall_type": 1, "description": "Web"},
    ],
}

listFirewallRules

Lists all rules of all types. The rules are sorted by type name; within a type, your rules come first by order_num and the default rule comes last.

Parameters

None.

Returns

Name	Type	Description
status	string	OK
rules	array	The rules, see the rule structure

Example

request

call("listFirewallRules", {})

response

{
    "status": "OK",
    "rules": [
        {
            "i_firewall_rule": 42,
            "type": "Web",
            "system": False,
            "ip": "198.51.100.0",
            "netmask": "255.255.255.0",
            "allow": True,
            "order_num": 1,
            "description": "Office network",
            "last_rule": False,
        },
        {
            "i_firewall_rule": 1,
            "type": "Web",
            "system": True,
            "ip": "0.0.0.0",
            "netmask": "0.0.0.0",
            "allow": False,
            "order_num": 99,
            "description": "Default rule",
            "last_rule": True,
        },
    ],
}

addFirewallRule

Adds a rule to a type. The new rule is placed after the existing rules of the type.

Parameters

Name	Type	Required	Description
i_firewall_type	int	yes	Type of the rule, from listFirewallTypes
ip	string	yes	IPv4 address
netmask	string	no	Netmask. Default 255.255.255.255, a single address
allow	boolean	no	True to allow, False to deny. Default False
description	string	no	Free text

Returns

Name	Type	Description
status	string	OK
i_firewall_rule	int	ID of the new rule

Example

request

call("addFirewallRule", {
    "i_firewall_type": 1,
    "ip": "203.0.113.0",
    "netmask": "255.255.255.0",
    "allow": True,
    "description": "Partner office",
})

response

{"status": "OK", "i_firewall_rule": 43}

updateFirewallRule

Changes a rule. Members you do not send keep their values. Of a default rule (system is True) only allow changes; the other members are ignored.

Parameters

Name	Type	Required	Description
i_firewall_rule	int	yes	ID of the rule
allow	boolean	no	True to allow, False to deny
i_firewall_type	int	no	Type of the rule
ip	string	no	IPv4 address
netmask	string	no	Netmask
description	string	no	Free text

Returns

Name	Type	Description
status	string	OK
i_firewall_rule	int	ID of the rule

Example

Deny any address that no rule above allows, by changing the default rule of Web:

request

call("updateFirewallRule", {"i_firewall_rule": 1, "allow": False})

response

{"status": "OK", "i_firewall_rule": 1}

deleteFirewallRule

Deletes a rule. The rules after it move up one position. Default rules cannot be deleted.

Parameters

Name	Type	Required	Description
i_firewall_rule	int	yes	ID of the rule

Returns

Name	Type	Description
status	string	OK
i_firewall_rule	int	ID of the deleted rule

Example

request

call("deleteFirewallRule", {"i_firewall_rule": 43})

response

{"status": "OK", "i_firewall_rule": 43}

moveFirewallRule

Moves a rule one position up or down within its type, the same as Up and Down in the panel. To move a rule further, call the method several times.

Parameters

Name	Type	Required	Description
i_firewall_rule	int	yes	ID of the rule
direction	string	yes	up or down

Returns

Name	Type	Description
status	string	OK
i_firewall_rule	int	ID of the rule
moved	boolean	False when nothing changed: the rule is a default rule, already first (up) or already last (down). This is not a fault

Example

request

call("moveFirewallRule", {"i_firewall_rule": 43, "direction": "up"})

response

{"status": "OK", "i_firewall_rule": 43, "moved": True}

Errors

faultCode	faultString	Cause
400	i_firewall_type is required and must be an integer., i_firewall_rule is required and must be an integer.	The ID is missing or not a number
400	"IP Address" field has incorrect format.	ip is not an IP address
400	"Netmask" field has incorrect format.	netmask is not a dotted-decimal netmask with contiguous bits, such as 255.255.255.0
400	direction must be 'up' or 'down'.	Wrong direction in moveFirewallRule
401	You do not have permissions to use this API call.	The authenticated customer is not the root customer
404	Firewall rule not found.	No rule with this ID
404	Firewall rule not found or is a system rule.	deleteFirewallRule was called for a default rule
500	Cannot update firewall rule., Cannot move up firewall rule., Cannot move down firewall rule.	The rule changed at the same time, for example in the panel. List the rules again and retry

Caution

Allow your own address for Web before you deny the default rule of Web, or you lose access to the panel and to the API.

Related

• Set up the firewall: types, default rules and the order of checks
• Security management
• Manage network services