secubox-openwrt/package/secubox/luci-app-network-tweaks/README.md

Network Services Dashboard (luci-app-network-tweaks)

Unified network services monitoring with dynamic component discovery, cumulative impact tracking, and automatic DNS/hosts synchronization

Overview

Network Services Dashboard (formerly Network Tweaks) combines automated VHost DNS synchronization with comprehensive network services monitoring. It provides real-time visibility into all network-impacting services, their cumulative effect on your system, and integrates with Network Modes for profile-based configuration.

Key Features

Network Services Dashboard (v2.0+)

• 🔍 Dynamic Component Discovery - Automatically discovers network-relevant services from the SecuBox plugin catalog
• 📊 Cumulative Impact Tracking - Real-time metrics showing total DNS entries, VHosts, and exposed ports
• 🎯 Network Mode Integration - Sync settings controlled by network mode profiles
• 🔄 Auto-Refresh - Live updates every 10 seconds
• 📡 Multi-Source Data Aggregation - Combines manifest metadata, install state, runtime status, and VHost associations
• 🎨 Modern Grid UI - Responsive card-based layout with detailed component views

Core Synchronization (v1.0+)

• Automatic DNS Generation - Creates DNSmasq configuration entries for all enabled VHost domains
• Hosts File Management - Updates /etc/hosts with VHost domain entries
• Real-time Synchronization - Watches VHost configuration changes and auto-updates
• LuCI Integration - User-friendly web interface with status dashboard
• Flexible Configuration - Choose which features to enable (DNS, hosts, or both)
• Network Awareness - Auto-detects LAN IP or allows manual override

Table of Contents

• Installation
• Quick Start
• Network Services Dashboard
• Core Synchronization
• Configuration
• Network Mode Integration
• Technical Documentation
• Troubleshooting
• Development
• Changelog

Installation

# Build the package
make package/luci-app-network-tweaks/compile

# Install on router
opkg install luci-app-network-tweaks_*.ipk

# Enable and start
/etc/init.d/network-tweaks enable
/etc/init.d/network-tweaks start

Quick Start

1. Access the Dashboard:

   • Navigate to Network → Network Services Dashboard in LuCI

2. View Network Impact:

   • See active components, DNS entries, VHosts, and exposed ports at a glance
   • Monitor individual service status and contributions

3. Configure Synchronization:

   • Enable DNS and/or hosts synchronization
   • Choose auto-sync or manual mode

4. Integrate with VHost Manager:

   • Enable VHosts in VHost Manager
   • Network Tweaks automatically makes them resolvable on your LAN

Network Services Dashboard

Architecture

Plugin Catalog Manifests → Discovery Engine → Data Aggregation → Dashboard Display
         ↓                        ↓                   ↓                 ↓
    *.json files          Network filter       Unified data         Grid cards
    (metadata)           (ports/protocols)      model (JSON)         + metrics

Dashboard Sections

1. Impact Summary

Four metric cards showing overall network impact:

Metric	Description
Active Components	Services currently running
DNS Entries	Total DNS records managed
Published VHosts	Virtual hosts configured
Exposed Ports	Network ports opened

2. Network Mode Status

Shows:

• Current network mode (Router, DMZ, Travel, etc.)
• Mode-specific sync settings
• Whether DNS sync is enabled

3. Components Grid

Responsive grid of component cards, each showing:

Status Badges:

• 🟢 Running - Service active
• 🔴 Stopped - Service installed but not running
• ⚪ N/A - No runtime available

Install State:

• Installed - All packages present
• Partial - Some packages missing
• Available - Ready to install

Network Impact:

• 🌐 DNS Entries - Number of DNS records
• 📡 VHosts - Published virtual hosts
• 🔌 Ports - Network ports exposed

Contribution:

• Shows how much this component adds to overall config

Actions:

• Details - View full component information

Component Details Modal

Click Details on any card to see:

Component: AdGuard Home
Category: network
Install State: installed
Service State: running

Network Impact:
• DNS Entries: 1
• VHosts: 1
• Ports: 2

Capabilities:
[dns-filtering] [ad-blocking] [vhost-publish]

Discovery Process

1. Manifest Scanning: Scans /usr/share/secubox/plugins/catalog/*.json
2. Network Filtering: Identifies apps with network impact:
   • network.inbound_ports[] - Apps exposing network ports
   • network.protocols[] - Apps using network protocols
   • capabilities[] - Network-related capabilities
3. State Queries:
   • Install State: via opkg status or apk info
   • Runtime State: via docker ps or init.d services
   • VHost Associations: matches to published VHosts
4. Impact Calculation: Counts DNS entries, hosts, ports, VHosts
5. Aggregation: Combines into unified JSON response

Network Relevance Detection

An app appears in the dashboard if its manifest contains:

Network Ports:

{
  "network": {
    "inbound_ports": [53, 3000]
  }
}

Network Protocols:

{
  "network": {
    "protocols": ["http", "https", "dns"]
  }
}

Network Capabilities:

{
  "capabilities": [
    "vhost-publish",
    "dns-filtering",
    "proxy",
    "firewall",
    "vpn",
    "network-service"
  ]
}

Core Synchronization

How It Works

1. Monitors VHosts: Watches /etc/config/vhosts for enabled virtual hosts
2. Generates Entries:
   • DNSmasq: Creates /tmp/dnsmasq.d/50-vhosts.conf with address=/domain/ip entries
   • Hosts: Appends entries to /etc/hosts in managed section
3. Auto-Reloads: Automatically reloads DNSmasq when changes are detected
4. Triggers:
   • VHost configuration changes (via UCI triggers)
   • Network interface up events (LAN)
   • Manual sync via LuCI or CLI

Generated Files

DNSmasq Configuration

Location: /tmp/dnsmasq.d/50-vhosts.conf

# Auto-generated DNS entries for VHost Manager domains
# Managed by network-tweaks
# IP: 192.168.1.1
# Generated: 2026-01-01 12:00:00

address=/cloud.local/192.168.1.1
address=/adguard.local/192.168.1.1
address=/domoticz.local/192.168.1.1

Hosts Entries

Appended to: /etc/hosts

# Managed by network-tweaks
# Auto-generated hosts entries for VHost Manager domains
# Generated: 2026-01-01 12:00:00
192.168.1.1 cloud.local
192.168.1.1 adguard.local
192.168.1.1 domoticz.local

Command Line Usage

# Synchronize all entries
network-tweaks-sync sync

# View current status
network-tweaks-sync status

# Clean up all managed entries
network-tweaks-sync cleanup

Service Management

# Enable auto-start
/etc/init.d/network-tweaks enable

# Start service
/etc/init.d/network-tweaks start

# Reload configuration (triggers sync)
/etc/init.d/network-tweaks reload

# Check status
/etc/init.d/network-tweaks status

Configuration

Web Interface Settings

Found under Configuration section in the dashboard:

Option	Default	Description
Enable Network Tweaks	✓	Master switch for DNS/hosts synchronization
Auto Sync	✓	Automatically sync when VHost config changes
Sync DNSmasq	✓	Generate DNSmasq config for local domain resolution
Sync /etc/hosts	✓	Update /etc/hosts file with VHost domains
LAN Interface	lan	Network interface for IP address detection
Override IP Address	empty	Manually specify IP (leave empty for auto-detect)

Configuration File

Edit /etc/config/network_tweaks:

config global 'global'
	option enabled '1'            # Enable/disable Network Tweaks
	option auto_sync '1'          # Auto-sync on config changes
	option sync_hosts '1'         # Update /etc/hosts
	option sync_dnsmasq '1'       # Generate DNSmasq config
	option lan_interface 'lan'    # Interface to use for IP
	option default_ip ''          # Manual IP override (empty = auto-detect)

Network Mode Integration

Each network mode profile includes network-tweaks settings:

Router Mode (Default)

config mode 'router'
	option network_tweaks_enabled '1'
	option network_tweaks_sync_hosts '1'
	option network_tweaks_sync_dnsmasq '1'
	option network_tweaks_auto_sync '1'

Sniffer Mode (Transparent)

config mode 'sniffer'
	option network_tweaks_enabled '0'    # Disabled for transparency
	option network_tweaks_sync_hosts '0'
	option network_tweaks_sync_dnsmasq '0'

Other Modes

All other modes (DMZ, Access Point, Relay, Double NAT, Travel, Multi-WAN, VPN Relay) enable network-tweaks with full synchronization.

Technical Documentation

Backend RPC API

getNetworkComponents

Returns all network-relevant components with aggregated data.

Request: No parameters

Response:

{
  "success": true,
  "components": [
    {
      "id": "adguardhome",
      "name": "AdGuard Home",
      "category": "network",
      "install_state": "installed",
      "service_state": "running",
      "network_impact": {
        "dns_entries": 1,
        "vhosts": 1,
        "ports": 2
      },
      "cumulative_contribution": {
        "dnsmasq_entries": 1,
        "hosts_entries": 1,
        "ports_opened": 2
      },
      "capabilities": ["dns-filtering", "vhost-publish"]
    }
  ],
  "cumulative_summary": {
    "total_components": 12,
    "active_components": 8,
    "total_dns_entries": 18,
    "total_vhosts": 6,
    "total_ports_exposed": 23
  },
  "network_mode": {
    "current_mode": "router",
    "mode_name": "Router",
    "sync_enabled": true
  }
}

getCumulativeImpact

Returns aggregated network impact summary.

Request: No parameters

Response:

{
  "success": true,
  "total_components": 12,
  "active_components": 8,
  "total_dns_entries": 18,
  "total_vhosts": 6,
  "total_ports_exposed": 23
}

setComponentEnabled

Enable/disable component network features.

Request:

{
  "app_id": "adguardhome",
  "enabled": true
}

Response:

{
  "success": true,
  "message": "Component network features updated"
}

Legacy Methods

• getStatus - Status with VHost counts
• syncNow - Trigger immediate synchronization
• getConfig - Get current configuration
• setConfig - Update configuration

CLI Integration

UBUS Commands:

# Get all components
ubus call luci.network-tweaks getNetworkComponents

# Get cumulative impact
ubus call luci.network-tweaks getCumulativeImpact

# Get configuration
ubus call luci.network-tweaks getConfig

# Trigger sync
ubus call luci.network-tweaks syncNow

Frontend Architecture

Main View: /luci-static/resources/view/network-tweaks/overview.js

Key methods:

• load() - Initialize data and load CSS
• renderDashboard() - Build complete dashboard
• renderCumulativeImpact() - Impact summary cards
• renderNetworkModeStatus() - Mode indicator
• renderComponentsGrid() - Component cards
• showComponentDetails() - Details modal
• pollData() - Auto-refresh (10s interval)
• updateDisplay() - Live DOM update

Styling: /luci-static/resources/network-tweaks/dashboard.css

Responsive grid:

• Desktop: 4-column grid (200px min)
• Mobile: Single column
• Hover effects and animations
• Status color coding

Troubleshooting

Components Not Appearing

Symptoms: Dashboard shows "No network-impacting components detected"

Solutions:

1. Check plugin catalog exists:

   ls /usr/share/secubox/plugins/catalog/
   

2. Verify manifest format:

   cat /usr/share/secubox/plugins/catalog/adguardhome.json
   

3. Test RPC manually:

   ubus call luci.network-tweaks getNetworkComponents
   

Service State Shows "N/A"

Causes:

• Docker not installed/running
• Init script doesn't exist
• Wrong runtime in manifest

Solutions:

1. For Docker apps:

   docker ps --filter "name=adguardhome"
   

2. For native services:

   /etc/init.d/service-name running
   

DNS Resolution Not Working

Solutions:

1. Check dnsmasq config:

   cat /tmp/dnsmasq.d/50-vhosts.conf
   

2. Verify dnsmasq running:

   ps | grep dnsmasq
   

3. Check hosts file:

   cat /etc/hosts
   

4. Trigger manual sync:

   • Click Sync Now in dashboard
   • Or: /usr/sbin/network-tweaks-sync sync

5. Ensure clients use router as DNS:

   nslookup cloud.local
   

Auto-Refresh Not Working

Solutions:

1. Check browser console for errors
2. Verify polling (10s interval)
3. Force reload: Ctrl+Shift+R

Development

Adding Custom Components

Create a plugin catalog entry:

# /usr/share/secubox/plugins/catalog/myapp.json
{
  "id": "myapp",
  "name": "My Custom App",
  "category": "network",
  "runtime": "native",
  "packages": ["myapp"],
  "network": {
    "inbound_ports": [8080],
    "protocols": ["http"]
  },
  "capabilities": ["vhost-publish"]
}

Adding New RPC Methods

1. Declare in list section:

   json_add_object "myMethod"
   json_close_object
   

2. Implement in call section:

   myMethod)
       json_init
       json_add_boolean "success" 1
       # Implementation
       json_dump
       ;;
   

Frontend Development

Add dashboard sections:

renderDashboard: function() {
    return E('div', { 'class': 'network-tweaks-dashboard' }, [
        this.renderCumulativeImpact(),
        this.renderMyNewSection(),  // Add here
        this.renderComponentsGrid()
    ]);
}

Example Workflows

Setting up Nextcloud with Network Tweaks

1. Install Nextcloud:

   nextcloudctl install
   /etc/init.d/nextcloud start
   

2. Create VHost in VHost Manager:

   • Domain: cloud.local
   • Backend: http://127.0.0.1:80
   • SSL: Enabled
   • Enable VHost

3. Network Tweaks automatically:

   • Creates DNS entry: cloud.local → 192.168.1.1
   • Updates hosts file
   • Reloads DNSmasq

4. Access from any device:

   • Open https://cloud.local
   • Domain resolves to router
   • Nginx forwards to Nextcloud

Performance Considerations

Response Times

• Typical RPC response: 200-500ms
• Dashboard initial load: 1-2s
• Auto-refresh impact: Minimal

Polling

• Interval: 10 seconds
• CPU impact: Minimal
• Network: ~5KB per request
• Memory: Stable (no accumulation)

Future Optimizations

• 30-second TTL cache for manifest scans
• Incremental discovery updates
• Background worker for heavy queries

Dependencies

• luci-base - LuCI web interface
• rpcd - UBUS RPC daemon
• luci-app-vhost-manager - VHost Manager (source of domains)
• dnsmasq - DNS server

Architecture Diagram

┌─────────────────────────────────────────────────────────────┐
│                    Plugin Catalog                            │
│        /usr/share/secubox/plugins/catalog/*.json            │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ↓
┌─────────────────────────────────────────────────────────────┐
│              Discovery Engine (RPC)                          │
│         /usr/libexec/rpcd/luci.network-tweaks               │
│                                                               │
│  ┌────────────────────────────────────────────┐             │
│  │ discover_network_components()              │             │
│  │ ├─ check_network_relevance()              │             │
│  │ ├─ query_install_state()                  │             │
│  │ ├─ query_service_state()                  │             │
│  │ ├─ discover_vhost_associations()          │             │
│  │ └─ calculate_network_impact()             │             │
│  └────────────────────────────────────────────┘             │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ↓
┌─────────────────────────────────────────────────────────────┐
│              Frontend Dashboard                              │
│    /luci-static/resources/view/network-tweaks/overview.js  │
│                                                               │
│  ┌────────────────────────────────────────────┐             │
│  │ Impact Summary Cards                       │             │
│  │ Network Mode Status                        │             │
│  │ Components Grid (auto-refresh 10s)        │             │
│  │ Component Details Modal                    │             │
│  └────────────────────────────────────────────┘             │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ↓
┌─────────────────────────────────────────────────────────────┐
│              Synchronization Engine                          │
│            /usr/sbin/network-tweaks-sync                    │
│                                                               │
│  Reads: /etc/config/vhosts                                  │
│  Generates: /tmp/dnsmasq.d/50-vhosts.conf                  │
│  Updates: /etc/hosts                                        │
│  Reloads: dnsmasq                                           │
└─────────────────────────────────────────────────────────────┘

Changelog

v2.0.0 (2026-01-01) - Network Services Dashboard

Major Features:

• ✨ Dynamic component discovery from plugin catalog
• ✨ Cumulative impact tracking dashboard
• ✨ Network mode integration
• ✨ Grid-based UI with component cards
• ✨ Auto-refresh with 10-second polling
• ✨ Component details modal
• ✨ Responsive design with dark mode support

Backend:

• Added getNetworkComponents RPC method
• Added getCumulativeImpact RPC method
• Added setComponentEnabled RPC method
• Added 8 helper functions for discovery/aggregation
• Added network mode status integration

Frontend:

• Complete rewrite of overview.js
• New dashboard.css with grid system
• Impact summary cards
• Network mode indicator
• Component grid with status badges

Configuration:

• Added network-tweaks options to all 8 network modes
• Config remains backward compatible

v1.0.0 - Initial Release (Network Tweaks)

• Basic VHost to DNS/hosts synchronization
• Manual sync trigger
• Simple statistics display
• Auto-sync on VHost changes
• Hotplug integration

License

Apache-2.0

Author

CyberMind Studio contact@cybermind.fr

Support

• Issues: https://github.com/CyberMind-FR/secubox-openwrt/issues
• Documentation: This README
• Version: 2.0.0
• Last Updated: 2026-01-01

Contributing

Contributions welcome! Please:

1. Test changes thoroughly
2. Update documentation
3. Follow existing code style
4. Submit PR with clear description