Firewall configuration API

This API is based on the Device Configuration API framework. For guidance on how to use these APIs, please refer to the Device Configuration APIs section in the VAPIX®.

Overview

The Firewall Configuration API makes it possible to add, fetch, edit, reorder, and remove existing firewall rules. With this API, you can also activate/deactivate the firewall, check if firewall is active, and test the firewall rules before saving.

info

This API includes operations on sensitive data. You must use a secured channel for the communication transmissions.

Use cases

Manage firewall

The Firewall Configuration API can activate or deactivate the firewall, and check if the firewall is activated.

Activate firewall

This example shows how to use firewall.v1.activated to activate the firewall.

JSON request:

PATCH /config/rest/firewall/v1/activated HTTP/1.1
HOST: my-device
Content-Type: application/json

{
    "data": true
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Check if the firewall is activated

This example shows how to use firewall.v1.activated to check if the firewall is activated.

JSON request:

GET /config/rest/firewall/v1/activated HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "data": "true"
}

Manage firewall rules

You can apply the firewall rules to filter or rate limit inbound traffic to the device.

During a test run, the pendingRules are active and the firewall rules remain in the pendingRules list until they are either confirmed by using confirmRules or cleared by using clearPendingRules.

Custom errors

Error code	Error message	Description
`100`	Invalid IP address.	The IP address is not a valid IPv4 or IPv6 address.
`103`	Invalid request.	The request doesn't meet the internal requirements. See the following use cases.

Get active default firewall policy

This example shows how to use firewall.v1.conf.rules.activeDefaultPolicy to get the active default firewall policy.

JSON request:

GET /config/rest/firewall/v1/conf/rules/activeDefaultPolicy HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "data": "DROP"
}

Get pending default firewall policy

This example shows how to use firewall.v1.conf.rules.pendingDefaultPolicy to get the pending default firewall policy.

JSON request:

GET /config/rest/firewall/v1/conf/rules/pendingDefaultPolicy HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success",
  "data": "DROP"
}

List all firewall rules

This example shows how to use firewall.v1.conf.rules to get a list of all firewall rules.

JSON request:

GET /config/rest/firewall/v1/conf/rules HTTP/1.1
HOST: my-device
Content-Type: application/json

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "status": "success",
    "data": {
        "activeRules": [
            {
                "ruleType": "FILTER",
                "ip": null,
                "ipRange": {
                    "start": "192.168.2.10",
                    "end": "192.168.2.128"
                },
                "mac": null,
                "tcpPort": 80,
                "udpPort": null,
                "port": null,
                "portRange": null,
                "pktType": null,
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "FILTER",
                "ip": "192.168.0.14",
                "mac": null,
                "tcpPort": 80,
                "udpPort": null,
                "port": null,
                "portRange": null,
                "pktType": null,
                "filter": {
                    "policy": "ACCEPT"
                }
            },
            {
                "ruleType": "FILTER",
                "ip": null,
                "mac": null,
                "tcpPort": null,
                "udpPort": null,
                "port": null,
                "portRange": {
                    "portType": "UDP",
                    "start": 161,
                    "end": 162
                },
                "pktType": null,
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "FILTER",
                "ip": "192.168.1.0/20",
                "mac": null,
                "tcpPort": 80,
                "udpPort": null,
                "port": null,
                "portRange": null,
                "pktType": null,
                "filter": {
                    "policy": "ACCEPT"
                }
            },
            {
                "ruleType": "FILTER",
                "ip": null,
                "mac": "00:1B:63:84:45:E6",
                "tcpPort": null,
                "udpPort": null,
                "port": {
                    "portType": "TCP",
                    "portNum": 22
                },
                "portRange": null,
                "pktType": null,
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "LIMIT",
                "ip": null,
                "mac": null,
                "tcpPort": null,
                "udpPort": null,
                "port": {
                    "portType": "TCP",
                    "portNum": 443
                },
                "portRange": null,
                "pktType": null,
                "limit": {
                    "amount": 20,
                    "period": "MINUTE",
                    "unit": "NEWCONNECTIONS",
                    "burst": 10
                }
            },
            {
                "ruleType": "LIMIT",
                "ip": null,
                "mac": null,
                "tcpPort": null,
                "udpPort": null,
                "port": null,
                "portRange": null,
                "pktType": "MULTICAST",
                "limit": {
                    "amount": 100,
                    "period": "SECOND",
                    "unit": "NEWCONNECTIONS",
                    "burst": 50
                }
            }
        ],
        "activeDefaultPolicy": "ACCEPT",
        "pendingRules": [],
        "pendingDefaultPolicy": null,
        "testTimeLeft": 0
    }
}

Edit firewall rules

This example shows how to use firewall.v1.conf.setRules to edit the existing firewall rules.

The changes are written to the activeRules list. If fallbackTime is set to 0, the changes are immediately applied and the current pendingRules is cleared.

info

If you set rules with fallbackTime greater than 0 when the firewall is inactive, error 103 is returned.

For each rule, only one option from layer 2, 3, or 4 is allowed. To apply a rule to multiple options within the same network layer, you must create separate rules.

JSON request:

POST /config/rest/firewall/v1/conf/setRules HTTP/1.1
HOST: my-device
Content-Type: application/json

{
    "data": {
        "rules": [
            {
                "ruleType": "FILTER",
                "ipRange": {
                    "start": "192.168.2.10",
                    "end": "192.168.2.128"
                },
                "tcpPort": 80,
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "FILTER",
                "ip": "192.168.2.16",
                "tcpPort": 80,
                "filter": {
                    "policy": "ACCEPT"
                }
            },
            {
                "ruleType": "FILTER",
                "portRange": {
                    "portType": "UDP",
                    "start": 161,
                    "end": 162
                },
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "FILTER",
                "ip": "192.168.1.0/20",
                "tcpPort": 80,
                "filter": {
                    "policy": "ACCEPT"
                }
            },
            {
                "ruleType": "FILTER",
                "mac": "00:1B:63:84:45:E6",
                "port": {
                    "portType": "TCP",
                    "portNum": 22
                },
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "LIMIT",
                "port": {
                    "portType": "TCP",
                    "portNum": 443
                },
                "limit": {
                    "amount": 20,
                    "period": "MINUTE",
                    "unit": "NEWCONNECTIONS",
                    "burst": 10
                }
            },
            {
                "ruleType": "LIMIT",
                "pktType": "MULTICAST",
                "limit": {
                    "amount": 100,
                    "period": "SECOND",
                    "unit": "NEWCONNECTIONS",
                    "burst": 50
                }
            }
        ],
        "fallbackTime": 30,
        "defaultPolicy": "ACCEPT"
    }
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Reorder firewall rules

This example shows how to use firewall.v1.conf.setRules to reorder the existing firewall rules.

The changes are written to the activeRules list. If fallbackTime is set to 0, the changes are immediately applied and the current pendingRules is cleared.

info

If you set rules with fallbackTime greater than 0 when the firewall is inactive, error 103 is returned.

JSON request:

POST /config/rest/firewall/v1/conf/setRules HTTP/1.1
HOST: my-device
Content-Type: application/json

{
    "data": {
        "rules": [
            {
                "ruleType": "FILTER",
                "ip": "192.168.1.0/20",
                "tcpPort": 80,
                "filter": {
                    "policy": "ACCEPT"
                }
            },
            {
                "ruleType": "FILTER",
                "ip": "192.168.2.16",
                "tcpPort": 80,
                "filter": {
                    "policy": "ACCEPT"
                }
            },
            {
                "ruleType": "FILTER",
                "ipRange": {
                    "start": "192.168.2.10",
                    "end": "192.168.2.128"
                },
                "tcpPort": 80,
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "FILTER",
                "portRange": {
                    "portType": "UDP",
                    "start": 161,
                    "end": 162
                },
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "FILTER",
                "mac": "00:1B:63:84:45:E6",
                "port": {
                    "portType": "TCP",
                    "portNum": 22
                },
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "LIMIT",
                "pktType": "MULTICAST",
                "limit": {
                    "amount": 100,
                    "period": "SECOND",
                    "unit": "NEWCONNECTIONS",
                    "burst": 50
                }
            },
            {
                "ruleType": "LIMIT",
                "port": {
                    "portType": "TCP",
                    "portNum": 443
                },
                "limit": {
                    "amount": 20,
                    "period": "MINUTE",
                    "unit": "NEWCONNECTIONS",
                    "burst": 10
                }
            }
        ],
        "fallbackTime": 30,
        "defaultPolicy": "ACCEPT"
    }
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Remove firewall rules

This example shows how to use firewall.v1.conf.setRules to remove the existing firewall rules.

The changes are written to the activeRules list. If fallbackTime is set to 0, the changes are immediately applied and the current pendingRules is cleared.

info

If you set rules with fallbackTime greater than 0 when the firewall is inactive, error 103 is returned.

JSON request:

POST /config/rest/firewall/v1/conf/setRules HTTP/1.1
HOST: my-device
Content-Type: application/json

{
    "data": {
        "rules": [
            {
                "ruleType": "FILTER",
                "ip": "192.168.2.16",
                "tcpPort": 80,
                "filter": {
                    "policy": "ACCEPT"
                }
            },
            {
                "ruleType": "FILTER",
                "ipRange": {
                    "start": "192.168.2.10",
                    "end": "192.168.2.128"
                },
                "tcpPort": 80,
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "FILTER",
                "portRange": {
                    "portType": "UDP",
                    "start": 161,
                    "end": 162
                },
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "FILTER",
                "mac": "00:1B:63:84:45:E6",
                "port": {
                    "portType": "TCP",
                    "portNum": 22
                },
                "filter": {
                    "policy": "DROP"
                }
            },
            {
                "ruleType": "LIMIT",
                "port": {
                    "portType": "TCP",
                    "portNum": 443
                },
                "limit": {
                    "amount": 20,
                    "period": "MINUTE",
                    "unit": "NEWCONNECTIONS",
                    "burst": 10
                }
            }
        ],
        "fallbackTime": 30,
        "defaultPolicy": "ACCEPT"
    }
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Confirm pending firewall rules

This example shows how to use firewall.v1.conf.confirmRules to confirm the pending firewall rules. It will move the pending firewall rules to the active list permanently.

JSON request:

POST /config/rest/firewall/v1/conf/confirmRules HTTP/1.1
HOST: my-device
Content-Type: application/json

{
    "data": {}
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

Clear pending firewall rules

This example shows how to use firewall.v1.conf.clearPendingRules to clear the pending firewall rules. It will cancel the active pending rules, restore the previous set of rules, and reset the fallback timer.

JSON request:

POST /config/rest/firewall/v1/conf/clearPendingRules HTTP/1.1
HOST: my-device
Content-Type: application/json

{
    "data": {}
}

JSON response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "success"
}

API definition

Structure

firewall.v1 (Root Entity)
    ├── activated (Property)
    ├── conf (Entity)
        ├── clearPendingRules (Action)
        ├── confirmRules (Action)
        ├── setRules (Action)
        ├── rules (Entity)
            ├── activeDefaultPolicy (Property)
            ├── activeRules (Property)
            ├── pendingDefaultPolicy (Property)
            ├── pendingRules (Property)
            ├── testTimeLeft (Property)

Entities

firewall.v1

Description: Firewall management
Type: Singleton
Operations:
- Get

firewall.v1.conf

Description: Firewall rules management
Type: Singleton
Operations:
- Get

firewall.v1.conf.rules

Description: Firewall rules: read-only properties that show the current state of the rules. You can leave it empty instead of specifying it as null.
Type: Singleton
Operations:
- Get

Properties

firewall.v1.activated

Description: Firewall service state
Data Type: boolean
Operations:
- Get
  - Permissions: admin
- Set
  - Permissions: admin

firewall.v1.conf.rules.activeDefaultPolicy

Description: Active default firewall policy. Default to ACCEPT.
Data Type: Policy
Operations:
- Get
  - Permissions: admin

firewall.v1.conf.rules.activeRules

Description: Active firewall rules
Data Type: RuleList
Operations:
- Get
  - Permissions: admin

firewall.v1.conf.rules.pendingDefaultPolicy

Description: Pending default firewall policy set by the setRules action
Data Type: Policy
Operations:
- Get
  - Permissions: admin

firewall.v1.conf.rules.pendingRules

Description: Pending firewall rules
Data Type: RuleList
Operations:
- Get
  - Permissions: admin

firewall.v1.conf.rules.testTimeLeft

Description: Measures the remaining test time for the pending firewall rules.
Data Type: PositiveNumValue
Operations:
- Get
  - Permissions: admin

Actions

firewall.v1.conf.clearPendingRules

Description: Clear the set of pending rules and abort any active test
Permissions: admin

firewall.v1.conf.confirmRules

Description: Confirm to apply the active firewall rules
Permissions: admin

firewall.v1.conf.setRules

Description: Set the active firewall rule list
Request Datatype: SetRulesReqData
Permissions: admin

Data types

RuleType

{
  "description": "Valid rule types",
  "enum": [
    "FILTER",
    "LIMIT"
  ],
  "type": "string"
}

PortType

{
  "description": "Port types",
  "enum": [
    "TCP",
    "UDP",
    "BOTH"
  ],
  "type": "string"
}

Port

{
  "description": "A valid port number",
  "maximum": 65535,
  "minimum": 1,
  "type": "integer"
}

PositiveNumValue

{
  "description": "Positive number",
  "minimum": 0,
  "type": "integer"
}

Policy

{
  "description": "Valid policies",
  "enum": [
    "DROP",
    "ACCEPT"
  ],
  "type": "string"
}

MAC

{
  "description": "MAC address type",
  "pattern": "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$",
  "type": "string"
}

NetworkPort

{
  "description": "Port address type",
  "fields": {
    "portType": {
      "description": "Port type",
      "type": "PortType"
    },
    "portNum": {
      "description": "Port number",
      "type": "Port"
    }
  },
  "type": "object"
}

IPRange

{
  "description": "IP range including lower and upper bounds",
  "fields": {
    "start": {
      "description": "IP range start address",
      "type": "string"
    },
    "end": {
      "description": "IP range end address",
      "type": "string"
    }
  },
  "type": "object"
}

PortRange

{
  "description": "Port range",
  "fields": {
    "portType": {
      "description": "Port type",
      "type": "PortType"
    },
    "start": {
      "description": "Port range start number",
      "type": "Port"
    },
    "end": {
      "description": "Port range end number",
      "type": "Port"
    }
  },
  "type": "object"
}

PktType

{
  "description": "Valid link-layer packet type",
  "enum": [
    "UNICAST",
    "BROADCAST",
    "MULTICAST"
  ],
  "type": "string"
}

Filter

{
  "description": "Firewall filter type",
  "fields": {
    "policy": {
      "description": "Filter policy",
      "type": "Policy"
    }
  },
  "type": "object"
}

LimitAmount

{
  "description": "Limit unit amount type",
  "minimum": 1,
  "maximum": 65535,
  "type": "integer"
}

LimitUnit

{
  "description": "Valid limit rule type",
  "enum": [
    "NEWCONNECTIONS"
  ],
  "type": "string"
}

LimitPeriod

{
  "description": "Rate limit period type",
  "enum": [
    "SECOND",
    "MINUTE",
    "HOUR",
    "DAY"
  ],
  "type": "string"
}

Limit

{
  "description": "Firewall limit type to define packet rate filtering",
  "fields": {
    "amount": {
      "description": "Max limit units allowed within the specified period",
      "type": "LimitAmount"
    },
    "period": {
      "description": "Limit rate period",
      "type": "LimitPeriod"
    },
    "unit": {
      "description": "Limit rate strategy indicating how to enforce the limit rate",
      "type": "LimitUnit"
    },
    "burst": {
      "description": "If the burst limit is reached, the firewall will filter all packets matching the rate limit strategy for the rate specified by amount and period",
      "type": "LimitAmount"
    }
  },
  "type": "object"
}

Rule

{
  "description": "Firewall rule entry type",
  "fields": {
    "ruleType": {
      "description": "Firewall rule entry type",
      "type": "RuleType"
    },
    "ip": {
      "description": "IPv4/IPv6 address or network",
      "nullable": true,
      "type": "string"
    },
    "ipRange": {
      "description": "IPv4/IPv6 address range",
      "nullable": true,
      "type": "IPRange"
    },
    "mac": {
      "description": "MAC address",
      "nullable": true,
      "type": "MAC"
    },
    "tcpPort": {
      "description": "The TCP port",
      "nullable": true,
      "type": "Port"
    },
    "udpPort": {
      "description": "The UDP port",
      "nullable": true,
      "type": "Port"
    },
    "port": {
      "description": "A generic port",
      "nullable": true,
      "type": "NetworkPort"
    },
    "portRange": {
      "type": "PortRange",
      "nullable": true,
      "description": "Port address range"
    },
    "pktType": {
      "description": "The link-layer packet type",
      "nullable": true,
      "type": "PktType"
    },
    "filter": {
      "description": "Filter rule",
      "nullable": true,
      "type": "Filter"
    },
    "limit": {
      "description": "Limit rule",
      "nullable": true,
      "type": "Limit"
    }
  },
  "type": "object"
}

RuleList

{
  "description": "Firewall rule list type",
  "items": {
    "type": "Rule"
  },
  "type": "array"
}

SetRulesReqData

{
  "description": "Firewall rules set request data type",
  "fields": {
    "defaultPolicy": {
      "description": "Default firewall policy",
      "type": "Policy"
    },
    "fallbackTime": {
      "description": "The maximum time in seconds to wait before reverting back to previous active rules",
      "type": "PositiveNumValue"
    },
    "rules": {
      "description": "Rules to set as active",
      "type": "RuleList"
    }
  },
  "type": "object"
}

Overview​

Use cases​

Manage firewall​

Activate firewall​

Check if the firewall is activated​

Manage firewall rules​

Custom errors​

Get active default firewall policy​

Get pending default firewall policy​

List all firewall rules​

Edit firewall rules​

Reorder firewall rules​

Remove firewall rules​

Confirm pending firewall rules​

Clear pending firewall rules​

API definition​

Structure​

Entities​

firewall.v1​

firewall.v1.conf​

firewall.v1.conf.rules​

Properties​

firewall.v1.activated​

firewall.v1.conf.rules.activeDefaultPolicy​

firewall.v1.conf.rules.activeRules​

firewall.v1.conf.rules.pendingDefaultPolicy​

firewall.v1.conf.rules.pendingRules​

firewall.v1.conf.rules.testTimeLeft​

Actions​

firewall.v1.conf.clearPendingRules​

firewall.v1.conf.confirmRules​

firewall.v1.conf.setRules​

Data types​

RuleType​

PortType​

Port​

PositiveNumValue​

Policy​

MAC​

NetworkPort​

IPRange​

PortRange​

PktType​

Filter​

LimitAmount​

LimitUnit​

LimitPeriod​

Limit​

Rule​

RuleList​

SetRulesReqData​

Overview

Use cases

Manage firewall

Activate firewall

Check if the firewall is activated

Manage firewall rules

Custom errors

Get active default firewall policy

Get pending default firewall policy

List all firewall rules

Edit firewall rules

Reorder firewall rules

Remove firewall rules

Confirm pending firewall rules

Clear pending firewall rules

API definition

Structure

Entities

firewall.v1

firewall.v1.conf

firewall.v1.conf.rules

Properties

firewall.v1.activated

firewall.v1.conf.rules.activeDefaultPolicy

firewall.v1.conf.rules.activeRules

firewall.v1.conf.rules.pendingDefaultPolicy

firewall.v1.conf.rules.pendingRules

firewall.v1.conf.rules.testTimeLeft

Actions

firewall.v1.conf.clearPendingRules

firewall.v1.conf.confirmRules

firewall.v1.conf.setRules

Data types

RuleType

PortType

Port

PositiveNumValue

Policy

MAC

NetworkPort

IPRange

PortRange

PktType

Filter

LimitAmount

LimitUnit

LimitPeriod

Limit

Rule

RuleList

SetRulesReqData