Skip to main content

pfSense

Knocknoc integrates with pfSense to dynamically control network access. 

The Knocknoc agent maintains a host alias on pfSense via the pfRest API. As users authenticate and grants expire, the alias's address list is updated and pending firewall changes are applied.

If you would prefer a poll-based integration (e.g., pfBlockerNG pulling a Knocknoc-hosted feed on its own schedule), use the EDL (Passive) Knoc type instead. It has no agent-side configuration.

Authentication

The Knocknoc agent authenticates to pfRest with an API key. pfRest also supports basic auth and JWTs; Knocknoc uses the API key option because it's the simplest to rotate and does not require storing the pfSense user's password.

Setup

Knocknoc maintains a single host alias on pfSense and rewrites its address list as users come and go. Existing firewall rules reference the alias by name.

Step 1: Install the pfRest Package

pfRest is a third-party package, so it isn't in pfSense's built-in Package Manager. Searching Available Packages won't find it. You install it from the pfRest GitHub release, following the pfRest install guide.

  1. On the pfRest releases page, find the .pkg build for your pfSense version (e.g. pfSense-2.8.1-pkg-RESTAPI.pkg). The build must match your pfSense version. If your version isn't in the newest release, use the most recent release that still includes it (pfSense CE 2.7.2, for instance, is covered up to pfRest v2.4.3).
  2. Open a shell on pfSense via Diagnostics > Command Prompt (or SSH, or the console Shell option) and install it: 
    pkg-static -C /dev/null add https://github.com/pfrest/pfSense-pkg-RESTAPI/releases/download/<release>/pfSense-<your-version>-pkg-RESTAPI.pkg
  3. Once installed, navigate to System > API to confirm it is running. If the API menu item is there, you have it installed.
  4. Enable Key authentication. Go to System > REST API > Settings, and under Authentication Methods make sure Key is selected (it sits alongside Local database and JWT, and the field is multi-select). Knocknoc authenticates with an API key, and pfRest only honors the key when Key is an enabled method. If it is not, every call fails with HTTP 401. Save.

Step 2: Create the Service Account and API Key

Create your service account:

  1. In pfSense, go to System > User Manager > Users
  2. Click Add to create a service account (e.g., knocknoc-agent)
  3. Set a strong password
  4. Under Effective Privileges, assign the pfRest API privileges below:
    • REST API - /api/v2/system/version GET
    • REST API - /api/v2/firewall/alias GET
    • REST API - /api/v2/firewall/aliases GET
    • REST API - /api/v2/firewall/alias PATCH
    • REST API - /api/v2/firewall/apply POST
    • REST API - /api/v2/firewall/alias POST (only needed if you want Knocknoc to create the alias on first grant)
  5. Save the user
  6. Generate an API key for this user under System > REST API > Keys

Create the API key. pfRest issues each key to whoever is logged in when it's created (there is no field to pick a different user), so you must create it while logged in as the service account, not as admin:

  1. The service account needs to reach the key page, so on top of the API privileges above, temporarily give it WebCfg - System: Login / Logout / Dashboard, WebCfg - System: RESTAPI Keys, and WebCfg - System: RESTAPI Key. You can remove these again once the key exists.
  2. Log out, then log back in as the service account (e.g. knocknoc-agent).
  3. Go to System > REST API > Keys and click Add. The defaults (SHA256, 16 bytes) are fine. Set a Description, then Save.
  4. Copy the generated key value. pfRest only displays it once, and it is issued to the account you are logged in as.

If you would rather not grant the service account GUI access, create the key while logged in as admin instead. The key then acts as admin (full privileges) rather than the least-privilege service account.

You will paste this value into the pfRest API Key field in the Knocknoc wizard.

Step 3: Create the Firewall Alias and Rule

The agent will write to a single host alias. You can pre-create it, or let Knocknoc create it on the first grant.

  1. In pfSense, go to Firewall > Aliases > IP
  2. Click Add
  3. Configure the alias:
    • Name: a name without spaces (e.g., knocknoc_users). Note this; you will enter it in the Knocknoc wizard.
    • Type: Host(s)
    • Description: e.g., Knocknoc-managed authenticated users
  4. Leave the address list empty for now. Knocknoc will populate it when users authenticate.
  5. Click Save, then Apply Changes

Now create or modify a firewall rule that references this alias:

  1. Go to Firewall > Rules
  2. Click Add
  3. Configure the rule:
    • Action: Pass
    • Source: Address or alias, then enter the alias name from above (e.g., knocknoc_users)
    • Destination, Protocol, Ports: whatever fits your policy
  4. Click Save, then Apply Changes

Step 4: Deploy the Knocknoc Agent

Deploy the Knocknoc orchestration agent with network access to the pfSense web GUI on the pfRest port (default: same as the management UI).

Step 5: Create Knoc in Knocknoc

  1. Select the Firewall / Appliances Knoc type
  2. Select Active
  3. Choose pfSense as the Vendor

Step 6: Configure Backend

Field Description
pfSense URL Base URL of the pfSense web GUI (e.g., https://pfsense.example.com). Must include the scheme; trailing slash is fine.
pfRest API Key The API key generated in Step 2. Knocknoc encrypts this at rest.
Insecure Tick this to skip TLS certificate verification. Only safe for self-signed certificates on a trusted network.

Step 7: Configure ACL

Field Description
Alias name The host alias name from Step 3 (e.g., knocknoc_users). Must match exactly. Knocknoc will create the alias if it does not yet exist.

Step 8: Assign Users and Test

  1. Assign users and/or groups to the Knoc
  2. Log in as a test user
  3. In pfSense, go to Firewall > Aliases > IP and click on the alias
  4. Verify the user's IP appears in the address list
  5. Verify network access through the firewall rule works
  6. On logout or grant expiry, the IP should be removed from the alias

Troubleshooting

Agent Logs

Start by checking the orchestration agent logs. Common problems:

  • Authentication failed: the API key is invalid, has been revoked, or was generated for a different user. Regenerate the key and update the Knocknoc backend configuration.
  • Permission denied: the API user lacks one of the privileges listed in Step 2 (Create the Service Account and API Key). Check the user's effective privileges in System > User Manager.
  • API endpoint not installed: the pfRest package is not installed, or it is installed but disabled. Confirm the package is present in System > Package Manager > Installed Packages
  • TLS certificate error: pfSense is using a self-signed or internal-CA certificate. Either install a trusted certificate on pfSense or tick Insecure in the Knocknoc backend configuration.

Alias Updates Not Visible

If the alias's address list never changes:

  1. Confirm the Alias name in the Knocknoc ACL exactly matches the alias on pfSense. Names are case-sensitive.
  2. Verify the API user has Firewall: Aliases: Edit privilege.
  3. Check the agent logs for apply errors. If apply fails after an alias edit, pfSense holds the changes as pending and they don't take effect.

Error Codes

The Knocknoc agent reports structured error codes when pfSense operations fail. These appear in agent logs and are forwarded to the Knocknoc server.

Error codes show up as (agent error #NNNNN) description in log output.

Connection and Authentication (PFS000-PFS049)

Code Description Common Causes
PFS000 Failed to connect to pfSense Hostname unreachable, DNS failure, or connection refused. Check that pfSense is online and the URL is correct.
PFS001 pfSense authentication failed Invalid or revoked API key (HTTP 401)
PFS002 pfSense authorization failed API user lacks the required privileges (HTTP 403). See Step 2 (Create the Service Account and API Key).
PFS003 pfSense TLS/SSL certificate error Self-signed or untrusted certificate. Install a valid certificate or tick Insecure in the backend configuration.
PFS004 pfSense connection timed out Network timeout. Check connectivity between the agent and pfSense.
PFS005 pfSense REST API package not installed The pfRest package is missing or disabled. See Step 1: Install the pfRest Package.

Alias Operations (PFS100-PFS149)

Code Description Common Causes
PFS100 Failed to get pfSense alias Request for the alias failed. Check the underlying error in the agent logs.
PFS101 Failed to create pfSense alias Creation of the alias failed. The API user may lack the Firewall: Aliases: Import privilege.
PFS102 Failed to update pfSense alias Update of the alias failed. The API user may lack the Firewall: Aliases: Edit privilege.
PFS103 pfSense alias not found The alias name configured in the ACL does not exist on pfSense. Names are case-sensitive.

Apply Operations (PFS200-PFS249)

Code Description Common Causes
PFS200 Failed to apply pending pfSense firewall changes Pending alias edits could not be applied and will not take effect.

Response Parsing (PFS400-PFS449)

Code Description Common Causes
PFS400 Invalid or unexpected response from pfSense The pfRest response could not be parsed. Often indicates a pfRest version mismatch or a proxy in the way.

pfSense Documentation References

Back to top