Firewall
This page describes how COD connects firewalls, which rights and settings are needed and where the limits are.
What the module does is described on the module page.
As of: November 2026, COD 3.8.6
Documentation contents
- Overview
- Getting started
- Requirements
- Names and addresses
- Network devices
- Time and DNS
- Installation
- Deployment shapes
- Initial setup
- Updates
- Modules
- Network and MikroTik
- Automation
- NAC
- TACACS+
- Firewall
- Captive Portal
- Monitoring
- Backup
- Hypervisor
- OTP
- Passkeepr
- GRC
- Inventory and CMDB import
- Troubleshooting
- Security
- Versions
- Version history
- Support
Documentation
- Overview
- Getting started
- Requirements
- Names and addresses
- Network devices
- Time and DNS
- Installation
- Deployment shapes
- Initial setup
- Updates
- Modules
- Network and MikroTik
- Automation
- NAC
- TACACS+
- Firewall
- Captive Portal
- Monitoring
- Backup
- Hypervisor
- OTP
- Passkeepr
- GRC
- Inventory and CMDB import
- Troubleshooting
- Security
- Versions
- Version history
- Support
Overview
| Item | Value |
|---|---|
| Purpose | Firmware level and updates, live state, reachability, VPN overview (WireGuard, IPsec, OpenVPN), aliases and zones, certificates, rules (experimental), self-registration |
| Vendors | AIMdefense, OPNsense, pfSense, DynFi |
| Connections and direction | COD server to firewall: HTTPS API and SSH. ICMP and TCP for reachability. For self-registration, once from firewall to COD |
| Credentials | API key and API secret, SSH user and password, SSH port, optionally the firewall’s CA certificate |
| Asset | built-in asset type “Firewall” |
| Firewall rules | Customers and partners receive the list of connections and firewall rules as part of the project. |
Functions per vendor
| Function | AIMdefense | OPNsense | pfSense | DynFi |
|---|---|---|---|---|
| Status, firmware, aliases, VPN overview | yes | yes | clarify in the project | clarify in the project |
| Certificate table, object migration, alias import | yes | yes | no | no |
| Self-registration with the plugin | no | yes | no | no |
| Captive portal | no | yes | no | no |
Requirements
On the firewall
| Requirement | Why |
|---|---|
| API access with API key and API secret | Status, firmware, aliases, VPN, certificates |
| API user with administrator rights (recommended) | With restricted rights, the user needs at least the OPNsense privileges “Interfaces: Virtual IPs: Status” and “System: High Availability” to show clusters in the layer 3 map. You receive the minimum rights as part of the project. |
| SSH with a dedicated user for COD | Rules, configuration, terminal |
| API and SSH access restricted to the source address of the COD server | All queries come from the COD server |
| Reachable via ICMP and TCP from the COD server | Reachability check |
In COD
- Firewall module enabled for the tenant.
- Built-in asset type “Firewall” in the asset catalogue. Do not change its name.
- Asset activated, vendor set.
- Mail setting of the location, so that outage messages arrive.
- If the firewall uses a certificate from its own CA: the CA certificate stored in COD.
Setup
Adding a firewall by hand
- On the firewall, create the API user and the SSH user for COD.
- In COD, create the asset with the type “Firewall” and the vendor. Activate it.
- Enter address, API key, API secret, SSH user, password and SSH port. If the firewall uses its own CA, store the CA certificate.
- Check status and firmware level in the module overview.
Self-registration with the OPNsense plugin
An OPNsense firewall can register itself with COD through the COD plugin. Agree with your partner on how to obtain the plugin.
- Enter the COD address in the plugin.
- Log in in the plugin with a COD user, its password and the one-time code.
- Choose the location.
- Choose the local OPNsense user for whom the plugin creates an API key.
- The plugin sends management address, port and key to COD once.
- The firewall appears in COD under “Firewall > Pending”. Accept the entry.
Note: “Reject” under “Firewall > Pending” deletes the asset. Reject only if the asset should be removed.
Reachability check
- Set the check schedule per location (cron, default every minute).
- Enter the recipients of outage messages.
- Check that the location’s mail setting works.
The check uses ICMP and a TCP connection to the firewall’s API port. Throttling per firewall prevents repeated mails about the same problem.
Technical details
| Item | Value |
|---|---|
| Connection | HTTPS API of the firewall. SSH for rules, configuration and terminal |
| Reachability | ICMP and TCP from the COD server, schedule per location, mail with throttling per firewall |
| VPN | WireGuard, OpenVPN and IPsec across all locations in tables and a topology view |
| Aliases and zones | central maintenance of aliases (IPs, networks, ports). Zones distribute new aliases to all firewalls in the zone. A reference check prevents deleting objects still in use |
| Layer 3 map | Firewalls appear as nodes, CARP pairs as a box |
| Terminal | SSH session in the browser, opened by the COD server |
| Asset | The “References” tab shows the firewall entry, Zabbix host, voucher configuration and tasks |
How quickly COD reports an outage
That depends on the schedule you set per location. COD actively reports the reachability of the firewall by mail. You see the state of VPN tunnels in the tables and the topology view. Alerts from your monitoring come from Zabbix. See Monitoring.
Configuration backup
The Firewall module does not back up configurations. The Backup module does that. If you pick a firewall from the inventory there, COD fills in the address and credentials once.
Known limits
| Limit | What you can do |
|---|---|
| The rule editor is experimental. It works over SSH, and a mistake when applying can take a firewall offline | Maintain rules in the firewall’s own interface. Use aliases and zones in COD |
| The update buttons do not ask for confirmation | Click them only in a maintenance window and after a current backup |
| “Reject” under “Firewall > Pending” deletes the asset | Reject only if the asset should be removed |
| There is no outage message for VPN tunnels | Monitor tunnels in Zabbix |
| The built-in asset type “Firewall” must not be renamed | Keep the name in the asset catalogue |
| Self-registration and captive portal only for OPNsense | Add other firewalls by hand |
| Certificate table, object migration and alias import only for AIMdefense and OPNsense | Maintain these items for pfSense and DynFi in the firewall itself |
| Scope of functions for pfSense and DynFi | The scope for your firewalls is clarified in the project. |
| Minimum rights of the API user | You receive the minimum rights as part of the project. |
Further reading
- Firewall module page
- Captive Portal
- What your network needs for Firewall and Captive Portal
- Network and MikroTik: layer 3 map
- Troubleshooting
- Questions about the modules
- Support: your partner is your first point of contact. Technical questions to extocode go through the helpdesk form.