secubox-openwrt/package/secubox/luci-app-cdn-cache/README.md

SecuBox CDN Cache

Version: 0.5.0 Status: Active

A caching proxy for SecuBox that reduces bandwidth usage by caching frequently accessed content locally. Built on nginx with intelligent caching policies for different content types.

Features

• Transparent Caching Proxy - Cache HTTP content automatically
• Policy-Based Caching - Different rules for Windows updates, Linux repos, Android apps, Steam games
• Bandwidth Savings - Reduce repeated downloads across all LAN clients
• Cache Management - Purge by domain, expire old content, preload URLs
• Real-time Statistics - Hit ratio, bandwidth saved, top cached domains
• LuCI Dashboard - Full web interface for configuration and monitoring

Architecture

LAN Clients
     |
     v
[CDN Cache Proxy :3128]  <-- nginx caching proxy
     |
     v
  Internet

Quick Start

# Enable and start
uci set cdn-cache.main.enabled=1
uci commit cdn-cache
/etc/init.d/cdn-cache start

# Configure clients to use proxy: 192.168.255.1:3128

Configuration

UCI Configuration

/etc/config/cdn-cache

config cdn_cache 'main'
    option enabled '1'
    option cache_dir '/var/cache/cdn'
    option cache_size '1024'          # Max cache size in MB
    option max_object_size '512'      # Max single object size in MB
    option cache_valid '1440'         # Default cache validity in minutes
    option listen_port '3128'         # Proxy listen port
    option transparent '0'            # Transparent proxy mode
    option log_level 'warn'

# Cache policies for specific content types
config cache_policy 'windows_update'
    option name 'Windows Update'
    option domains 'windowsupdate.com download.microsoft.com'
    option extensions 'exe msu cab msi'
    option cache_time '10080'         # 7 days
    option max_size '2048'
    option priority '10'

config cache_policy 'linux_repos'
    option name 'Linux Repositories'
    option domains 'archive.ubuntu.com deb.debian.org mirrors.kernel.org'
    option extensions 'deb rpm pkg.tar.zst'
    option cache_time '4320'          # 3 days
    option max_size '1024'
    option priority '10'

# Exclusions (never cache)
config exclusion 'banking'
    option name 'Banking Sites'
    option domains 'bank.com paypal.com'
    option reason 'Security sensitive'

Client Configuration

Manual Proxy

Set HTTP proxy on client devices:

• Proxy Address: 192.168.255.1
• Proxy Port: 3128

Transparent Mode

Enable transparent mode to automatically redirect HTTP traffic:

uci set cdn-cache.main.transparent=1
uci commit cdn-cache
/etc/init.d/cdn-cache restart

RPCD API

Status & Statistics

Method	Parameters	Description
status	-	Service status, cache info, uptime
stats	-	Hit/miss counts, bandwidth saved
cache_list	-	List cached items (top 100)
top_domains	-	Domains ranked by cache usage
cache_size	-	Used/max/free cache space
bandwidth_savings	period	Savings over time (24h/7d/30d)
hit_ratio	period	Hit ratio over time
logs	count	Recent log entries

Cache Management

Method	Parameters	Description
purge_cache	-	Clear entire cache
purge_domain	domain	Clear cache for specific domain
purge_expired	-	Remove expired entries
preload_url	url	Fetch and cache a URL
clear_stats	-	Reset statistics

Configuration

Method	Parameters	Description
set_enabled	enabled	Enable/disable service
policies	-	List cache policies
add_policy	name, domains, extensions, cache_time, max_size	Create policy
remove_policy	id	Delete policy
exclusions	-	List exclusions
add_exclusion	name, domains, reason	Create exclusion
remove_exclusion	id	Delete exclusion
set_limits	max_size_mb, cache_valid	Set cache limits
restart	-	Restart service

Examples

# Check status
ubus call luci.cdn-cache status

# Get statistics
ubus call luci.cdn-cache stats

# Purge cache for a domain
ubus call luci.cdn-cache purge_domain '{"domain":"example.com"}'

# Add a custom policy
ubus call luci.cdn-cache add_policy '{
  "name": "Game Updates",
  "domains": "cdn.steampowered.com epicgames.com",
  "extensions": "pak bundle",
  "cache_time": 10080,
  "max_size": 4096
}'

# Set cache limits (2GB, 48h validity)
ubus call luci.cdn-cache set_limits '{"max_size_mb": 2048, "cache_valid": 2880}'

Nginx Cache Configuration

The service generates nginx configuration at /var/etc/cdn-cache-nginx.conf:

• Cache Zone: 64MB keys zone, configurable max size
• Cache Levels: 2-level directory structure for performance
• Stale Content: Serves stale on upstream errors (500, 502, 503, 504)
• Cache Lock: Prevents thundering herd on cache miss
• Health Check: /cdn-cache-health endpoint

Response Headers

Cached responses include:

• X-Cache-Status: HIT, MISS, EXPIRED, STALE, UPDATING
• X-Cache-Date: Original response date

Default Cache Policies

Policy	Domains	Extensions	Duration
Windows Update	windowsupdate.com, download.microsoft.com	exe, msu, cab, msi	7 days
Linux Repos	archive.ubuntu.com, deb.debian.org	deb, rpm, pkg.tar.zst	3 days
Android Apps	play.googleapis.com	apk, obb	7 days
Steam Games	steamcontent.com	-	7 days
Static Content	*	js, css, png, jpg, woff	1 day

Files

File	Description
/etc/config/cdn-cache	UCI configuration
/etc/init.d/cdn-cache	Init script
/var/etc/cdn-cache-nginx.conf	Generated nginx config
/var/cache/cdn/	Cache storage directory
/var/run/cdn-cache.pid	PID file
/var/run/cdn-cache-stats.json	Statistics file
/var/log/cdn-cache/access.log	Access log
/var/log/cdn-cache/error.log	Error log
/usr/libexec/rpcd/luci.cdn-cache	RPCD backend

Troubleshooting

Service won't start

# Check nginx syntax
nginx -t -c /var/etc/cdn-cache-nginx.conf

# Check error log
cat /var/log/cdn-cache/error.log

Cache not working

# Verify proxy is listening
netstat -tlnp | grep 3128

# Test with curl
curl -x http://192.168.255.1:3128 http://example.com -I

# Check cache status header
curl -x http://192.168.255.1:3128 http://example.com -I | grep X-Cache

Check cache contents

# List cached files
ls -la /var/cache/cdn/

# Cache size
du -sh /var/cache/cdn/

Clear all cache

ubus call luci.cdn-cache purge_cache
# or manually
rm -rf /var/cache/cdn/*
/etc/init.d/cdn-cache restart

Performance

With optimal configuration:

• Hit Ratio: 60-80% typical for repeated content
• Bandwidth Savings: 40-60% reduction
• Latency: < 1ms for cache hits

Dependencies

• nginx-full - Nginx with proxy and cache modules
• luci-base - LuCI framework
• rpcd - RPC daemon

Package Structure

luci-app-cdn-cache/
├── Makefile
├── README.md
├── htdocs/luci-static/resources/
│   ├── view/cdn-cache/
│   │   ├── overview.js        # Main dashboard
│   │   ├── cache.js           # Cache management
│   │   ├── policies.js        # Policy configuration
│   │   ├── statistics.js      # Statistics graphs
│   │   ├── maintenance.js     # Maintenance tools
│   │   └── settings.js        # Settings
│   └── cdn-cache/
│       ├── api.js             # RPC API client
│       └── dashboard.css      # Styles
└── root/
    ├── etc/
    │   ├── config/cdn-cache   # UCI defaults
    │   └── init.d/cdn-cache   # Init script
    └── usr/
        ├── libexec/rpcd/luci.cdn-cache  # RPCD backend
        └── share/
            ├── luci/menu.d/   # LuCI menu
            └── rpcd/acl.d/    # ACL permissions

License

Apache-2.0 - CyberMind.fr