secubox-openwrt/DEBUG_GUIDE.md

SecuBox LuCI WebUI Debug Guide

Date: 2026-01-04 Status: Debug logging added to all views

Overview

Debug logging has been added to all SecuBox Admin LuCI views to troubleshoot why the CLI works but the WebUI doesn't. All debug messages use the browser console and are prefixed with [*-DEBUG] tags.

Debug Levels Added

1. API Module (secubox-admin/api.js)

Prefix: [API-DEBUG]

All RPC calls are wrapped with debug logging:

[API-DEBUG] Calling: getCatalogSources with args: []
[API-DEBUG] Success: getCatalogSources result: {sources: [...]}
// OR
[API-DEBUG] Error: getCatalogSources error: Error object
[API-DEBUG] Error stack: full stack trace

Methods Tracked:

• getApps, installApp, removeApp
• getModules, enableModule, disableModule
• getHealth, getAlerts, getLogs
• getCatalogSources, setCatalogSource, syncCatalog
• checkUpdates, getAppVersions, getChangelog
• getWidgetData

2. Updates View (view/secubox-admin/updates.js)

Prefix: [UPDATES-DEBUG]

Load Phase:

[UPDATES-DEBUG] ========== LOAD START ==========
[UPDATES-DEBUG] Starting Promise.all with 3 API calls...
[UPDATES-DEBUG] checkUpdates() raw result: {...}
[UPDATES-DEBUG] checkUpdates() result type: object
[UPDATES-DEBUG] checkUpdates() keys: [...]
[UPDATES-DEBUG] getApps() raw result: {...}
[UPDATES-DEBUG] getModules() raw result: {...}
[UPDATES-DEBUG] ========== ALL PROMISES RESOLVED ==========
[UPDATES-DEBUG] Result[0] (updates): {...}
[UPDATES-DEBUG] Result[1] (apps): {...}
[UPDATES-DEBUG] Result[2] (modules): {...}
[UPDATES-DEBUG] ========== LOAD COMPLETE ==========

Render Phase:

[UPDATES-DEBUG] ========== RENDER START ==========
[UPDATES-DEBUG] Render data (raw): [...]
[UPDATES-DEBUG] Render data type: object
[UPDATES-DEBUG] updateData: {...}
[UPDATES-DEBUG] updatesAvailable: [...]
[UPDATES-DEBUG] totalUpdates: 5
[UPDATES-DEBUG] ========== RENDER PROCESSING ==========

Error Tracking:

[UPDATES-DEBUG] checkUpdates() ERROR: Error object
[UPDATES-DEBUG] checkUpdates() error message: "method not found"
[UPDATES-DEBUG] checkUpdates() error stack: full stack

3. Catalog Sources View (view/secubox-admin/catalog-sources.js)

Prefix: [CATALOG-SOURCES-DEBUG]

Similar structure to Updates view:

Load Phase:

[CATALOG-SOURCES-DEBUG] ========== LOAD START ==========
[CATALOG-SOURCES-DEBUG] getCatalogSources() raw result: {...}
[CATALOG-SOURCES-DEBUG] getCatalogSources() sources: [...]
[CATALOG-SOURCES-DEBUG] ========== ALL PROMISES RESOLVED ==========

Render Phase:

[CATALOG-SOURCES-DEBUG] ========== RENDER START ==========
[CATALOG-SOURCES-DEBUG] sources array: [...]
[CATALOG-SOURCES-DEBUG] sources count: 4

4. Apps Manager View (view/secubox-admin/apps.js)

Prefix: [APPS-DEBUG]

Similar structure to other views:

Load Phase:

[APPS-DEBUG] ========== LOAD START ==========
[APPS-DEBUG] getApps() raw result: {...}
[APPS-DEBUG] getApps() apps: [...]
[APPS-DEBUG] ========== ALL PROMISES RESOLVED ==========

Render Phase:

[APPS-DEBUG] ========== RENDER START ==========
[APPS-DEBUG] apps array: [...]
[APPS-DEBUG] apps count: 37

How to Use Debug Logging

Step 1: Open Browser Console

Chrome/Edge:

• Press F12 or Ctrl+Shift+I
• Click "Console" tab

Firefox:

• Press F12 or Ctrl+Shift+K
• Click "Console" tab

Step 2: Filter Debug Messages

In console filter box, type:

• DEBUG - Show all debug messages
• API-DEBUG - Show only API calls
• UPDATES-DEBUG - Show only Updates view
• CATALOG-SOURCES-DEBUG - Show only Catalog Sources view
• APPS-DEBUG - Show only Apps Manager view

Step 3: Navigate to Views

1. Updates View: /cgi-bin/luci/admin/secubox/admin/updates

   • Watch console for [UPDATES-DEBUG] messages
   • Check if checkUpdates() succeeds or fails
   • Verify result structure

2. Catalog Sources: /cgi-bin/luci/admin/secubox/admin/catalog-sources

   • Watch for [CATALOG-SOURCES-DEBUG] messages
   • Check if getCatalogSources() succeeds
   • Verify sources array

3. Apps Manager: /cgi-bin/luci/admin/secubox/admin/apps

   • Watch for [APPS-DEBUG] messages
   • Check if getApps() succeeds
   • Verify apps array

Step 4: Identify Issues

Common error patterns:

RPC Method Not Found

[API-DEBUG] Error: getCatalogSources error: Error: method not found

Cause: RPCD backend not deployed or not running Fix: Redeploy secubox-core package, restart rpcd

Permission Denied

[API-DEBUG] Error: getCatalogSources error: Error: access denied

Cause: ACL permissions not set Fix: Check /usr/share/rpcd/acl.d/ files

Empty Result

[CATALOG-SOURCES-DEBUG] getCatalogSources() sources: []

Cause: UCI config not loaded or empty Fix: Check /etc/config/secubox-appstore

Null/Undefined Result

[APPS-DEBUG] getApps() raw result: null
[APPS-DEBUG] getApps() result type: object
[APPS-DEBUG] getApps() keys: []

Cause: Backend returned invalid JSON or error Fix: Check backend script logs: logread | grep secubox

Testing Checklist

Test 1: Verify RPC Backend Available

# On router:
ubus list | grep luci.secubox
# Should show: luci.secubox

ubus -v list luci.secubox
# Should show all methods including:
# - get_catalog_sources
# - check_updates
# - get_appstore_apps

Test 2: Test RPC Methods Directly

# Test getCatalogSources
ubus call luci.secubox get_catalog_sources
# Expected: {"sources":[...]}

# Test checkUpdates
ubus call luci.secubox check_updates
# Expected: {"updates":[...],"total_updates":N}

# Test getApps
ubus call luci.secubox get_appstore_apps
# Expected: {"apps":[...],"categories":{...}}

Test 3: Check RPCD Logs

# Watch RPCD logs while accessing WebUI
logread -f | grep -E "(rpcd|luci.secubox)"

# Or check recent logs
logread | grep luci.secubox | tail -20

Test 4: Verify File Permissions

# Check RPCD script is executable
ls -la /usr/libexec/rpcd/luci.secubox
# Should be: -rwxr-xr-x

# Check catalog exists and readable
ls -la /usr/share/secubox/catalog.json
# Should be: -rw-r--r--

# Check UCI config exists
ls -la /etc/config/secubox-appstore
# Should exist

Common Issues & Solutions

Issue 1: "method not found" in console

Debug Output:

[API-DEBUG] Error: get_catalog_sources error: Error: method not found

Solution:

# Redeploy secubox-core
opkg remove secubox-core
opkg install /tmp/secubox-core_0.8.0-8_all.ipk

# Restart RPCD
/etc/init.d/rpcd restart

# Verify method available
ubus list | grep luci.secubox

Issue 2: Empty sources array

Debug Output:

[CATALOG-SOURCES-DEBUG] getCatalogSources() sources: []

Solution:

# Check UCI config exists
cat /etc/config/secubox-appstore

# If missing, reinstall secubox-core or create manually
# See /etc/config/secubox-appstore template

Issue 3: RPC call hangs/times out

Debug Output:

[API-DEBUG] Calling: checkUpdates with args: []
(... no response ...)

Solution:

# Check if backend script has execution errors
/usr/sbin/secubox-appstore check-updates --json
# If fails, check script syntax/permissions

# Check opkg lock
ls -la /var/lock/opkg.lock
# If exists and process not running, remove it

Issue 4: Apps array is empty

Debug Output:

[APPS-DEBUG] getApps() apps: []

Solution:

# Check catalog file
ls -la /usr/share/secubox/catalog.json
cat /usr/share/secubox/catalog.json | jq '.plugins | length'
# Should show: 37

# Test direct RPCD call
ubus call luci.secubox get_appstore_apps
# Check if returns apps

Debug Information to Collect

When reporting issues, provide:

1. Console Logs:

   • Filter by DEBUG
   • Copy all debug output from page load
   • Include both successful and error messages

2. RPCD Test Results:

   ubus list | grep luci.secubox
   ubus call luci.secubox get_catalog_sources
   ubus call luci.secubox check_updates
   ubus call luci.secubox get_appstore_apps
   

3. System Logs:

   logread | grep -E "(secubox|rpcd)" | tail -50
   

4. Package Versions:

   opkg list-installed | grep secubox
   

5. File Permissions:

   ls -la /usr/libexec/rpcd/luci.secubox
   ls -la /usr/share/secubox/catalog.json
   ls -la /etc/config/secubox-appstore
   

Package Updates

Debug logging added in:

• luci-app-secubox-admin: v1.0.0-14
• secubox-core: v0.8.0-8 (catalog enrichment)

To get debug logging:

# Rebuild packages
cd secubox-tools
./local-build.sh luci-app-secubox-admin
./local-build.sh secubox-core

# Deploy to router
scp build/x86-64/luci-app-secubox-admin_1.0.0-14_all.ipk root@router:/tmp/
scp build/x86-64/secubox-core_0.8.0-8_all.ipk root@router:/tmp/

ssh root@router
opkg remove luci-app-secubox-admin secubox-core
opkg install /tmp/secubox-core_0.8.0-8_all.ipk
opkg install /tmp/luci-app-secubox-admin_1.0.0-14_all.ipk
/etc/init.d/rpcd restart

Next Steps

With debug logging in place:

1. Access WebUI views in browser
2. Open console (F12)
3. Filter for DEBUG messages
4. Navigate to problematic view
5. Capture console output
6. Compare with expected CLI behavior
7. Identify where WebUI differs from CLI

This will pinpoint exactly where the issue occurs (RPC call, data parsing, rendering, etc.).