[

KINGWERX

]
← FIREWALL PROJECTS

INSTALLATION GUIDE

osUI Dashboard Setup Instructions for OPNsense

OVERVIEW INSTALLATION LIVE DEMO

// DOWNLOAD PACKAGE

DOWNLOAD INSTALLOSDASH.ZIP
WINDOWS
LINUX / MAC
1
ENABLE SSH ON OPNSENSE

Enable SSH access on your OPNsense firewall for the initial installation:

# In OPNsense Web UI:
System → Settings → Administration

# Under "Secure Shell":
# Check "Enable Secure Shell"
# Check "Permit root user login"
# Click "Save"
2
EXTRACT THE INSTALLER

Extract the downloaded installosdash.zip to a folder on your computer.

3
RUN THE DEPLOYMENT SCRIPT

Open PowerShell, navigate to the extracted folder, and run the deployment script:

cd C:\path\to\installosdash
.\deploy.ps1

The script will prompt you for:

  • OPNsense IP address
  • SSH port (default: 22)
  • Username (default: root)
  • Password

It will then automatically upload all files and run the installer on OPNsense.

Tip: If PowerShell blocks the script, run: powershell -ExecutionPolicy Bypass -File deploy.ps1

4
ACCESS THE DASHBOARD

Open your browser and navigate to the dashboard:

http://YOUR_OPNSENSE_IP:5000

Default Login:

  • Username: admin
  • Password: admin

Important: Change your password immediately in Settings!

1
ENABLE SSH ON OPNSENSE

Enable SSH access on your OPNsense firewall:

# In OPNsense Web UI:
System → Settings → Administration

# Under "Secure Shell":
# Check "Enable Secure Shell"
# Check "Permit root user login"
# Click "Save"
2
UPLOAD FILES TO OPNSENSE

Extract the zip and upload the installer folder to OPNsense:

# Extract the zip
unzip installosdash.zip

# Upload the entire folder to OPNsense
scp -r installosdash root@YOUR_OPNSENSE_IP:/tmp/
3
RUN THE INSTALLER

SSH into OPNsense and run the install script:

ssh root@YOUR_OPNSENSE_IP
cd /tmp/installosdash
sh install.sh

The installer will automatically install Python, dependencies, and configure the service.

4
ACCESS THE DASHBOARD

Open your browser and navigate to:

http://YOUR_OPNSENSE_IP:5000

Default Login: admin / admin

Change your password immediately in Settings!

5
CREATE OPNSENSE API KEY

Required: The dashboard uses the OPNsense REST API for firewall rules, aliases, DHCP, WireGuard, and more. You must create an API key for it to work.

In the OPNsense Web UI:

1
Go to System → Access → Users
2
Find the root user in the list
3
Look for the API keys section (it has a + button — this may be below the user list, not inside the edit form)
4
Click the + button to generate a new API key
5
A file will download (e.g. apikey.txt) containing your key and secret
6
Open the file and copy both values

Now add them to the dashboard:

7
In the osUI dashboard, go to Settings (gear icon)
8
Under OPNsense API, paste the API Key and API Secret
9
Click Save Settings

Tip: Click "Test Connection" to verify the API key works. You should see "Connected OK".

6
ENABLE DNS QUERY LOGGING

The dashboard displays DNS queries from your network devices. This requires enabling query logging in the DNS Resolver:

# In OPNsense Web UI:
Services → Unbound DNS → General

# Scroll to "Advanced" or "Custom options"
# Add the following custom option:

server:
log-queries: yes

# Click "Save" then "Apply"

Note: Without this setting, the DNS Query Log and Sites Visited features will be empty.

7
INSTALL GEOIP DATABASE (OPTIONAL)

For country flags and location data on the threat map:

1. Create a free account at MaxMind GeoLite2

2. Download GeoLite2-City.mmdb (the binary .mmdb file)

3. Upload it to OPNsense:

scp GeoLite2-City.mmdb root@YOUR_OPNSENSE_IP:/opt/dashboard/

4. Go to dashboard Settings and click Restart Dashboard to load the database.

8
CONFIGURE ABUSEIPDB (OPTIONAL)

To enable automatic threat reporting:

1. Create a free account at abuseipdb.com

2. Go to Account → API and create a key

3. In the dashboard Settings, paste the key under AbuseIPDB Integration

4. Enable Auto-Report Threats and click Save Settings

Note: The free tier allows 1,000 API lookups per day, which is sufficient for most home networks.

9
CONFIGURE EMAIL NOTIFICATIONS (OPTIONAL)

The dashboard can send email alerts when your WAN goes down/recovers and when monitored devices go offline. Configure SMTP in Settings:

SMTP Settings:

  • SMTP Host: Your email provider's SMTP server
  • SMTP Port: 587 (TLS) or 465 (SSL)
  • SMTP Username: Your email address
  • SMTP Password: Your email password or app password
  • From Address: The address emails will be sent from
  • Recipients: Up to 3 email addresses to receive alerts

Gmail Setup:

Gmail requires an App Password instead of your regular Google password. Here's how to set it up:

# Gmail SMTP Settings:
SMTP Host:     smtp.gmail.com
SMTP Port:     587
SMTP Username: [email protected]
SMTP Password: (App Password - see below)
From Address:  [email protected]

How to create a Gmail App Password:

1
Go to myaccount.google.com/security
2
Enable 2-Step Verification if not already enabled (required for App Passwords)
3
Go to myaccount.google.com/apppasswords
4
Enter a name (e.g. "osUI Dashboard") and click Create
5
Copy the 16-character password that appears
6
Paste it as the SMTP Password in dashboard Settings

Tip: After saving, use the "Send Test" button in Settings to verify your email configuration is working.

Other Email Providers:

# Outlook / Hotmail:
SMTP Host: smtp.office365.com  Port: 587

# Yahoo Mail:
SMTP Host: smtp.mail.yahoo.com  Port: 587

# iCloud Mail:
SMTP Host: smtp.mail.me.com     Port: 587

# Note: Most providers require an App Password.
# Check your provider's security settings.
10
SET UP WIREGUARD VPN (OPTIONAL)

WireGuard requires the os-wireguard plugin. To use the VPN management page:

1
Install the plugin: System > Firmware > Plugins → search os-wireguard → click + to install
2
Make sure your API key is configured (Step 5 above)
3
Click the VPN Config link on the Settings page
4
Click Create Server to set up a WireGuard server with auto-generated keys
5
Add peers and scan the QR code with the WireGuard app on your phone, or download the .conf file for desktop clients

Note: The dashboard automatically creates firewall rules to allow WireGuard traffic (UDP 51820) when you create a server. No manual firewall configuration needed.

// SERVICE COMMANDS

  • service dashboard start - Start the dashboard
  • service dashboard stop - Stop the dashboard
  • service dashboard restart - Restart the dashboard
  • service dashboard status - Check if running

// SECURITY REMINDER

  • Disable SSH: After installation is complete, disable SSH on your OPNsense firewall:
# In OPNsense Web UI:
System → Settings → Administration

# Under "Secure Shell":
# Uncheck "Enable Secure Shell"
# Click "Save"
  • SSH is only needed during installation. The dashboard uses the OPNsense REST API for all daily operations, so SSH can be safely disabled. Re-enable it temporarily for updates.

// NOTES

  • Auto-Start: The dashboard automatically starts on boot. No additional configuration needed.
  • Log File: View logs at /var/log/dashboard.log
  • Updates: To update, download the latest package and run the installer again.
  • Firewall Rules: Port 5000 should be accessible from your LAN by default.
  • Backup: Use the Settings page to download a full backup (config + dashboard data).