From 50ffb4fe16072e80fe2dd64e10333dc62c838ede Mon Sep 17 00:00:00 2001 From: Joao Gilberto Magalhaes Date: Tue, 2 Dec 2025 11:47:19 -0500 Subject: [PATCH] Add environment variable documentation for all plugins, reorganize plugin files for consistency - Introduced environment variable support in documentation for Cloudflare, Cleanup, Deny Pages, IP Whitelist, JWT Validator, and FastCGI plugins. - Updated plugin files with consistent headings, examples, and tables for easier configuration reference. - Adjusted `README.md` and `plugins.md` to reflect updated plugin paths and environment variable usage. --- README.md | 12 ++--- docs/{plugins => Plugins}/cleanup.md | 14 ++++-- docs/{plugins => Plugins}/cloudflare.md | 12 +++++ docs/{plugins => Plugins}/deny-pages.md | 12 +++++ docs/{plugins => Plugins}/fastcgi.md | 14 ++++++ docs/{plugins => Plugins}/ip-whitelist.md | 12 +++++ docs/{plugins => Plugins}/jwt-validator.md | 18 +++++++ docs/plugins.md | 57 ++++++++++++++-------- 8 files changed, 122 insertions(+), 29 deletions(-) rename docs/{plugins => Plugins}/cleanup.md (65%) rename docs/{plugins => Plugins}/cloudflare.md (77%) rename docs/{plugins => Plugins}/deny-pages.md (77%) rename docs/{plugins => Plugins}/fastcgi.md (79%) rename docs/{plugins => Plugins}/ip-whitelist.md (76%) rename docs/{plugins => Plugins}/jwt-validator.md (87%) diff --git a/README.md b/README.md index 76bcb35..b0122b5 100644 --- a/README.md +++ b/README.md @@ -89,12 +89,12 @@ Detailed configuration guides for advanced setups: - [Environment Variables](docs/environment-variable.md) - Configure EasyHAProxy behavior - [Volumes](docs/volumes.md) - Map volumes for certificates, config, and custom files - [Plugins](docs/plugins.md) - Extend HAProxy with plugins ([Development Guide](docs/plugin-development.md)) - - [Cloudflare](docs/plugins/cloudflare.md) - Restore visitor IP from Cloudflare CDN - - [Cleanup](docs/plugins/cleanup.md) - Automatic cleanup of temporary files - - [Deny Pages](docs/plugins/deny-pages.md) - Block access to specific paths - - [IP Whitelist](docs/plugins/ip-whitelist.md) - Restrict access to IPs/CIDR ranges - - [JWT Validator](docs/plugins/jwt-validator.md) - JWT authentication validation - - [FastCGI](docs/plugins/fastcgi.md) - PHP-FPM and FastCGI application support + - [JWT Validator](docs/Plugins/jwt-validator.md) - JWT authentication validation + - [FastCGI](docs/Plugins/fastcgi.md) - PHP-FPM and FastCGI application support + - [Cloudflare](docs/Plugins/cloudflare.md) - Restore visitor IP from Cloudflare CDN + - [IP Whitelist](docs/Plugins/ip-whitelist.md) - Restrict access to IPs/CIDR ranges + - [Deny Pages](docs/Plugins/deny-pages.md) - Block access to specific paths + - [Cleanup](docs/Plugins/cleanup.md) - Automatic cleanup of temporary files - [Other Configurations](docs/other.md) - Additional configurations (ports, custom errors, etc.) - [Limitations](docs/limitations.md) - Important limitations and considerations diff --git a/docs/plugins/cleanup.md b/docs/Plugins/cleanup.md similarity index 65% rename from docs/plugins/cleanup.md rename to docs/Plugins/cleanup.md index fcef7b2..76ac12d 100644 --- a/docs/plugins/cleanup.md +++ b/docs/Plugins/cleanup.md @@ -39,10 +39,16 @@ plugins: ### Environment Variables -```bash -EASYHAPROXY_PLUGINS_ENABLED=cleanup -EASYHAPROXY_PLUGIN_CLEANUP_MAX_IDLE_TIME=600 -``` +Configure the Cleanup plugin globally: + +| Environment Variable | Config Key | Type | Default | Description | +|-------------------------------------------------|----------------------|----------|---------|----------------------------------------------| +| `EASYHAPROXY_PLUGINS_ENABLED` | - | string | - | Enable cleanup plugin (value: `cleanup`) | +| `EASYHAPROXY_PLUGIN_CLEANUP_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin | +| `EASYHAPROXY_PLUGIN_CLEANUP_MAX_IDLE_TIME` | `max_idle_time` | integer | `300` | Maximum age in seconds before deleting files | +| `EASYHAPROXY_PLUGIN_CLEANUP_CLEANUP_TEMP_FILES` | `cleanup_temp_files` | boolean | `true` | Enable temp file cleanup | + +**Note:** This is a global plugin - configuration applies to the entire system. ### Custom Idle Time (1 hour) diff --git a/docs/plugins/cloudflare.md b/docs/Plugins/cloudflare.md similarity index 77% rename from docs/plugins/cloudflare.md rename to docs/Plugins/cloudflare.md index 301e9ed..ff6bf66 100644 --- a/docs/plugins/cloudflare.md +++ b/docs/Plugins/cloudflare.md @@ -80,6 +80,18 @@ plugins: use_builtin_ips: true # Uses built-in Cloudflare IPs (default) ``` +### Environment Variables + +Configure Cloudflare plugin defaults for all domains: + +| Environment Variable | Config Key | Type | Default | Description | +|-------------------------------------------------|-------------------|----------|-----------------------------------|---------------------------------------| +| `EASYHAPROXY_PLUGIN_CLOUDFLARE_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin for all domains | +| `EASYHAPROXY_PLUGIN_CLOUDFLARE_USE_BUILTIN_IPS` | `use_builtin_ips` | boolean | `true` | Use built-in Cloudflare IP ranges | +| `EASYHAPROXY_PLUGIN_CLOUDFLARE_IP_LIST_PATH` | `ip_list_path` | string | `/etc/haproxy/cloudflare_ips.lst` | Path to Cloudflare IP list file | + +**Note:** Environment variables set defaults for ALL domains. To enable/disable per-domain, use container labels or Kubernetes annotations. + ## Generated HAProxy Configuration ```haproxy diff --git a/docs/plugins/deny-pages.md b/docs/Plugins/deny-pages.md similarity index 77% rename from docs/plugins/deny-pages.md rename to docs/Plugins/deny-pages.md index 3bea22f..0d7cff8 100644 --- a/docs/plugins/deny-pages.md +++ b/docs/Plugins/deny-pages.md @@ -96,6 +96,18 @@ labels: easyhaproxy.http.plugin.deny_pages.status_code: 403 ``` +### Environment Variables + +Configure Deny Pages plugin defaults for all domains: + +| Environment Variable | Config Key | Type | Default | Description | +|---------------------------------------------|---------------|---------|---------|----------------------------------------| +| `EASYHAPROXY_PLUGIN_DENY_PAGES_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin for all domains | +| `EASYHAPROXY_PLUGIN_DENY_PAGES_PATHS` | `paths` | string | - | Comma-separated list of paths to block | +| `EASYHAPROXY_PLUGIN_DENY_PAGES_STATUS_CODE` | `status_code` | integer | `403` | HTTP status code to return | + +**Note:** Environment variables set defaults for ALL domains. To configure per-domain, use container labels or Kubernetes annotations. + ## Generated HAProxy Configuration ```haproxy diff --git a/docs/plugins/fastcgi.md b/docs/Plugins/fastcgi.md similarity index 79% rename from docs/plugins/fastcgi.md rename to docs/Plugins/fastcgi.md index ab836bc..aa1316d 100644 --- a/docs/plugins/fastcgi.md +++ b/docs/Plugins/fastcgi.md @@ -115,6 +115,20 @@ easymapping: path_info: true ``` +### Environment Variables + +Configure FastCGI plugin defaults for all domains: + +| Environment Variable | Config Key | Type | Default | Description | +|----------------------------------------------|-------------------|----------|-----------------|---------------------------------------| +| `EASYHAPROXY_PLUGIN_FASTCGI_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin for all domains | +| `EASYHAPROXY_PLUGIN_FASTCGI_DOCUMENT_ROOT` | `document_root` | string | `/var/www/html` | Document root path | +| `EASYHAPROXY_PLUGIN_FASTCGI_SCRIPT_FILENAME` | `script_filename` | string | `%[path]` | Custom pattern for SCRIPT_FILENAME | +| `EASYHAPROXY_PLUGIN_FASTCGI_INDEX_FILE` | `index_file` | string | `index.php` | Default index file | +| `EASYHAPROXY_PLUGIN_FASTCGI_PATH_INFO` | `path_info` | boolean | `true` | Enable PATH_INFO support | + +**Note:** Environment variables set defaults for ALL domains. To configure per-domain, use container labels or Kubernetes annotations. Custom params (`custom_params`) cannot be configured via environment variables - use YAML or labels instead. + ## Generated HAProxy Configuration The plugin generates a top-level `fcgi-app` section and a `use-fcgi-app` directive in the backend: diff --git a/docs/plugins/ip-whitelist.md b/docs/Plugins/ip-whitelist.md similarity index 76% rename from docs/plugins/ip-whitelist.md rename to docs/Plugins/ip-whitelist.md index fd0a297..0cc6132 100644 --- a/docs/plugins/ip-whitelist.md +++ b/docs/Plugins/ip-whitelist.md @@ -85,6 +85,18 @@ easymapping: status_code: 403 ``` +### Environment Variables + +Configure IP Whitelist plugin defaults for all domains: + +| Environment Variable | Config Key | Type | Default | Description | +|-----------------------------------------------|---------------|----------|---------|--------------------------------------------------| +| `EASYHAPROXY_PLUGIN_IP_WHITELIST_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin for all domains | +| `EASYHAPROXY_PLUGIN_IP_WHITELIST_ALLOWED_IPS` | `allowed_ips` | string | - | Comma-separated list of IPs/CIDR ranges to allow | +| `EASYHAPROXY_PLUGIN_IP_WHITELIST_STATUS_CODE` | `status_code` | integer | `403` | HTTP status code to return for blocked IPs | + +**Note:** Environment variables set defaults for ALL domains. To configure per-domain, use container labels or Kubernetes annotations. + ## Generated HAProxy Configuration ```haproxy diff --git a/docs/plugins/jwt-validator.md b/docs/Plugins/jwt-validator.md similarity index 87% rename from docs/plugins/jwt-validator.md rename to docs/Plugins/jwt-validator.md index 27eec2e..28fb53b 100644 --- a/docs/plugins/jwt-validator.md +++ b/docs/Plugins/jwt-validator.md @@ -157,6 +157,24 @@ easymapping: pubkey_path: /etc/haproxy/jwt_keys/api_pubkey.pem ``` +### Environment Variables + +Configure JWT Validator plugin defaults for all domains: + +| Environment Variable | Config Key | Type | Default | Description | +|----------------------------------------------------|-------------------|---------|---------|---------------------------------------------| +| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ENABLED` | `enabled` | boolean | `true` | Enable/disable plugin for all domains | +| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ALGORITHM` | `algorithm` | string | `RS256` | JWT signing algorithm | +| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ISSUER` | `issuer` | string | - | Expected JWT issuer (optional) | +| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_AUDIENCE` | `audience` | string | - | Expected JWT audience (optional) | +| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PUBKEY_PATH` | `pubkey_path` | string | - | Path to public key file | +| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PUBKEY` | `pubkey` | string | - | Public key as base64-encoded string | +| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_PATHS` | `paths` | string | - | Comma-separated paths requiring JWT | +| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ONLY_PATHS` | `only_paths` | boolean | `false` | If true, only specified paths accessible | +| `EASYHAPROXY_PLUGIN_JWT_VALIDATOR_ALLOW_ANONYMOUS` | `allow_anonymous` | boolean | `false` | Allow requests without Authorization header | + +**Note:** Environment variables set defaults for ALL domains. To configure per-domain, use container labels or Kubernetes annotations. + ## Generated HAProxy Configuration ### All Paths Protected diff --git a/docs/plugins.md b/docs/plugins.md index 86d1e1b..3feedfd 100644 --- a/docs/plugins.md +++ b/docs/plugins.md @@ -44,12 +44,12 @@ Execute **once for each discovered domain/host**. EasyHAProxy includes several built-in plugins ready to use: -- [Cloudflare](plugins/cloudflare.md) - Restore visitor IP from Cloudflare CDN -- [Cleanup](plugins/cleanup.md) - Cleanup temporary files -- [Deny Pages](plugins/deny-pages.md) - Block specific paths -- [IP Whitelist](plugins/ip-whitelist.md) - Restrict access to IPs/CIDR ranges -- [JWT Validator](plugins/jwt-validator.md) - Validate JWT tokens -- [FastCGI](plugins/fastcgi.md) - Configure PHP-FPM and FastCGI applications +- [Cloudflare](Plugins/cloudflare.md) - Restore visitor IP from Cloudflare CDN +- [Cleanup](Plugins/cleanup.md) - Cleanup temporary files +- [Deny Pages](Plugins/deny-pages.md) - Block specific paths +- [IP Whitelist](Plugins/ip-whitelist.md) - Restrict access to IPs/CIDR ranges +- [JWT Validator](Plugins/jwt-validator.md) - Validate JWT tokens +- [FastCGI](Plugins/fastcgi.md) - Configure PHP-FPM and FastCGI applications ## Configuration Methods @@ -124,49 +124,68 @@ services: ### 3. Static YAML Configuration -Configure plugins globally in `/etc/haproxy/static/config.yaml`: +Configure plugins in `/etc/haproxy/static/config.yaml`: ```yaml plugins: # Global settings abort_on_error: false # Log and continue on errors (recommended) - # Enable global plugins + # Enable GLOBAL plugins (run once per discovery cycle) enabled: [cleanup] - # Configure individual plugins + # Configure plugins (both global and domain plugins) config: - cloudflare: - enabled: true - ip_list_path: /etc/haproxy/cloudflare_ips.lst - + # Global plugin configuration (cleanup runs once per cycle) cleanup: enabled: true max_idle_time: 600 + # Domain plugin configuration (applies to ALL domains by default) + cloudflare: + enabled: true # Apply to all domains + use_builtin_ips: true # Use built-in Cloudflare IPs + + # Domain plugin disabled by default (enable per-domain via labels/annotations) deny_pages: - enabled: false # Disable globally, enable per-container via labels + enabled: false ``` +**Important distinctions:** + +- **Global plugins** (like `cleanup`): Run once per discovery cycle, configured here only +- **Domain plugins** (like `cloudflare`, `deny_pages`, `jwt_validator`): + - Configuration here sets **defaults for ALL domains** + - Can be enabled/disabled per-domain via container labels or Kubernetes annotations + - Per-domain configuration overrides these defaults + ### 4. Environment Variables -Configure plugins via environment variables: +Configure plugins via environment variables. **Note:** Environment variables set system-wide defaults and cannot configure plugins per-domain. ```bash -# Global settings +# Enable GLOBAL plugins (run once per discovery cycle) EASYHAPROXY_PLUGINS_ENABLED=cleanup EASYHAPROXY_PLUGINS_ABORT_ON_ERROR=false -# Plugin-specific configuration +# Configure GLOBAL plugins EASYHAPROXY_PLUGIN_CLEANUP_ENABLED=true EASYHAPROXY_PLUGIN_CLEANUP_MAX_IDLE_TIME=600 -EASYHAPROXY_PLUGIN_CLOUDFLARE_IP_LIST_PATH=/etc/haproxy/cloudflare_ips.lst + +# Configure DOMAIN plugins (sets defaults for ALL domains) +EASYHAPROXY_PLUGIN_CLOUDFLARE_ENABLED=true +EASYHAPROXY_PLUGIN_CLOUDFLARE_USE_BUILTIN_IPS=true ``` **Variable format:** -- Enable plugins: `EASYHAPROXY_PLUGINS_ENABLED=plugin1,plugin2` +- Enable global plugins: `EASYHAPROXY_PLUGINS_ENABLED=plugin1,plugin2` - Configure plugin: `EASYHAPROXY_PLUGIN__=value` +**Scope limitations:** +- **Global plugins**: Environment variables configure the single instance +- **Domain plugins**: Environment variables set defaults for ALL domains +- **Per-domain configuration**: Use container labels (Docker) or annotations (Kubernetes) instead + ## Common Use Cases ### Protect API with JWT Authentication