gandalf/secubox-openwrt
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(cdn-cache): Comprehensive README with API and troubleshooting

Browse Source 
- Full RPCD API documentation with all methods
- UCI configuration examples
- Client setup instructions (manual proxy and transparent mode)
- Nginx cache configuration details
- Troubleshooting guide
- Default cache policies table

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
CyberMind-FR 2026-01-28 13:44:23 +01:00
parent 70187a7c45
commit 8de5167405
1 changed files with 240 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

349
package/secubox/luci-app-cdn-cache/README.md
View File

@ -1,156 +1,287 @@
# SecuBox CDN Cache Dashboard
# SecuBox CDN Cache
**Version:** 1.0.0
**Last Updated:** 2025-12-28
**Version:** 0.5.0
**Status:** Active
[![OpenWrt](https://img.shields.io/badge/OpenWrt-23.05+-blue.svg)](https://openwrt.org/)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
[![SecuBox](https://img.shields.io/badge/SecuBox-Module-cyan.svg)](https://cybermind.fr/secubox)
Dashboard LuCI pour gérer un proxy cache CDN local sur OpenWrt. Optimisez votre bande passante en cachant le contenu web fréquemment accédé.
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.
![CDN Cache Dashboard](docs/screenshot-overview.png)
## Features
## 🎯 Fonctionnalités
- **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
- **📊 Dashboard temps réel** — Statistiques de hit ratio, économies de bande passante
- **💾 Gestion du cache** — Visualisation des objets en cache, purge sélective
- **📋 Policies configurables** — Règles par domaine, extension, durée
- **📈 Graphiques statistiques** — Évolution du hit ratio et des économies
- **🔧 Maintenance** — Purge, préchargement, logs, redémarrage
- **⚙️ Configuration complète** — Taille cache, port, mode transparent
## Architecture
## 📦 Installation
### Depuis les packages SecuBox
```bash
opkg update
opkg install luci-app-cdn-cache
```
LAN Clients
|
v
[CDN Cache Proxy :3128] <-- nginx caching proxy
|
v
Internet
```
### Compilation manuelle
## Quick Start
```bash
# Cloner dans le SDK OpenWrt
git clone https://github.com/gkerma/luci-app-cdn-cache.git package/luci-app-cdn-cache
# Compiler
make package/luci-app-cdn-cache/compile V=s
```
## 🔧 Configuration
### Via LuCI
1. Accéder à **Services → CDN Cache → Settings**
2. Configurer la taille du cache, le port et les policies
3. Activer le service
### Via UCI
```bash
# Activer le service
# Enable and start
uci set cdn-cache.main.enabled=1
uci set cdn-cache.main.cache_size=2048
uci set cdn-cache.main.listen_port=3128
uci commit cdn-cache
/etc/init.d/cdn-cache start
# Redémarrer
# 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:
```bash
uci set cdn-cache.main.transparent=1
uci commit cdn-cache
/etc/init.d/cdn-cache restart
```
### Configuration client
## RPCD API
Configurez vos appareils pour utiliser le proxy :
### Status & Statistics
```
Proxy HTTP: 192.168.1.1:3128
| 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
```bash
# 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}'
```
Ou utilisez le mode transparent avec des règles iptables.
## Nginx Cache Configuration
## 📊 Policies de Cache
The service generates nginx configuration at `/var/etc/cdn-cache-nginx.conf`:
Les policies définissent quoi cacher et pour combien de temps :
- **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
| Policy | Domaines | Extensions | Durée |
|--------|----------|------------|-------|
| Windows Update | windowsupdate.com, download.microsoft.com | exe, msu, cab | 7 jours |
| Linux Repos | archive.ubuntu.com, deb.debian.org | deb, rpm | 3 jours |
| Static Content | * | js, css, png, jpg, woff | 1 jour |
### Response Headers
## 🚫 Exclusions
Cached responses include:
- `X-Cache-Status`: HIT, MISS, EXPIRED, STALE, UPDATING
- `X-Cache-Date`: Original response date
Certains domaines ne doivent jamais être cachés :
## Default Cache Policies
- **Sites bancaires** — Sécurité
- **Streaming vidéo** — Contenu temps réel
- **APIs dynamiques** — Données changeantes
| 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 |
## 📁 Structure du Package
## 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
```bash
# 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
```bash
# 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
```bash
# List cached files
ls -la /var/cache/cdn/
# Cache size
du -sh /var/cache/cdn/
```
### Clear all cache
```bash
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 # Dashboard principal
│ │ ├── cache.js # Gestion du cache
│ │ ├── policies.js # Configuration policies
│ │ ├── statistics.js # Graphiques stats
│ │ ├── maintenance.js # Outils maintenance
│ │ └── settings.js # Configuration
│ │ ├── 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 # API RPC
│ ├── api.js # RPC API client
│ └── dashboard.css # Styles
└── root/
├── etc/
│ ├── config/cdn-cache # Configuration UCI
│ └── init.d/cdn-cache # Script init
│ ├── config/cdn-cache # UCI defaults
│ └── init.d/cdn-cache # Init script
└── usr/
├── libexec/rpcd/cdn-cache # Backend RPCD
├── libexec/rpcd/luci.cdn-cache # RPCD backend
└── share/
├── luci/menu.d/ # Menu LuCI
└── rpcd/acl.d/ # ACL
├── luci/menu.d/ # LuCI menu
└── rpcd/acl.d/ # ACL permissions
```
## 🔗 API RPCD
## License
| Méthode | Description |
|---------|-------------|
| `status` | État du service |
| `stats` | Statistiques globales |
| `cache_list` | Liste des objets en cache |
| `top_domains` | Top domaines par usage |
| `bandwidth_savings` | Économies de bande passante |
| `purge_cache` | Vider tout le cache |
| `purge_domain` | Vider cache d'un domaine |
| `preload_url` | Précharger une URL |
## 🔧 Dépendances
- `luci-base` — Framework LuCI
- `nginx-ssl` — Serveur proxy
- `rpcd` — Daemon RPC
- `coreutils-stat` — Utilitaires
## 📈 Performances
Avec une configuration optimale :
- **Hit ratio** : 60-80% typique
- **Économies** : 40-60% de bande passante
- **Latence** : < 1ms pour les hits
## 🔗 Liens
- [Documentation](https://cybermind.fr/apps/cdn-cache)
- [SecuBox Project](https://cybermind.fr/secubox)
- [CyberMind.fr](https://cybermind.fr)
## 📄 Licence
Apache-2.0 © 2025 CyberMind.fr
Apache-2.0 - CyberMind.fr