OPNsense
Knocknoc integrates with OPNsense by managing the contents of a pre-existing firewall alias via the OPNsense REST API. When a user authenticates the agent adds their IP to the alias; when the grant expires or the user logs out, the IP is removed.
The agent never creates the alias or modifies firewall rules. You create the alias and reference it from a rule yourself, and Knocknoc just maintains its contents.
Authentication
The Knocknoc agent authenticates to the OPNsense API using HTTP Basic Authentication with an API key/secret pair generated from an OPNsense user's profile.
The API key acts as the username and the API secret as the password. Knocknoc encrypts the API secret at rest. You only need to enter it when first configuring the Knoc or when explicitly rotating it.
Create an API Key/Secret
- In the OPNsense web UI, go to System > Access > Users
- Either create a dedicated user (recommended) or open an existing user's profile
- Scroll to the API keys section
- Click the + button to generate a new key/secret pair
- OPNsense downloads a file named
OPNsense.<username>_apikey.txt. It contains two lines,key=...andsecret=.... Save the file. You'll upload it directly to the Knocknoc wizard in Step 6.
The downloaded secret is shown only once. If you lose it, generate a new pair.
Permissions
The API user needs permission to read and modify aliases and to apply firewall changes.
In System > Access > Groups, create or edit a group assigned to the API user. Add at least these privileges:
- Firewall: Alias: Edit
- Firewall: Aliases
- the privilege that permits applying alias changes (the "Firewall: Alias: Apply" or equivalent entry, depending on OPNsense version). Without it, every grant and revoke will fail with an authorisation error after the alias is mutated.
OPNsense's privilege names differ slightly between versions. Pick the entries that correspond to alias management and applying firewall configuration. The user does not need full administrator rights.
Setup
Step 1: Create the Firewall Alias
Knocknoc manages the contents of an alias you create up front. The alias is not created by the agent.
- In the OPNsense web UI, go to Firewall > Aliases
- Click the + button to add a new alias
- Configure the alias:
- Name: a short identifier matching
[A-Za-z0-9_]+(e.g.,knocknoc_allowed). Note this name; you will enter it in the Knocknoc wizard. Hyphens and dots are not allowed. - Type: Host(s) (or Network(s) if you intend to grant CIDR ranges). The agent supports both individual addresses and CIDR prefixes.
- Content: leave empty. Knocknoc will populate it.
- Description: something descriptive (e.g., "Knocknoc-managed allowlist")
- Name: a short identifier matching
- Click Save, then Apply at the top of the aliases page
Step 2: Reference the Alias in a Firewall Rule
The alias by itself does nothing. It needs to be referenced from a firewall rule.
- Go to Firewall > Rules > (interface)
- Edit or create the rule that should be gated by Knocknoc
- For the rule's Source (or destination, depending on your design), select the alias you created in Step 1
- Click Save and Apply Changes
Until Knocknoc grants a user, the alias is empty and the rule effectively matches no one.
Step 3: Create the API User and Key
Follow Create an API Key/Secret above. Make sure the user is in a group with the privileges listed under Permissions.
Step 4: Deploy the Knocknoc Agent
Deploy the Knocknoc orchestration agent on a host that has network access to the OPNsense firewall's web UI (port 443 by default). The agent does not need to run on the firewall itself.
Step 5: Create the Knoc
- In the Knocknoc admin UI, create a new Appliance Knoc
- Select Active mode
- Choose OPNsense as the Vendor
Step 6: Configure the Backend
Use API key file to upload the OPNsense.<username>_apikey.txt from Step 3. The wizard reads the file and fills in API Key and API Secret for you. To enter them by hand instead, skip the upload and type the values into the fields below.
| Field | Description |
|---|---|
| Hostname | The full URL of the OPNsense web UI, including the scheme. Example: https://firewall.example.com. A path component is not allowed. |
| API key file | The OPNsense.<username>_apikey.txt saved in Step 3. Uploading it auto-fills API Key and API Secret. |
| API Key | The key= value from the API credentials file. Auto-filled when you use API key file. |
| API Secret | The secret= value from the API credentials file. Auto-filled when you use API key file. Encrypted at rest by Knocknoc. |
| Insecure | Enable only if your OPNsense uses a self-signed TLS certificate that the agent host does not trust. This disables TLS verification and exposes the connection to MITM. Prefer installing a trusted certificate. |
Step 7: Configure the ACL
| Field | Description |
|---|---|
| Alias Name | The name of the alias from Step 1 (e.g., knocknoc_allowed). Must match exactly. Letters, numbers, and underscores only. |
Step 8: Assign Users and Test
- Assign users and/or groups to the Knoc
- Log in as a test user via the Knocknoc user portal
- In OPNsense, go to Firewall > Diagnostics > Aliases and select your alias from the dropdown
- The user's IP should appear in the contents listing
- Verify network traffic from the user's IP is permitted by the firewall rule
- On logout or grant expiry the IP should disappear from the alias and traffic should be blocked again
Troubleshooting
Agent Logs
Start by checking the orchestration agent logs. Errors are reported with structured codes in the form (agent error #207NNN) description. See Error Codes below.
Common problems:
- Authentication failed (
#207000): the API key/secret pair is wrong. Regenerate the key in System > Access > Users and update the Knoc. - Authorization failed (
#207001): the API user is authenticated but lacks privileges. Check the group membership and the Firewall: Alias: Edit / Firewall: Aliases privileges. - Alias not found (
#207100): the alias name in the Knoc doesn't match an alias in OPNsense, or the user lacks privilege to see it. Check the Alias name field; it is case-sensitive. - TLS error (
#207003): the agent does not trust the OPNsense certificate. Install a trusted certificate on OPNsense, or (for lab use only) enable Insecure in the backend configuration. - Connection refused (
#207004): the agent host cannot reach OPNsense on the configured port. Check firewall rules and the Hostname scheme/port.
IPs Appear in the Alias But Traffic Is Still Blocked
If alias contents update but firewall rules don't behave as expected:
- Confirm the firewall rule actually references the alias (Step 2). It's easy to create the alias and forget to wire it into a rule.
- Confirm the rule's action is Pass (or whatever you intended) and that no higher-priority rule is overriding it.
- Confirm the alias Type matches what you're granting (Host(s) for IPs, Network(s) for CIDRs).
Rotating Credentials
To rotate the API key/secret without dropping access:
- In OPNsense, generate a new key/secret pair for the API user
- In Knocknoc, edit the Knoc and upload the new
apikey.txt, or paste the key and secret by hand. The hostname can stay the same. - Save. The agent will pick up the new credentials on the next grant operation.
- In OPNsense, remove the old key/secret entry once you've confirmed the new one works.
If you change the Hostname, Knocknoc requires you to re-enter the API secret as a safety check. This prevents an admin from inadvertently re-pointing a Knoc at a different firewall using the old credentials.
Error Codes
The Knocknoc agent reports structured error codes when OPNsense operations fail. These appear in agent logs and are forwarded to the Knocknoc server.
Error codes show up as (agent error #207NNN) description in log output.
Connection and Authentication (207000-207099)
| Code | Description | Common Causes |
|---|---|---|
| 207000 | OPNsense rejected the API key/secret | API user or password incorrect; HTTP 401 |
| 207001 | OPNsense API user lacks the required privileges | User missing alias management privileges; HTTP 403 |
| 207002 | OPNsense did not respond in time | Network or firewall slow to respond; request timed out |
| 207003 | TLS/SSL certificate error connecting to OPNsense | Self-signed/expired cert; install trusted cert or enable Insecure |
| 207004 | Connection refused by OPNsense | Wrong port, firewall blocking, or service not running |
| 207005 | Failed to resolve OPNsense hostname | DNS failure for the configured hostname |
| 207006 | OPNsense request failed | Generic transport error; check underlying message |
Alias Lookup and Management (207100-207199)
| Code | Description | Common Causes |
|---|---|---|
| 207100 | OPNsense alias not found | Alias name in the Knoc doesn't match an alias in OPNsense |
| 207101 | Failed to read OPNsense alias contents | Unexpected response from the firewall |
| 207102 | Failed to add entry to OPNsense alias | OPNsense returned a failure status |
| 207103 | Failed to remove entry from OPNsense alias | OPNsense returned a failure status |
Apply (207200-207299)
| Code | Description | Common Causes |
|---|---|---|
| 207200 | Failed to apply OPNsense alias changes | Apply step failed; previous add/delete may not be persisted |
OPNsense Documentation References
- Aliases: creating and managing aliases