From a96899c5202c543d7d4128eeba209ba6aba214ec Mon Sep 17 00:00:00 2001 From: CyberMind-FR Date: Wed, 28 Jan 2026 06:46:26 +0100 Subject: [PATCH] docs(haproxy): Add comprehensive README with ACME webroot documentation Documents: - ACME webroot mode architecture (zero-downtime certs) - Certificate management commands - UCI configuration options - Virtual host and backend setup - CLI reference - Troubleshooting guide - File locations Co-Authored-By: Claude Opus 4.5 --- package/secubox/secubox-app-haproxy/README.md | 192 ++++++++++++++++++ 1 file changed, 192 insertions(+) create mode 100644 package/secubox/secubox-app-haproxy/README.md diff --git a/package/secubox/secubox-app-haproxy/README.md b/package/secubox/secubox-app-haproxy/README.md new file mode 100644 index 00000000..1cc282ec --- /dev/null +++ b/package/secubox/secubox-app-haproxy/README.md @@ -0,0 +1,192 @@ +# SecuBox HAProxy App + +HAProxy reverse proxy with automatic SSL/TLS certificate management via ACME (Let's Encrypt). + +## Features + +- **LXC Container Isolation** - HAProxy runs in isolated container +- **Automatic HTTPS** - ACME certificate issuance and renewal +- **Zero-Downtime Certificates** - Webroot mode keeps HAProxy running during issuance +- **Virtual Hosts** - Multiple domains with automatic routing +- **Load Balancing** - Round-robin, least connections, source IP +- **Health Checks** - Automatic backend health monitoring +- **Stats Dashboard** - Real-time statistics on port 8404 + +## Certificate Management + +### ACME Webroot Mode (Zero Downtime) + +HAProxy handles ACME challenges internally - no restart required: + +``` +Internet → Port 80 → HAProxy + │ + ├─ /.well-known/acme-challenge/ + │ ↓ + │ acme_challenge backend (:8402) + │ ↓ + │ busybox httpd serves challenge files + │ + └─ Other paths → normal backends +``` + +### Request a Certificate + +```bash +# Production certificate (trusted by browsers) +haproxyctl cert add example.com + +# Staging certificate (for testing, not trusted) +uci set haproxy.acme.staging='1' +uci commit haproxy +haproxyctl cert add example.com +``` + +### Prerequisites for ACME + +1. **DNS** - Domain must point to your server's public IP +2. **Port 80** - Must be accessible from internet (firewall/NAT) +3. **Email** - Configure in LuCI > Services > HAProxy > Settings + +### Certificate Commands + +```bash +haproxyctl cert list # List installed certificates +haproxyctl cert add # Request new certificate +haproxyctl cert renew [domain] # Renew certificate(s) +haproxyctl cert remove # Remove certificate +haproxyctl cert import # Import existing cert +``` + +## Configuration + +### UCI Options + +```bash +# Main settings +uci set haproxy.main.enabled='1' +uci set haproxy.main.http_port='80' +uci set haproxy.main.https_port='443' +uci set haproxy.main.stats_port='8404' + +# ACME settings +uci set haproxy.acme.email='admin@example.com' +uci set haproxy.acme.staging='0' # 0=production, 1=staging +uci set haproxy.acme.key_type='ec-256' # ec-256, ec-384, rsa-2048, rsa-4096 + +uci commit haproxy +``` + +### Create a Virtual Host + +```bash +# Via CLI +haproxyctl vhost add example.com mybackend --ssl --acme + +# Via UCI +uci set haproxy.example=vhost +uci set haproxy.example.domain='example.com' +uci set haproxy.example.backend='mybackend' +uci set haproxy.example.ssl='1' +uci set haproxy.example.ssl_redirect='1' +uci set haproxy.example.acme='1' +uci set haproxy.example.enabled='1' +uci commit haproxy +haproxyctl generate && haproxyctl reload +``` + +### Create a Backend + +```bash +# Via CLI +haproxyctl backend add myapp --server 192.168.1.100:8080 + +# Via UCI +uci set haproxy.myapp=backend +uci set haproxy.myapp.name='myapp' +uci set haproxy.myapp.mode='http' +uci set haproxy.myapp.balance='roundrobin' +uci set haproxy.myapp.enabled='1' + +uci set haproxy.myapp_srv1=server +uci set haproxy.myapp_srv1.backend='myapp' +uci set haproxy.myapp_srv1.address='192.168.1.100' +uci set haproxy.myapp_srv1.port='8080' +uci set haproxy.myapp_srv1.check='1' +uci commit haproxy +``` + +## CLI Reference + +```bash +haproxyctl status # Show status +haproxyctl start # Start HAProxy +haproxyctl stop # Stop HAProxy +haproxyctl restart # Restart HAProxy +haproxyctl reload # Reload configuration +haproxyctl generate # Regenerate config file +haproxyctl validate # Validate configuration + +haproxyctl vhost list # List virtual hosts +haproxyctl backend list # List backends +haproxyctl cert list # List certificates +haproxyctl stats # Show runtime statistics +``` + +## Troubleshooting + +### Certificate Issuance Fails + +1. **Check DNS resolution:** + ```bash + nslookup example.com + ``` + +2. **Verify port 80 is accessible:** + ```bash + # From external server + curl -I http://example.com/.well-known/acme-challenge/test + ``` + +3. **Check HAProxy is running:** + ```bash + haproxyctl status + ``` + +4. **Review logs:** + ```bash + logread | grep -i acme + logread | grep -i haproxy + ``` + +### HAProxy Won't Start + +1. **Validate configuration:** + ```bash + haproxyctl validate + ``` + +2. **Check certificate files:** + ```bash + ls -la /srv/haproxy/certs/ + ``` + +3. **Review container logs:** + ```bash + lxc-attach -n haproxy -- cat /var/log/haproxy.log + ``` + +## File Locations + +| Path | Description | +|------|-------------| +| `/etc/config/haproxy` | UCI configuration | +| `/srv/haproxy/config/haproxy.cfg` | Generated HAProxy config | +| `/srv/haproxy/certs/` | SSL certificates | +| `/etc/acme/` | ACME account and cert data | +| `/var/www/acme-challenge/` | ACME challenge webroot | +| `/srv/lxc/haproxy/` | LXC container rootfs | + +## License + +MIT License - Copyright (C) 2025 CyberMind.fr