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 displays the essential configuration options. Click Show advanced options to see all available settings.

Required Settings

Setting	Description
Enable NetDefense	Activates the NetDefense Agent service
Registration Token	UUID token provided by your NetDefense account for device registration

Advanced Settings

Click the toggle to reveal advanced configuration options:

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 server.
Log Level	INFO	Controls the verbosity of agent logs (DEBUG, INFO, WARNING, ERROR).

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 checkbox

3. Enter your Registration Token

   Your registration token is available from your NetDefense dashboard. 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 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

Registration Token

Required

The registration token links your OPNsense device to your NetDefense account. Obtain this token from your NetDefense dashboard:

1. Log in to your NetDefense account

2. Navigate to Devices > Add Device

3. Copy the registration token provided

Device ID

Auto-generated

Each device requires a unique identifier. The Device ID:

• 🔄 Is automatically generated when the settings page first loads
• 🔁 Can be reset using the Reset ID button
• ✅ Must be in valid UUID format

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:

• ☁️ 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. Disable only if:

• 🔏 Using a self-signed certificate on a self-hosted deployment
• 🔍 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.

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.

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