Configuration

This guide covers how to configure the NetDefense plugin through the OPNsense web interface.

Accessing NetDefense Settings

1. Log in to your OPNsense web interface

2. Navigate to Services > NetDefense > Settings

Basic Configuration

The settings page is organized into two steps followed by an advanced section.

Step 1: API Configuration

Setting	Description
API Credentials	OPNsense API key and secret used by NDAgent to manage the system. A dedicated netdefense-agent user with full administrative rights is automatically created on first use. The status indicator shows whether credentials are configured and ready. Use the Rotate Credentials button to generate a new key/secret pair.

Step 2: Service Configuration

Setting	Description
Enable NetDefense Agent	Activates the NetDefense Agent service to connect to the central server.
Registration Token	UUID token provided by your NetDefense organization for device registration.

Advanced Settings

Click the Advanced Settings toggle to reveal additional configuration options, grouped by what they affect.

Control Plane — how this device reaches NetDefense:

Setting	Default	Description
Device ID	Auto-generated	Unique UUID identifier for this device. Auto-generated on first load if empty.
Server Address	https://hub.netdefense.io	NetDefense server URL. Only change if using a self-hosted deployment. See Service Endpoints for how this relates to the host ndcli uses.
SSL Verification	Enabled	Verifies SSL certificates when connecting to the NetDefense server.
TOFU Key Fetch SSL Verification	Enabled	Verifies the certificate on the one-time trust-key fetch, independently of the setting above.
Extra CA File	Empty	CA certificates of a TLS-inspection proxy, trusted for the connection to NetDefense besides the agent’s built-in roots.

Remote Access — whether and how anyone can reach a session on this device:

Setting	Default	Description
Pathfinder Address	https://pathfinder.netdefense.io	PathFinder server URL used for remote sessions. Only change if using a self-hosted deployment.
Pathfinder SSL Verification	Enabled	Verifies SSL certificates when connecting to PathFinder.
Pathfinder Shell	OPNsense Shell	The shell launched when a remote session is opened via ndcli device connect. Any shell installed on the device (e.g., bash, sh, csh, tcsh) appears as an option.
Remote Access Policy	Full access	The device’s own ceiling on remote sessions. Cannot be raised remotely.

Configuration Sync — what this device will accept in a pushed configuration:

Setting	Default	Description
Allow All Snippet Content	Disabled	When left off, the device refuses privileged snippet content instead of applying it.

Maintenance:

Setting	Default	Description
Log Level	INFO	Controls the verbosity of agent logs (DEBUG, INFO, WARNING, ERROR).
Re-bind Token	Empty	One-time token used to re-bind this device’s signing key.

Tip

The Device ID is automatically generated when the settings page loads for the first time. Use the Reset ID button to generate a new UUID if needed (e.g., when cloning a device).

Enabling NetDefense

1. Navigate to Services > NetDefense > Settings

2. Check the Enable NetDefense Agent checkbox

3. Enter your Registration Token

   Your registration token is available from your NetDefense organization settings. It should be in UUID format (e.g., 12345678-1234-1234-1234-123456789abc).

4. Click Apply

The agent will start and attempt to register with the NetDefense server. Check the Log File to monitor the registration process.

Disabling NetDefense

1. Navigate to Services > NetDefense > Settings

2. Uncheck the Enable NetDefense Agent checkbox

3. Click Apply

This will stop the NetDefense Agent service. The device will go offline in your NetDefense dashboard but will retain its configuration for when you re-enable it.

Configuration Reference

API Credentials

Auto-generated

NDAgent requires OPNsense API credentials to apply configuration changes to the firewall. The plugin automatically creates a dedicated netdefense-agent OPNsense user with full administrative rights and generates an API key/secret pair for it.

The account needs full administrative rights because the agent manages users, groups and firmware, as well as the rest of the configuration NetDefense manages on the firewall. OPNsense lets an account that can manage users give any account administrative rights, so a narrower grant wouldn’t make it any less powerful.

You can rotate the credentials at any time using the Rotate Credentials button — for example, to comply with a key rotation policy, after a suspected compromise, or following personnel turnover. The agent picks up the new credentials automatically with no restart or downtime required.

API credentials never leave the device

The API key and secret are used exclusively by the NDAgent daemon to connect to the OPNsense API via localhost. They are never transmitted to NetDefense or any external system. There is no need to expose the OPNsense web administration or API endpoints to external networks for NetDefense to function.

Registration Token

Required

The registration token links your OPNsense device to your NetDefense organization. Obtain this token from your NetDefense organization settings:

1. Log in to your NetDefense account

2. Navigate to Organizations and select your organization

3. Copy the Registration Token

Device ID

Auto-generated

Each device requires a unique identifier. It is automatically generated when the settings page first loads. Use the Reset ID button to generate a new UUID if needed.

Caution

Changing the Device ID will cause the device to appear as a new device in your NetDefense dashboard. Any existing configuration or history associated with the old Device ID will not transfer.

Server Address

Advanced

The server address specifies which NetDefense server the agent connects to for configuration syncs and management:

• Default: https://hub.netdefense.io (NetDefense cloud service)
• Self-hosted: Enter your self-hosted NetDefense server URL (e.g., https://netdefense.example.com:8443)

This is the agent’s own endpoint, and it is deliberately not the host ndcli points at. Service Endpoints lists all three NetDefense hostnames and which component uses each.

SSL Verification

Advanced

When enabled (default), the agent verifies the SSL certificate of the NetDefense server. Only disable this when using a self-signed certificate on a self-hosted deployment, or temporarily while troubleshooting connectivity issues.

From agent 1.21.0, the certificate is checked against root certificates built into the agent, not the firewall’s certificate store — see Extra CA File.

Danger

Disabling SSL verification reduces security. Only disable this temporarily for troubleshooting or if using trusted self-signed certificates in a controlled environment.

TOFU Key Fetch SSL Verification

Advanced

The very first time the agent connects, it fetches and pins the platform’s signing keys. This setting controls certificate verification for that one fetch only, and it is deliberately independent of SSL Verification above.

The reason they are separate: if a single toggle covered both, turning off certificate checks for day-to-day traffic on a lab or self-hosted deployment would also open the one moment when the device decides which keys to trust forever. Keeping this on means that even a device running with SSL verification disabled still validates the certificate before pinning anything.

Leave it enabled unless you are pinning against a self-signed deployment and understand that a rogue key planted during that fetch would be trusted from then on.

Extra CA File

Advanced

The path of a PEM file of CA certificates the agent trusts for its connection to NetDefense, in addition to the root certificates built into it. Set it only when this firewall reaches the internet through a TLS-inspection proxy. Empty by default.

From agent 1.21.0, the agent checks the certificate of every connection it makes to NetDefense (registration and the control channel, the trust-key fetch, and the relay for remote sessions) against public root certificates built into the agent and refreshed with each release. It never uses the firewall’s own certificate store for these connections, because NetDefense can sync CAs into that store (see Certificates): a CA synced to the firewall is never trusted by the agent. A TLS-inspection proxy re-signs these connections with a CA of its own, so the agent refuses them, and the device stays offline, until that CA is added here.

1. Get the proxy’s CA certificate in PEM form from whoever runs the proxy. The agent’s log names it — see What the log shows below.

2. From a root shell on the firewall, at the console or over SSH, save it where only root can change it. For example:

   install -o root -g wheel -m 644 ./proxy-ca.pem /usr/local/etc/ndagent-extra-ca.pem

3. Enter the path in Extra CA File and click Apply. The agent restarts and trusts the CAs in the file alongside its built-in roots.

Do this on the firewall itself, through its web interface or a root shell. A NetDefense remote session can’t reach a device that’s offline for this reason, because the relay connection is checked the same way.

The file is read when the agent starts. After changing its contents, restart the agent (service ndagent restart).

The agent uses the file only if:

• the path is absolute and names the file itself, with no symbolic link anywhere on it;
• it isn’t in the system certificate store, which the firewall’s certificates feed, synced ones included: /etc/ssl, /usr/local/etc/ssl, /usr/local/share/certs, /usr/share/certs, or /usr/local/openssl;
• it’s a regular file owned by root, with a single link, that neither its group nor others can write;
• every directory above it is owned by root and writable by root alone, so a file in /tmp is refused;
• it’s no larger than 1 MiB and holds only PEM certificates: one or more -----BEGIN CERTIFICATE----- blocks and no other kind of block. Text between the blocks is ignored.

The settings page takes a path made of letters, digits, and . _ + @ , = - /.

What the log shows. When the agent starts, it logs each CA the file adds, with its subject, SHA-256 fingerprint, and expiry date. A file it can’t use is logged as an ERROR that gives the reason, and the agent carries on with its built-in roots alone. When NetDefense’s certificate isn’t signed by a root the agent trusts, the agent logs an ERROR naming extra_ca_file, at most once every 10 minutes for each address it connects to. Its presented_issuer field names the issuer of the topmost certificate in the chain the agent was shown, which behind an inspection proxy is the CA to add here. presented_sha256 is that topmost certificate’s fingerprint; it’s the server’s own certificate only when the chain carries no intermediate.

Local to this firewall. No NetDefense sync writes this setting or the file it names. It changes only on the firewall: on this page, or from a root shell there, which includes a NetDefense remote session while the device’s Remote Access Policy is Full access. The plugin writes the setting to the agent’s configuration file, /usr/local/etc/ndagent.conf, as extra_ca_file. That file is regenerated from these settings whenever they’re applied and on every plugin update, so set the path here rather than editing the file.

Self-hosted deployments. A self-hosted NetDefense whose certificate comes from a private CA can add that CA here, instead of turning off SSL Verification.

A connection whose SSL verification setting on this page is turned off isn’t checked at all, and this file plays no part in it.

Pathfinder Address

Advanced

The address of the PathFinder relay server, used to establish remote shell connections via ndcli device connect:

• Default: https://pathfinder.netdefense.io (NetDefense cloud service)
• Self-hosted: Enter your self-hosted PathFinder URL

Pathfinder SSL Verification

Advanced

When enabled (default), the agent verifies the SSL certificate of the PathFinder server. Follows the same considerations as SSL Verification above.

Pathfinder Shell

Advanced

Selects the shell that is launched when a remote session is opened via ndcli device connect. The dropdown lists all shells currently installed on the device. OPNsense ships with several shells by default (sh, csh, tcsh, and the OPNsense interactive menu). Additional shells installed on the device (e.g., bash) will appear automatically as options.

Remote Access Policy

Advanced

Sets a ceiling on remote sessions to this device. The platform may request a session at or below the ceiling, and never above it:

Value	What the device will serve
Full access (default)	Whatever is requested — interactive shell, SSH, and the web UI.
Read-only web UI only	The web UI and nothing else, as a read-only session. No shell, no SSH, no command execution, regardless of the privilege held by whoever asked.
Disabled	Nothing. Remote sessions are refused outright and no relay connection is made.

This is the device’s own decision, and it is the one setting on this page that cannot be changed remotely. The value lives in this firewall’s configuration, and the agent has no way to write it — so it cannot be raised by an operator account, by a configuration sync, by an AI agent using the MCP tools, or by the NetDefense platform itself. Changing it requires access to this device.

Tip

Read-only web UI only is the setting most operators actually want on a client site: support staff can still check interface status or confirm a rule during an outage, but nobody can obtain a shell on the box through NetDefense — not you, not your automation, not an incident you haven’t had yet.

Existing devices default to Full access, so upgrading changes nothing until you opt in.

Caution

This governs NetDefense remote sessions only. It does not restrict configuration sync, which is a separate surface — see Allow All Snippet Content. Note in particular that installing a package runs that package’s post-install scripts as root, and this ceiling does not change that.

Allow All Snippet Content

Advanced

Controls whether this device applies privileged content inside a pushed configuration, or refuses it.

Left off (the default), the device rejects individual snippet elements that would grant broad privileges, create system-scope accounts, give an account an interactive shell, install SSH authorized keys, or enable Zabbix remote commands and sudo, or create or update an external authentication server, write a login order, or add or update a certificate or CA — and the sync reports which element was refused and why.

Turn it on only if you legitimately push content that needs it: service accounts or monitoring configuration with those capabilities, authentication servers, or certificates. Check the agent log first to see exactly what is being refused.

Deleting an authentication server, a certificate, or a CA is never blocked by this setting.

Turning it on doesn’t lift the Superuser clearance check (ndagent 1.20.1 and later): a USER or GROUP snippet that would make an account administrator-equivalent is refused unless a Superuser saved it, whichever way this is set.

Caution

This is enforced on the firewall, so it holds even if the configuration was signed and delivered correctly — including by a compromised control plane. Turning it on removes that protection for this device.

Devices upgrading from a release before this setting existed keep their previous behaviour automatically; the default applies to newly configured devices.

The agent’s configuration and its refusal messages call this setting reject_dangerous_snippets, inverted: off here is reject_dangerous_snippets=true. From agent 1.21.0, a refusal names this setting and where to find it. An older agent’s refusal suggests setting reject_dangerous_snippets=false, which means turning this setting on. Change it here and click Apply, not in the agent’s configuration file: the plugin rewrites that file from these settings whenever they’re applied and on every plugin update.

Log Level

Advanced

Controls the verbosity of the NetDefense Agent logs:

Level	Description
DEBUG	Detailed diagnostic information. Use for troubleshooting.
INFO	General operational information (recommended for production).
WARNING	Warning messages for potentially harmful situations.
ERROR	Error events that might still allow the agent to continue running.

Re-bind Token

Advanced

A one-time token used to re-bind this device’s signing key — after a suspected key leak, a hardware replacement, or a routine rotation.

Your NetDefense administrator issues the token with ndcli device rebind-token <name>. Paste it here and save; the agent generates a new keypair and re-registers automatically. The token expires 24 hours after it is issued and can only be used once.

Clear this field once the device shows ENABLED again, so a subsequent re-bind requires a freshly issued token.

Tip

Re-binding deliberately requires this device-local step. The platform cannot rotate a device’s trusted key on its own — someone with access to this firewall has to apply the token here.

Viewing Service Status

Via Web Interface

Navigate to Services > NetDefense > Log File to view real-time agent logs. This integrated log viewer shows:

• Service start/stop events
• Registration status
• Connection events
• Task execution results
• Any errors or warnings

Via Command Line

service ndagent status

tail -f /var/log/ndagent.log

grep ndagent /var/log/messages

Applying Configuration Changes

After making any configuration changes:

1. Click the Apply button at the bottom of the settings page

2. The service will automatically restart with the new configuration

3. Check the Log File page to confirm the service started successfully

User Permissions

Access to the NetDefense plugin requires the Services: NetDefense permission. To grant access:

1. Navigate to System > Access > Groups

2. Edit the desired group

3. Under Assigned Privileges, add Services: NetDefense

4. Save the changes

This grants access to:

• NetDefense settings page
• NetDefense log viewer
• NetDefense API endpoints