[Support] Network Optimizer for UniFi

January 10Jan 10

Application Information

Application: Network Optimizer for UniFi
GitHub Repository: https://github.com/Ozark-Connect/NetworkOptimizer
GitHub Packages: https://github.com/orgs/ozark-connect/packages?repo_name=network-optimizer
Template Repository: https://github.com/stefan-matic/unraid-templates
Network Optimizer template: https://github.com/stefan-matic/unraid-templates/blob/main/templates/network-optimizer.xml
Network Optimizer Speedtest template: https://github.com/stefan-matic/unraid-templates/blob/main/templates/network-optimizer-speedtest.xml
Category: Network, Tools, Security

Disclaimer

I am not the original creator of this application.
All issues with the application itself, bugs, feature requests, etc. should be submitted directly on github: https://github.com/Ozark-Connect/NetworkOptimizer
If you're having issues with the UNRAID deployment or the template itself - or wish to request new changes for the template you can post a reply here.

Description

Network Optimizer for UniFi analyzes your UniFi controller configuration to identify security gaps, performance issues, and misconfigurations. It answers critical questions: Do your firewall rules actually work? Are your VLANs properly isolated? Are your DNS settings being bypassed?

Key Features:

Security Auditing - 39 comprehensive checks across four categories with 0-100 scoring
Adaptive SQM (Smart Queue Management) - Automatically manages bufferbloat with intelligent bandwidth adjustment
Speed Testing - LAN testing via iperf3 and client testing via OpenSpeedTest
Deep Analysis - Detects firewall rule shadowing, conflicts, and VLAN isolation issues
Cellular Monitoring - Track RSSI, RSRP, RSRQ, SINR for U-LTE/U5G-Max backup connections
Dual-WAN Support - Separate configurations per interface with profiles for DOCSIS, fiber, wireless, Starlink, and cellular
PDF Reports - Generate actionable security audit reports
Privacy First - All data stored locally, no external services

Architecture

Network Optimizer uses a two-container architecture:

Network Optimizer - Main application that performs security audits, adaptive SQM, network monitoring, and serves the web UI. Includes SQLite database and iperf3 server capabilities.
Network Optimizer Speedtest - Customized OpenSpeedTest component for browser-based client speed testing that automatically reports results to the main application.

Requirements

Minimum (Audit Only)

UniFi OS device (UDM, UCG, UDR, Cloud Key) or self-hosted Network Server
HTTPS access to UniFi controller API
Local-only UniFi account (Ubiquiti SSO not supported)

Full Functionality

SSH access enabled on gateway and UniFi devices
Enable at: Settings → Control Plane → Console → SSH
Device SSH: UniFi Devices → Device Updates and Settings → Device SSH Settings (UniFi Network 9.5+)

Installation

Prerequisites

Unraid 6.9+ recommended
UniFi controller with local account created
SSH access enabled on UniFi gateway (for SQM and speed testing)

Installation Steps

Install Network Optimizer (Required)
- Search for "Network Optimizer" in Community Applications or template list
- Configure the WebUI port (default: 8042)
- Set your HOST_IP or HOST_NAME for proper operation
- Optionally set APP_PASSWORD for authentication
- Click Apply
Install Network Optimizer Speedtest (Recommended)
- Search for "Network Optimizer Speedtest" in Community Applications or template list
- Configure the WebUI port (default: 3005)
- Set HOST_IP or HOST_NAME to match your Network Optimizer container
- Click Apply
Access the WebUI
- Navigate to http://YOUR-UNRAID-IP:8042
- If you didn't set APP_PASSWORD, retrieve auto-generated password from container logs: docker logs network-optimizer
- Configure your UniFi controller URL in settings
- Authenticate with your local UniFi account
Run Your First Audit
- Navigate to the Security Audit section
- Click "Run Audit"
- Review the results and recommendations

Configuration

Network Optimizer

Parameter	Default	Description
WebUI Port	8042	Port to access the Network Optimizer web interface
Data Directory	/mnt/user/appdata/network-optimizer/data	SQLite database, configs, and license files
SSH Keys Directory	/mnt/user/appdata/network-optimizer/ssh-keys	Optional: SSH keys for device access
Logs Directory	/mnt/user/appdata/network-optimizer/logs	Application logs
Timezone	America/Chicago	Timezone setting
APP_PASSWORD	Auto-generated	Optional: Set custom application password
HOST_IP	Required	Host IP address for path analysis and client speed tests
HOST_NAME	Required	Host name for path analysis and client speed tests
REVERSE_PROXIED_HOST_NAME	-	Reverse proxy hostname (e.g., optimizer.example.com)
BIND_LOCALHOST_ONLY	false	Set to true to bind to localhost only (for reverse proxy)

OpenSpeedTest Configuration

Parameter	Default	Description
OPENSPEEDTEST_PORT	3005	Port where OpenSpeedTest is running
OPENSPEEDTEST_HOST	-	OpenSpeedTest host for CORS configuration
OPENSPEEDTEST_HTTPS	false	Set to true if OpenSpeedTest uses HTTPS
OPENSPEEDTEST_HTTPS_PORT	443	HTTPS port for OpenSpeedTest

Advanced Settings

Parameter	Default	Description
IPERF3_SERVER_ENABLED	false	Enable to accept client-initiated speed tests on port 5201
LOG_LEVEL	Information	Logging level (Trace, Debug, Information, Warning, Error, Critical)
APP_LOG_LEVEL	Information	Network Optimizer specific log level
DEMO_MODE_MAPPINGS	-	Optional: Demo mode configuration

InfluxDB Integration (Advanced)

Parameter	Default	Description
INFLUXDB_URL	-	Optional: InfluxDB URL for metrics storage (e.g., http://localhost:8086)
INFLUXDB_TOKEN	-	Optional: InfluxDB authentication token
INFLUXDB_ORG	network-optimizer	Optional: InfluxDB organization name
INFLUXDB_BUCKET	network_optimizer	Optional: InfluxDB bucket name for storing metrics

Network Optimizer Speedtest

Parameter	Default	Description
WebUI Port	3005	Port for accessing the speed test web interface
Timezone	America/Chicago	Timezone setting
HOST_IP	Required	Host IP for result reporting to Network Optimizer
HOST_NAME	Required	Host name for URL construction
REVERSE_PROXIED_HOST_NAME	-	Reverse proxy hostname for result reporting
OPENSPEEDTEST_PORT	3005	Port number for OpenSpeedTest (should match WebUI Port)

Usage Guide

Initial Setup

Access the WebUI at http://YOUR-UNRAID-IP:8042
Log in with your password (check logs if auto-generated)
Navigate to Settings and configure:
- UniFi Controller URL (e.g., https://192.168.1.1)
- UniFi local account credentials
Save settings and verify connection

Running Security Audits

Network Optimizer performs 39 checks across four categories:

Firewall Analysis
- Deep analysis of firewall rules
- Detection of rule shadowing and conflicts
- Verification that rules actually work as intended
VLAN Security
- Device fingerprinting via MAC lookups
- Confirmation that devices are on intended networks
- VLAN isolation verification
DNS Validation
- DoH (DNS over HTTPS) configuration checks
- WAN DNS settings verification
- Detection of DNS bypass attempts
General Configuration
- Network best practices validation
- Performance issue identification
- Misconfiguration detection

Results are scored 0-100 and categorized by severity with actionable recommendations.

Adaptive SQM Setup

Smart Queue Management automatically addresses bufferbloat:

Navigate to SQM configuration
Select your connection profile:
- DOCSIS (Cable)
- Fiber
- Wireless
- Starlink
- Cellular
Configure dual-WAN if applicable (separate settings per interface)
Enable scheduled speed tests for automatic adjustment
Deploy configuration to gateway (persists through reboots)

LAN Speed Testing

Test network performance between gateway and devices:

Ensure SSH is enabled on UniFi gateway and devices
Navigate to Speed Testing section
Select target device (auto-discovers UniFi equipment)
Run iperf3 test
Review results with network path and hop count correlation

Client Speed Testing

Browser-based testing from phones, tablets, and laptops:

Access Network Optimizer Speedtest at http://YOUR-UNRAID-IP:3005
Click "Start Test"
Results automatically report to Network Optimizer
View location mapping (with HTTPS enabled) for coverage analysis

Cellular Monitoring

For U-LTE or U5G-Max backup connections:

Navigate to Cellular Monitoring
View real-time metrics:
- RSSI (Signal Strength)
- RSRP (Reference Signal Received Power)
- RSRQ (Reference Signal Received Quality)
- SINR (Signal-to-Interference-plus-Noise Ratio)
Track tower information and connection quality

Generating Reports

Complete a security audit
Navigate to Reports section
Click "Generate PDF Report"
Download actionable security audit report

Troubleshooting

Can't Connect to UniFi Controller

Verify controller URL includes HTTPS (e.g., https://192.168.1.1)
Ensure you created a local-only account (Ubiquiti SSO not supported)
Check firewall rules allow access from Unraid to controller
Verify SSL certificate is trusted or self-signed certificates are accepted

SSH Connection Failures

Confirm SSH is enabled: Settings → Control Plane → Console → SSH
Verify Device SSH Settings: UniFi Devices → Device Updates and Settings
Ensure SSH keys are properly mounted (if using key-based auth)
Check that SSH credentials match your UniFi account

Speed Test Not Working

Verify HOST_IP or HOST_NAME is set correctly in both containers
Ensure Network Optimizer Speedtest container is running
Check that port 3005 is accessible
Verify CORS configuration for OpenSpeedTest

iperf3 Tests Failing

Enable iperf3 server by setting IPERF3_SERVER_ENABLED=true
Ensure port 5201 is accessible on the gateway
Verify SSH access to target devices
Check that iperf3 is installed on UniFi devices

High CPU Usage

Reduce concurrent speed test operations
Lower LOG_LEVEL to Warning or Error
Disable scheduled speed tests if not needed

Container Won't Start

Check that host port 8042 is not already in use
Verify data directory permissions: /mnt/user/appdata/network-optimizer/data
Review container logs: docker logs network-optimizer
Ensure HOST_IP or HOST_NAME is set

Performance Notes

Docker Desktop on macOS/Windows introduces virtualization overhead that limits multi-gigabit testing accuracy
For best speed test results, run on native Linux (Unraid is ideal)
LAN testing accuracy depends on SSH connection stability
Large networks may take longer for initial device discovery

Licensing

Network Optimizer uses Business Source License 1.1:

Permitted: Personal, non-commercial use across up to three sites
Requires License: Commercial deployment by MSPs, consultants, or service providers
Future: Transitions to Apache 2.0 on January 1, 2028
Commercial Inquiries: [email protected]

Privacy & Security

All data is stored locally in SQLite on your Unraid server
No data is sent to external services
UniFi credentials are stored securely (encrypted at rest)
SSH connections are established only to your local UniFi devices
Network topology data never leaves your network

Current Status

Functional:

Core security auditing (39 checks)
Adaptive SQM with multiple connection profiles
LAN speed testing via iperf3
Client speed testing via OpenSpeedTest
Cellular monitoring for U-LTE/U5G-Max

In Development:

Time-series metrics and historical analysis
Cable modem statistics
Multi-site support

Support

If you need help or encounter issues, please post in this thread with:

Unraid version
Network Optimizer version (check container logs or WebUI)
UniFi Network version
UniFi devices in use (UDM, UCG, UDR, etc.)
Description of the issue
Relevant logs (use docker logs network-optimizer or docker logs network-optimizer-speedtest)
Network setup (single/dual-WAN, number of VLANs, etc.)

For bugs or feature requests, you can also open an issue on the GitHub repository.

FAQ

Q: Does this work with non-UniFi networks?
A: No. Network Optimizer is specifically designed for UniFi controllers and devices. It requires UniFi API access.

Q: Can I use my Ubiquiti SSO account?
A: No. You must create a local-only account on your UniFi controller. Ubiquiti SSO is not supported.

Q: Is my UniFi password stored securely?
A: Yes. Credentials are encrypted at rest in the SQLite database and transmitted only over HTTPS to your local controller.

Q: Do I need the speedtest container?
A: It's optional but recommended. The speedtest container enables browser-based client testing from phones, tablets, and laptops.

Q: How accurate are the speed tests?
A: Very accurate on native Linux (Unraid). Docker Desktop on macOS/Windows has virtualization overhead that can affect multi-gigabit testing.

Q: Can this configure my UniFi network automatically?
A: No. Network Optimizer is an analysis and auditing tool. It provides recommendations but does not automatically modify your UniFi configuration. SQM deployment is the exception.

Q: Does this work with UbiOS (UDM/UCG/UDR)?
A: Yes. It works with UniFi OS devices and self-hosted Network Server installations.

Q: What's the difference between this and UniFi's built-in analytics?
A: Network Optimizer performs deep security analysis that UniFi doesn't provide, such as firewall rule conflict detection, VLAN isolation verification, and DNS bypass detection. It also offers advanced SQM and comprehensive speed testing.

Changelog

Version 1.0.0 (Initial Release)

Network Optimizer template
Network Optimizer Speedtest template
Security auditing with 39 checks across four categories
Adaptive SQM with connection profiles
LAN speed testing via iperf3
Client speed testing via OpenSpeedTest
Cellular monitoring support
PDF report generation
InfluxDB integration (optional)