--- sidebar_position: 16 --- # Plugins EasyHAProxy supports a flexible plugin system that allows you to extend HAProxy configuration with custom functionality. Plugins are automatically invoked during the discovery cycle and can inject HAProxy configuration directives or modify discovery data. ## Plugin Types ### Global Plugins Global plugins execute **once per discovery cycle**, regardless of how many domains are discovered. They're ideal for: - Cleanup tasks - Global monitoring - DNS updates - Log management ### Domain Plugins Domain plugins execute **once for each discovered domain/host**. They're ideal for: - Domain-specific configuration - IP restoration (e.g., Cloudflare) - Path blocking - Custom headers per domain ## Built-in Plugins ### Cloudflare (Domain Plugin) Restores the original visitor IP address from Cloudflare's `CF-Connecting-IP` header when requests come through Cloudflare's CDN. **Configuration:** ```yaml # /etc/haproxy/static/config.yaml plugins: cloudflare: enabled: true ip_list_path: /etc/haproxy/cloudflare_ips.lst ``` **Container Label:** ```yaml services: myapp: labels: easyhaproxy.http.host: example.com easyhaproxy.http.plugins: cloudflare ``` **Environment Variable:** ```bash EASYHAPROXY_PLUGINS_ENABLED=cloudflare EASYHAPROXY_PLUGIN_CLOUDFLARE_IP_LIST_PATH=/etc/haproxy/cloudflare_ips.lst ``` ### Cleanup (Global Plugin) Performs cleanup tasks during each discovery cycle, such as removing old temporary files. **Configuration:** ```yaml # /etc/haproxy/static/config.yaml plugins: cleanup: enabled: true max_idle_time: 300 # seconds cleanup_temp_files: true ``` **Environment Variable:** ```bash EASYHAPROXY_PLUGINS_ENABLED=cleanup EASYHAPROXY_PLUGIN_CLEANUP_MAX_IDLE_TIME=600 ``` ### Deny Pages (Domain Plugin) Blocks access to specific paths for a domain. **Configuration:** ```yaml # /etc/haproxy/static/config.yaml plugins: deny_pages: enabled: true paths: /admin,/private,/internal status_code: 403 ``` **Container Label:** ```yaml services: myapp: labels: easyhaproxy.http.host: example.com easyhaproxy.http.plugins: deny_pages easyhaproxy.http.plugin.deny_pages.paths: /admin,/private easyhaproxy.http.plugin.deny_pages.status_code: 403 ``` ## Configuration Methods Plugins can be configured using three methods. Configuration from YAML takes precedence over environment variables. ### 1. Static YAML Configuration Configure plugins in `/etc/haproxy/static/config.yaml`: ```yaml plugins: # Global settings abort_on_error: false # Log and continue on plugin errors (default) # Plugin-specific configuration cloudflare: enabled: true ip_list_path: /etc/haproxy/cloudflare_ips.lst cleanup: enabled: true max_idle_time: 300 deny_pages: enabled: false # Disable globally, can still be enabled per domain ``` ### 2. Environment Variables Configure plugins via environment variables: ```bash # Global settings EASYHAPROXY_PLUGINS_ABORT_ON_ERROR=false EASYHAPROXY_PLUGINS_ENABLED=cloudflare,cleanup # Plugin-specific configuration EASYHAPROXY_PLUGIN_CLOUDFLARE_ENABLED=true EASYHAPROXY_PLUGIN_CLOUDFLARE_IP_LIST_PATH=/etc/haproxy/cloudflare_ips.lst EASYHAPROXY_PLUGIN_CLEANUP_MAX_IDLE_TIME=600 ``` ### 3. Container Labels (Domain Plugins Only) Enable domain plugins for specific containers: ```yaml services: webapp: image: myapp:latest labels: easyhaproxy.http.host: example.com easyhaproxy.http.plugins: cloudflare,deny_pages easyhaproxy.http.plugin.deny_pages.paths: /admin,/api/internal ``` ## Error Handling ### Log and Continue (Default) By default, plugin errors are logged as warnings and the discovery cycle continues: ```yaml plugins: abort_on_error: false # Default ``` This ensures that a failing plugin doesn't prevent HAProxy configuration updates. ### Abort on Error For critical plugins, you can stop the discovery cycle on errors: ```yaml plugins: abort_on_error: true ``` With this setting, any plugin error will halt configuration generation and the previous HAProxy config remains active until the issue is resolved. ## Custom Plugins You can create custom plugins by placing Python files in `/etc/haproxy/plugins/`. ### Simple Custom Plugin Example Create `/etc/haproxy/plugins/custom_header.py`: ```python import os import sys sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) from plugins import PluginInterface, PluginType, PluginContext, PluginResult class CustomHeaderPlugin(PluginInterface): def __init__(self): self.enabled = True self.header_name = "X-Custom-App" self.header_value = "EasyHAProxy" @property def name(self) -> str: return "custom_header" @property def plugin_type(self) -> PluginType: return PluginType.DOMAIN def configure(self, config: dict) -> None: if "enabled" in config: self.enabled = str(config["enabled"]).lower() in ["true", "1", "yes"] if "header_name" in config: self.header_name = config["header_name"] if "header_value" in config: self.header_value = config["header_value"] def process(self, context: PluginContext) -> PluginResult: if not self.enabled: return PluginResult() haproxy_config = f'http-request set-header {self.header_name} "{self.header_value}"' return PluginResult( haproxy_config=haproxy_config, metadata={"domain": context.domain} ) ``` ### Enable Your Custom Plugin **YAML:** ```yaml plugins: custom_header: enabled: true header_name: X-My-Header header_value: MyValue ``` **Container Label:** ```yaml labels: easyhaproxy.http.plugins: custom_header easyhaproxy.http.plugin.custom_header.header_value: CustomValue ``` ## Plugin Development For detailed information on developing plugins, see the [Plugin Developer Guide](plugin-development.md). Key points: - Plugins must inherit from `PluginInterface` - Implement required methods: `name`, `plugin_type`, `configure`, `process` - Return `PluginResult` with HAProxy config snippets - Use `loggerEasyHaproxy` for logging - Handle errors gracefully ## Use Cases ### 1. Cloudflare IP Restoration Restore original visitor IPs when using Cloudflare: ```yaml plugins: cloudflare: enabled: true ``` Requires Cloudflare IP list at `/etc/haproxy/cloudflare_ips.lst`. See [Cloudflare documentation](https://support.cloudflare.com/hc/en-us/articles/200170786-Restoring-original-visitor-IPs). ### 2. Path Protection Block sensitive paths from public access: ```yaml labels: easyhaproxy.http.host: myapp.com easyhaproxy.http.plugins: deny_pages easyhaproxy.http.plugin.deny_pages.paths: /admin,/config,/debug ``` ### 3. Automatic Cleanup Keep your system clean: ```yaml plugins: cleanup: enabled: true max_idle_time: 3600 # 1 hour ``` ### 4. Custom Authentication Create a plugin to add basic auth: ```python def process(self, context: PluginContext) -> PluginResult: return PluginResult( haproxy_config="""http-request auth realm MyApp unless { http_auth(user_list) }""" ) ``` ## Debugging Enable debug logging to see plugin execution: ```bash EASYHAPROXY_LOG_LEVEL=DEBUG ``` Look for log messages: ``` INFO: Loaded builtin plugin: cloudflare (domain) DEBUG: Executing domain plugin: cloudflare for domain: example.com DEBUG: Plugin cloudflare metadata: {'domain': 'example.com'} ``` ## Best Practices 1. **Test plugins independently** before deploying to production 2. **Use log-and-continue mode** unless a plugin is critical 3. **Keep plugin logic simple** - one plugin should do one thing well 4. **Document configuration options** in plugin docstrings 5. **Handle errors gracefully** - return empty PluginResult on errors 6. **Use sensible defaults** so plugins work out of the box ## Limitations - Plugins are Python-only (no shell scripts) - Plugins cannot modify the HAProxy template structure - Domain plugins are executed for each domain, so keep them lightweight - Plugin errors in abort mode will halt configuration updates ## Further Reading - [Plugin Developer Guide](plugin-development.md) - [Container Labels](container-labels.md) - [Environment Variables](environment-variable.md) - [Static Configuration](static.md)