Skip to main content

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

  1. In the OPNsense web UI, go to System > Access > Users
  2. Either create a dedicated user (recommended) or open an existing user's profile
  3. Scroll to the API keys section
  4. Click the + button to generate a new key/secret pair
  5. OPNsense downloads a file named OPNsense.<username>_apikey.txt. It contains two lines, key=... and secret=.... 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.

  1. In the OPNsense web UI, go to Firewall > Aliases
  2. Click the + button to add a new alias
  3. 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")
  4. 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.

  1. Go to Firewall > Rules > (interface)
  2. Edit or create the rule that should be gated by Knocknoc
  3. For the rule's Source (or destination, depending on your design), select the alias you created in Step 1
  4. 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

  1. In the Knocknoc admin UI, create a new Application Knoc
  2. Select Active mode
  3. 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

  1. Assign users and/or groups to the Knoc
  2. Log in as a test user via the Knocknoc user portal
  3. In OPNsense, go to Firewall > Diagnostics > Aliases and select your alias from the dropdown
  4. The user's IP should appear in the contents listing
  5. Verify network traffic from the user's IP is permitted by the firewall rule
  6. 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:

  1. In OPNsense, generate a new key/secret pair for the API user
  2. 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.
  3. Save. The agent will pick up the new credentials on the next grant operation.
  4. 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

Back to top