- »
- Development Manual »
- API Reference »
- Firewall
The firewall API plugin (os-firewall) offers a way for machine to machine interaction between custom applications and OPNsense, it caneasily be installed like any other plugin via System ‣ Firmware ‣ Plugins.
Although the plugin does contains a basic user interface (in Firewall ‣ Automation), it’s mirely intendedas a reference and testbed. There’s no relation to any of the rules being managed via the core system.
Tip
Use your browsers “inspect” feature to compare requests easily, the user interface in terms of communication is exactly the sameas offered by the API . Rules not visible in the web interface (Firewall ‣ Automation) will not be returned by the API either.
Method | Module | Controller | Command | Parameters |
|---|---|---|---|---|
| firewall | alias | addItem | |
| firewall | alias | delItem | $uuid |
| firewall | alias | export | |
| firewall | alias | get | |
| firewall | alias | getAliasUUID | $name |
| firewall | alias | getGeoIP | |
| firewall | alias | getItem | $uuid=null |
| firewall | alias | getTableSize | |
| firewall | alias | import | |
| firewall | alias | listCategories | |
| firewall | alias | listCountries | |
| firewall | alias | listNetworkAliases | |
| firewall | alias | listUserGroups | |
| firewall | alias | reconfigure | |
| firewall | alias | searchItem | |
| firewall | alias | set | |
| firewall | alias | setItem | $uuid |
| firewall | alias | toggleItem | $uuid,$enabled=null |
| model Alias.xml |
Method | Module | Controller | Command | Parameters |
|---|---|---|---|---|
| firewall | alias_util | add | $alias |
| firewall | alias_util | aliases | |
| firewall | alias_util | delete | $alias |
| firewall | alias_util | findReferences | |
| firewall | alias_util | flush | $alias |
| firewall | alias_util | list | $alias |
| firewall | alias_util | updateBogons |
Method | Module | Controller | Command | Parameters |
|---|---|---|---|---|
| firewall | category | addItem | |
| firewall | category | delItem | $uuid |
| firewall | category | get | |
| firewall | category | getItem | $uuid=null |
| firewall | category | searchItem | $add_empty=’0’ |
| firewall | category | set | |
| firewall | category | setItem | $uuid |
| model Category.xml |
Method | Module | Controller | Command | Parameters |
|---|---|---|---|---|
| firewall | filter_base | apply | $rollback_revision=null |
| firewall | filter_base | cancelRollback | $rollback_revision |
| firewall | filter_base | get | |
| firewall | filter_base | listCategories | |
| firewall | filter_base | listNetworkSelectOptions | |
| firewall | filter_base | revert | $revision |
| firewall | filter_base | savepoint | |
| firewall | filter_base | set | |
| model Filter.xml |
Method | Module | Controller | Command | Parameters |
|---|---|---|---|---|
| firewall | filter | addRule | |
| firewall | filter | delRule | $uuid |
| firewall | filter | getRule | $uuid=null |
| firewall | filter | searchRule | |
| firewall | filter | setRule | $uuid |
| firewall | filter | toggleRule | $uuid,$enabled=null |
Method | Module | Controller | Command | Parameters |
|---|---|---|---|---|
| firewall | filter_util | ruleStats |
Method | Module | Controller | Command | Parameters |
|---|---|---|---|---|
| firewall | group | addItem | |
| firewall | group | delItem | $uuid |
| firewall | group | get | |
| firewall | group | getItem | $uuid=null |
| firewall | group | reconfigure | |
| firewall | group | searchItem | |
| firewall | group | set | |
| firewall | group | setItem | $uuid |
| model Group.xml |
Method | Module | Controller | Command | Parameters |
|---|---|---|---|---|
| firewall | npt | addRule | |
| firewall | npt | delRule | $uuid |
| firewall | npt | getRule | $uuid=null |
| firewall | npt | searchRule | |
| firewall | npt | setRule | $uuid |
| firewall | npt | toggleRule | $uuid,$enabled=null |
Method | Module | Controller | Command | Parameters |
|---|---|---|---|---|
| firewall | one_to_one | addRule | |
| firewall | one_to_one | delRule | $uuid |
| firewall | one_to_one | getRule | $uuid=null |
| firewall | one_to_one | searchRule | |
| firewall | one_to_one | setRule | $uuid |
| firewall | one_to_one | toggleRule | $uuid,$enabled=null |
Method | Module | Controller | Command | Parameters |
|---|---|---|---|---|
| firewall | source_nat | addRule | |
| firewall | source_nat | delRule | $uuid |
| firewall | source_nat | getRule | $uuid=null |
| firewall | source_nat | searchRule | |
| firewall | source_nat | setRule | $uuid |
| firewall | source_nat | toggleRule | $uuid,$enabled=null |
Concept¶
The firewall plugin injects rules in the standard OPNsense firewall while maintaining visibility on them in thestandard user interface.
We use our standard ApiMutableModelControllerBase to allow crud operations on rule entries and offer a set ofspecific actions to apply the new configuration.Since firewall rules can be quite sensitive with a higher risk of lockout, we also support a rollback mechanism here,which offers the ability to rollback this components changes.
The diagram above contains the basic steps to change rules, apply and eventually rollback if not being able to access the machine again.When calling savepoint() a new config revision will be created and the timestamp will be returned for later use.If the cancelRollback(savepoint) is not called within 60 seconds, the firewall will rollback to the previous stateidentified by the savepoint timestamp (if available).
Note
The examples in this document disable certificate validation, make sure when using this in a production environment toremove the verify=False from the requests calls
Tip
The number of versions kept can be configured as “backup count” in System -> Configuration -> History.This affectively determines within how many configuration changes you can still rollback, if the backup is removed, a rollbackwill keep the current state (do nothing).
Administration example¶
Administrative endpoints are pretty standard use of ApiMutableModelControllerBase, the example below searches fora rule named “OPNsense_fw_api_testrule_1”, when not found one will be added otherwise it will print the internal uuid.Inline you will find a brief description of the steps performed.
administrative_example.py¶
1#!/usr/bin/env python3.7 2import requests 3import json 4 5# key + secret from downloaded apikey.txt 6api_key="3RhWOno+HwvtmT406I6zw8of8J6n9FOKlWK6U0B+K7stt/fDaJg7bjeF3QAshlScYqC+3o5THy3vQViW" 7api_secret="uaBk27NKhQCZSDpfAlG6YJ473MzvsCNiED6kzbYuykzU05fCRkcJADhDm5nxbZt8yREC74ZpvD/vbcEx" 8 9# define the basics, hostname to use and description used to identify our test rule10rule_description='OPNsense_fw_api_testrule_1'11remote_uri="https://192.168.1.1"1213# search for rule14r = requests.get(15 "%s/api/firewall/filter/searchRule?current=1&rowCount=7&searchPhrase=%s" % (16 remote_uri, rule_description17 ),18 auth=(api_key, api_secret), verify=False19)2021if r.status_code == 200:22 response = json.loads(r.text)23 if len(response['rows']) == 0:24 # create a new rule, identified by rule_description allowing traffic from25 # 192.168.0.0/24 to 10.0.0.0/24 using TCP protocol26 data = {"rule" :27 {28 "description": rule_description,29 "source_net": "192.168.0.0/24",30 "protocol": "TCP",31 "destination_net": "10.0.0.0/24"32 }33 }34 r = requests.post(35 "%s/api/firewall/filter/addRule" % remote_uri, auth=(api_key, api_secret), verify=False, json=data36 )37 if r.status_code == 200:38 print("created : %s" % json.loads(r.text)['uuid'])39 else:40 print("error : %s" % r.text)4142 else:43 for row in response['rows']:44 print ("found uuid %s" % row['uuid'])
Tip
Since our model contains default values for most attributes, we only need to feed the changes if we would like to keep thedefaults. In this case the TCP/IP version was IPv4 by default for example. In most cases one would like to set all relevant propertiesin case defaults change over time.
Apply / revert example¶
This example will disable the rule created in the previous example and apply the changes using a savepoint, since we’re notcalling cancelRollback(savepoint) it will revert after 60 seconds to the original state.
savepoint_example.py¶
1#!/usr/bin/env python3.7 2import requests 3import json 4 5# key + secret from downloaded apikey.txt 6api_key="3RhWOno+HwvtmT406I6zw8of8J6n9FOKlWK6U0B+K7stt/fDaJg7bjeF3QAshlScYqC+3o5THy3vQViW" 7api_secret="uaBk27NKhQCZSDpfAlG6YJ473MzvsCNiED6kzbYuykzU05fCRkcJADhDm5nxbZt8yREC74ZpvD/vbcEx" 8 9# define the basics, hostname to use and description used to identify our test rule10rule_description='OPNsense_fw_api_testrule_1'11remote_uri="https://192.168.1.1"1213# search for rule14r = requests.get(15 "%s/api/firewall/filter/searchRule?current=1&rowCount=7&searchPhrase=%s" % (16 remote_uri, rule_description17 ),18 auth=(api_key, api_secret), verify=False19)2021if r.status_code == 200:22 response = json.loads(r.text)23 if len(response['rows']) > 0:24 rule_uuid = response['rows'][0]['uuid']25 r = requests.post("%s/api/firewall/filter/savepoint" % remote_uri, auth=(api_key, api_secret), verify=False)26 if r.status_code == 200:27 sp_response = json.loads(r.text)28 # disable rule29 r = requests.post("%s/api/firewall/filter/toggleRule/%s/0" % (remote_uri, rule_uuid),30 auth=(api_key, api_secret), verify=False31 )32 # apply changes, revert to sp_response['revision'] after 60 seconds33 r = requests.post("%s/api/firewall/filter/apply/%s" % (remote_uri, sp_response['revision']),34 auth=(api_key, api_secret), verify=False35 )36 print("revert to revision %s in 60 seconds (%s changed)" % (sp_response['revision'], rule_uuid))37 else:38 print("rule %s not found" % rule_description)
Note
The savepoint will only revert this components changes, other changes won’t be affected by this revert, for exampleadd an additional interface between savepoint and revert won’t be affected.
