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 the required privileges 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.
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.

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 the minimum required privileges and generates an API key/secret pair for it.

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)

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.

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.

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. 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 — and the sync reports which element was refused and why.

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

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.

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