Enhancing Your Pangolin Deployment with Middleware Manager: A Complete Guide
Use Github Repo to open Issues
Please note that this was created for my personal use. I cannot accept responsibility if it affects your working environment. This has been tested with the applications I use and it works flawlessly.
Security Warning: Use Middlewares Responsibly
IMPORTANT: While middlewares can significantly enhance your security posture, they can also introduce serious vulnerabilities if misconfigured. Here are some critical warnings:
- Authentication Leakage: Improper forward authentication configurations can leak credentials or bypass authentication entirely.
- Rate Limiting Bypass: Incorrectly configured rate limiters might be bypassed using various techniques, leaving your services vulnerable to DDoS attacks.
- Header Injection: Poorly configured header middlewares can expose your applications to XSS or CSRF attacks.
- IP Whitelisting Risks: Relying solely on IP whitelisting can create a false sense of security, especially with sophisticated attackers who can spoof IP addresses.
- Testing Is Essential: Always test new middleware configurations in a staging environment before deploying to production.
- Provider Reference Confusion: Mixing up provider references (
@httpvs@file) can lead to middleware chains that don’t apply as expected. - Performance Impact: Stacking too many middlewares can significantly impact performance, especially complex middlewares like authentication.
Always thoroughly understand any middleware before implementing it in production. Take time to read Traefik’s documentation on each middleware type before using it.
Pangolin has revolutionized how we handle tunneled reverse proxies with its elegant approach to identity and access management. But what if you need more advanced security features like rate limiting, IP filtering, or integration with third-party authentication systems? That’s where the Pangolin Middleware Manager comes in – a powerful extension that lets you harness the full capabilities of Traefik middlewares without modifying Pangolin itself.
What is Pangolin Middleware Manager?
Pangolin Middleware Manager is a specialized microservice that seamlessly integrates with your existing Pangolin deployment. It provides a simple web interface to attach additional Traefik middlewares to your resources, enabling advanced functionality that wasn’t previously possible without custom configuration.
With Middleware Manager, you can implement:
- External authentication systems (Authelia, Authentik, JWT)
- Security headers and content security policies
- Geographic IP blocking
- Rate limiting and DDoS protection
- Custom redirect and path manipulation rules
- Integration with security tools like CrowdSec
The real power comes from being able to apply these middlewares to specific resources without disrupting Pangolin’s core functionality.
Prerequisites
Before we begin, make sure you have:
- A working Pangolin deployment (version 1.0.0 or later)
- Docker and Docker Compose
- Basic understanding of Traefik concepts
- Administrative access to your Pangolin server
Deployment Guide
Adding Middleware Manager to your existing Pangolin setup is straightforward. Let’s break it down into simple steps:
Step 1: Update Your Docker Compose File
First, you’ll need to modify your docker-compose.yml file. Here’s what you need to add:
middleware-manager:
image: hhftechnology/middleware-manager:latest
container_name: middleware-manager
restart: unless-stopped
volumes:
- ./data:/data
- ./config/traefik/rules:/conf
- ./config/middleware-manager/templates.yaml:/app/config/templates.yaml # Optional for custom templates
environment:
- PANGOLIN_API_URL=http://pangolin:3001/api/v1
- TRAEFIK_CONF_DIR=/conf
- DB_PATH=/data/middleware.db
- PORT=3456
ports:
- "3456:3456"
Step 2: Create Required Directories
You’ll need to create a directory for Traefik’s dynamic configuration files:
mkdir -p ./config/traefik/rules
mkdir -p ./config/middleware-manager
Then move your dynamic_config.yml in the rules folder
Step 3: Update Traefik Configuration
For the Middleware Manager to work correctly, Traefik needs to load configuration from the /rules directory. Make sure your Traefik service has this volume mounted:
traefik:
# Other configuration...
volumes:
- ./config/traefik:/etc/traefik:ro
- ./config/letsencrypt:/letsencrypt
- ./config/traefik/logs:/var/log/traefik
- ./config/traefik/rules:/rules # Add this line
Also, you need to update your Traefik static configuration (traefik_config.yml) to include the file provider for the rules directory. Add the following to your providers section:
providers:
# Existing providers...
file:
directory: "/rules"
watch: true
Step 4: Add Badger Plugin Configuration
The Middleware Manager relies on Traefik’s ability to use the Badger plugin. Make sure your Traefik configuration includes:
experimental:
plugins:
badger:
moduleName: "github.com/fosrl/badger"
version: "v1.0.0"
Step 5: Start the Services
Now you can start your updated stack:
docker compose up -d
Step 6: Access the Middleware Manager UI
Once everything is running, you can access the Middleware Manager UI at:
http://your-server:3456
Use Template as much as possible dont use dashboard unless you know how to use json format for the same.
Understanding How It Works
The Middleware Manager operates by:
- Monitoring resources created in Pangolin through its API
- Allowing you to attach middlewares to specific resources via the web interface
- Generating Traefik configuration files that properly reference services defined by Pangolin
- Ensuring middlewares are applied with the correct provider references
This approach keeps Pangolin’s configuration clean while extending its capabilities through Traefik’s powerful middleware system.
Common Middleware Configurations
Authentication with Authelia
middlewares:
- id: "authelia"
name: "Authelia Authentication"
type: "forwardAuth"
config:
address: "http://authelia:9091/api/verify?rd=https://auth.yourdomain.com"
trustForwardHeader: true
authResponseHeaders:
- "Remote-User"
- "Remote-Groups"
- "Remote-Name"
- "Remote-Email"
Basic Rate Limiting
middlewares:
- id: "rate-limit"
name: "Basic Rate Limiting"
type: "rateLimit"
config:
average: 100
burst: 50
Security Headers
middlewares:
- id: "security-headers"
name: "Strong Security Headers"
type: "headers"
config:
customResponseHeaders:
Server: ""
X-Powered-By: ""
browserXSSFilter: true
contentTypeNosniff: true
customFrameOptionsValue: "SAMEORIGIN"
forceSTSHeader: true
stsIncludeSubdomains: true
stsSeconds: 63072000
Debugging Common Issues
When using Middleware Manager, you might encounter some challenges. Here’s how to troubleshoot them:
1. “The service does not exist” error in Traefik logs
This usually means the cross-provider reference isn’t working correctly.
Solution:
- Verify the configuration file was generated correctly:
cat ./config/traefik/rules/resource-overrides.yml - Check if service references include the
@httpsuffix - Restart the Middleware Manager:
docker restart middleware-manager
2. “The middleware does not exist” error in Traefik logs
Similar to the service error, but for middlewares:
Solution:
- Verify the middleware is properly defined in the configuration
- Ensure Pangolin-defined middlewares have an
@httpsuffix when referenced - Check if the middleware requires a Traefik plugin that isn’t installed
3. No changes appearing after adding middleware
If you’ve added a middleware but don’t see changes applied:
Solution:
- Check Traefik’s dashboard (if enabled) to see if the routes are correctly defined
- Look at the Middleware Manager logs:
docker logs middleware-manager - Verify the middleware priority (lower numbers have higher precedence)
- Restart Traefik:
docker restart traefik
4. Middleware Manager UI not showing resources
If the UI doesn’t display your Pangolin resources:
Solution:
- Verify connectivity between Middleware Manager and Pangolin:
docker exec middleware-manager curl -f http://pangolin:3001/api/v1 - Check if the Pangolin API URL is correctly set in the environment variables
- Restart the Middleware Manager container
5. Database Errors
If you encounter database-related errors:
Solution:
- Check permissions on the data directory:
ls -la ./data - Ensure the database is properly initialized:
docker logs middleware-manager | grep -i database - As a last resort, you can reset the database:
rm ./data/middleware.db(this will remove all your middleware configurations)
Final Thoughts
The Pangolin Middleware Manager bridges the gap between Pangolin’s elegant simplicity and Traefik’s powerful middleware capabilities. By installing this extension, you gain a flexible security layer that can adapt to your specific needs without sacrificing the user-friendly experience that makes Pangolin so valuable.
Middlewares are powerful tools that require careful configuration and testing. Start simple, test thoroughly, and gradually expand your security posture as you become more comfortable with the system.
Happy proxying!
(Yes, i am the girl that loves UI)
