# Complete Guide to Deploying TraefikShaper Security with Pangolin

**URL:** <https://forum.hhf.technology/t/complete-guide-to-deploying-traefikshaper-security-with-pangolin/1144>\
**Category:** Firewalls & Security\
**Tags:** pangolin, security\
**Created:** [April 4, 2025, 7:49am UTC](https://forum.hhf.technology/t/complete-guide-to-deploying-traefikshaper-security-with-pangolin/1144 "2025-04-04T07:49:30Z")\
**Posts on this page:** 8\
**Page:** 1

<div class="post-metadata">

**Author:** ![hhf.technoloy](https://forum.hhf.technology/user_avatar/forum.hhf.technology/hhf.technoloy/32/68_2.png) [@hhf.technoloy](https://forum.hhf.technology/u/hhf.technoloy)\
**Post date:** [April 4, 2025, 7:49am UTC](https://forum.hhf.technology/t/complete-guide-to-deploying-traefikshaper-security-with-pangolin/1144/1 "2025-04-04T07:49:30Z")

</div>

This guide will walk you through integrating TraefikShaper with Pangolin to add dynamic IP whitelisting capabilities to your self-hosted services. This security layer allows temporary access to your services through an approval system.

> **[GitHub - l4rm4nd/TraefikShaper: Docker container to manipulate Traefik's dynamic...](https://github.com/l4rm4nd/TraefikShaper)**
>
> Docker container to manipulate Traefik's dynamic configuration and IpAllowList middleware for dynamic IP whitelisting

 ![image](https://forum-cdn.hhf.technology/original/2X/8/83699d97583085c98e273ca0528c9ce13dda94f9.png)

## What You’ll Achieve

- Deploy TraefikShaper alongside your Pangolin installation
- Create a `/knock-knock` endpoint for users to request access
- Set up notifications via Discord, Telegram, or WhatsApp
- Configure proper routing to prevent lockouts
- Learn recovery procedures if things go wrong

## Prerequisites

- A working Pangolin installation with Traefik
- Access to your server’s file system
- Basic understanding of YAML and Docker

## 1. Installation and Setup

### 1.1. Update Your Docker Compose File

Add the TraefikShaper service to your `docker-compose.yml`:

 ![image](https://forum-cdn.hhf.technology/original/2X/b/b17c2f04447ca1a5ee677ba8cd477ad22d3dfd34.png)

```yaml
services:
  # Your existing Pangolin services...
  
  traefikshaper:
    image: l4rm4nd/traefikshaper:latest
    container_name: traefikshaper
    restart: unless-stopped
    environment:
      - APPURL=https://your-domain.com #this is up to your convenience.
      - GRANT_HTTP_ENDPOINT=/knock-knock #you can change to custom also.
      - DEFAULT_PRIVATE_CLASS_SOURCE_RANGE=True
      - IPSTRATEGY_DEPTH=0
      - EXPIRATION_TIME=3600
      - APPRISE_NOTIFICATION_URL=discord://webhook_id/webhook_token
    volumes:
      - ./config/traefik/dynamic-whitelist.yml:/app/dynamic-whitelist.yml
      - /etc/localtime:/etc/localtime:ro
      - /etc/timezone:/etc/timezone:ro

```

### 1.2. Create the Dynamic Whitelist File

 ![image](https://forum-cdn.hhf.technology/original/2X/e/e9e69151c994d57df01bc35ff21f0062f72d2322.png)

Create a file at `./config/traefik/dynamic-whitelist.yml`:

```yaml
http:
  middlewares:
    dynamic-ipwhitelist:
      ipAllowList:
        ipStrategy:
          depth: 0
        sourceRange:
        - 127.0.0.1/32
        - 10.0.0.0/8
        - 172.16.0.0/12
        - 192.168.0.0/16

```

This adds localhost and private networks to the allowed IPs by default.

### 1.3. Modify Traefik’s Static Configuration

Edit `./config/traefik/traefik_config.yml` to add the file provider:

```yaml
providers:
  http:
    endpoint: "http://pangolin:3001/api/v1/traefik-config"
    pollInterval: "5s"
  file:
    directory: "/etc/traefik"
    watch: true

# Rest of your existing configuration...

```

Make sure to remove any middleware applied globally at the entrypoint level, as we’ll apply them to specific routers instead.

### 1.4. Update Dynamic Configuration

Edit `./config/traefik/dynamic_config.yml` to add TraefikShaper’s routing rules:

```yaml
http:
  routers:
    # Your existing routers, adding the whitelist middleware
    next-router:
      rule: "Host(`your-domain.com`) && !PathPrefix(`/api/v1`) && !PathPrefix(`/knock-knock`)"
      service: next-service
      entryPoints:
        - websecure
      middlewares:
        - dynamic-ipwhitelist@file
      tls:
        certResolver: letsencrypt
    
    # Add this for the knock-knock endpoint
    knock-knock-router:
      rule: "Host(`your-domain.com`) && PathPrefix(`/knock-knock`)"
      service: traefikshaper-service
      entryPoints:
        - websecure
      priority: 100
      tls:
        certResolver: letsencrypt
  
  services:
    # Your existing services...
    
    # Add this for TraefikShaper
    traefikshaper-service:
      loadBalancer:
        servers:
          - url: "http://traefikshaper:5000"

```

## 2. Setting Up Notifications

TraefikShaper uses the Apprise library for notifications, which supports many services. Here’s how to set up different notification channels:

### 2.1. Discord Notifications

1. Create a webhook in your Discord server:

2. Format for TraefikShaper:

### 2.2. Telegram Notifications

1. Create a Telegram bot using BotFather
2. Get your chat ID using a bot like @userinfobot
3. Format for TraefikShaper:

```auto
tgram://bot_token/chat_id

```

### 2.3. WhatsApp Notifications

WhatsApp is supported through Apprise’s Gotify or REST integrations:

1. Set up a Gotify server or use a WhatsApp-to-REST bridge service
2. Format for Gotify:

```auto
gotify://gotify-server.com/token

```

### 2.4. Multiple Notification Services

You can chain multiple notification services together:

```auto
discord://webhook_id/webhook_token,tgram://bot_token/chat_id

```

## 3. Testing Your Setup

1. Start or restart your Pangolin stack:

2. Try to access a protected resource - you should get blocked

3. Visit `/knock-knock` on the same domain

4. Check your notification service for an approval link

5. Click the approval link to grant access to the requesting IP

6. Try accessing the protected resource again - it should now work

## 4. Recovery Procedures

### 4.1. If You’re Locked Out

If you’ve locked yourself out and can’t access your services:

1. Connect to your server via SSH
2. Edit the whitelist file directly:

```bash
nano ./config/traefik/dynamic-whitelist.yml

```

3. Add your current IP to the sourceRange list:

```yaml
sourceRange:
- 127.0.0.1/32
- YOUR_IP_ADDRESS/32

```

4. Restart TraefikShaper:

```bash
docker restart traefikshaper

```

### 4.2. Complete Reset

If you need to start over:

1. Reset the whitelist file:

2. Restart TraefikShaper:

## 5. Advanced Configuration

### 5.1. Customizing Access Duration

Set how long temporary access lasts (in seconds):

```yaml
environment:
  - EXPIRATION_TIME=86400 # 24 hours

```

### 5.2. IP Strategy Depth

If your Traefik instance is behind a proxy (like Cloudflare):

```yaml
environment:
  - IPSTRATEGY_DEPTH=1

```

### 5.3. Excluded IPs

For specific handling of proxy IPs:

```yaml
environment:
  - EXCLUDED_IPS=103.21.244.0/22,103.22.200.0/22

```

## 6. Troubleshooting

### 6.1. Traefik Configuration Errors

If Traefik fails to start with YAML errors:

- Check for tab characters - YAML requires spaces
- Verify that rules are formatted correctly
- Ensure multiple path prefixes use separate conditions with `&&`

### 6.2. TraefikShaper Issues

If TraefikShaper shows “Invalid token” errors:

- Each approval link can only be used once
- Tokens expire after a short time
- Check that SECRET\_KEY hasn’t changed

### 6.3. Notification Problems

If you’re not receiving notifications:

- Verify the notification URL format is correct
- Check TraefikShaper logs for error messages
- Test with a simpler notification service first

## 7. Security Considerations

- Always include private subnets in your allowlist if needed internally
- Consider setting up a dedicated domain for TraefikShaper
- Keep approval times short for sensitive services
- Regularly check what IPs have been whitelisted

## 8. Regular Maintenance

It’s good practice to periodically:

1. Check the whitelist to remove unnecessary IPs
2. Update the TraefikShaper container to the latest version
3. Review your notification settings to ensure they still work
4. Test the recovery procedures

By following this guide, you’ve added a powerful security layer to your Pangolin installation that gives you granular control over who can access your services, while providing a convenient mechanism for temporary access through notifications.

---

<div class="post-metadata">

**Author:** ![beuz](https://forum.hhf.technology/user_avatar/forum.hhf.technology/beuz/32/931_2.png) [@beuz](https://forum.hhf.technology/u/beuz)\
**Post date:** [April 6, 2025, 9:42am UTC](https://forum.hhf.technology/t/complete-guide-to-deploying-traefikshaper-security-with-pangolin/1144/2 "2025-04-06T09:42:29Z")

</div>

Thanks for this guide!

Got everything working except for the approval page. I’ve set the ‘APPURL’ variable for traefik-shaper to ‘traefikshaper.my-domain.nl’ but when I try to access it I get a ‘SSL\_ERROR\_UNRECOGNIZED\_NAME\_ALERT’ error. I must be missing something but can’t figure it out. Any suggestions?

---

<div class="post-metadata">

**Author:** ![hdsplus](https://forum.hhf.technology/user_avatar/forum.hhf.technology/hdsplus/32/1548_2.png) [@hdsplus](https://forum.hhf.technology/u/hdsplus)\
**Post date:** [April 20, 2025, 8:48pm UTC](https://forum.hhf.technology/t/complete-guide-to-deploying-traefikshaper-security-with-pangolin/1144/4 "2025-04-20T20:48:08Z")

</div>

With this conf, It does not work as expected. When you accept the request, being linked to “next-service” it returns you to the Pangolin login, it does not redirect you to the service. Would it have a solution?

---

<div class="post-metadata">

**Author:** ![hdsplus](https://forum.hhf.technology/user_avatar/forum.hhf.technology/hdsplus/32/1548_2.png) [@hdsplus](https://forum.hhf.technology/u/hdsplus)\
**Post date:** [May 3, 2025, 5:10am UTC](https://forum.hhf.technology/t/complete-guide-to-deploying-traefikshaper-security-with-pangolin/1144/5 "2025-05-03T05:10:32Z")

</div>

Can the article be updated, explained to actually work? Thanks

---

<div class="post-metadata">

**Author:** ![hhf.technoloy](https://forum.hhf.technology/user_avatar/forum.hhf.technology/hhf.technoloy/32/68_2.png) [@hhf.technoloy](https://forum.hhf.technology/u/hhf.technoloy)\
**Post date:** [May 3, 2025, 6:26am UTC](https://forum.hhf.technology/t/complete-guide-to-deploying-traefikshaper-security-with-pangolin/1144/6 "2025-05-03T06:26:42Z")

</div>

its working for general UI. not for individual resources. for individual resources you will need to use custom routers once you create your service and override them.

---

<div class="post-metadata">

**Author:** ![hdsplus](https://forum.hhf.technology/user_avatar/forum.hhf.technology/hdsplus/32/1548_2.png) [@hdsplus](https://forum.hhf.technology/u/hdsplus)\
**Post date:** [May 3, 2025, 6:49am UTC](https://forum.hhf.technology/t/complete-guide-to-deploying-traefikshaper-security-with-pangolin/1144/7 "2025-05-03T06:49:15Z")

</div>

> [@hhf.technoloy](#):
>
> ```auto
> traefikshaper-service:
> loadBalancer:
> servers:
> - url: "http://traefikshaper:5000"
> 
> ```

what custom routers?

---

<div class="post-metadata">

**Author:** ![hhf.technoloy](https://forum.hhf.technology/user_avatar/forum.hhf.technology/hhf.technoloy/32/68_2.png) [@hhf.technoloy](https://forum.hhf.technology/u/hhf.technoloy)\
**Post date:** [May 3, 2025, 6:50am UTC](https://forum.hhf.technology/t/complete-guide-to-deploying-traefikshaper-security-with-pangolin/1144/8 "2025-05-03T06:50:40Z")

</div>

` docker exec pangolin curl http://localhost:3001/api/v1/traefik-config | jq` run this and you will see all the routers for your resources

---

<div class="post-metadata">

**Author:** ![hdsplus](https://forum.hhf.technology/user_avatar/forum.hhf.technology/hdsplus/32/1548_2.png) [@hdsplus](https://forum.hhf.technology/u/hdsplus)\
**Post date:** [May 3, 2025, 12:19pm UTC](https://forum.hhf.technology/t/complete-guide-to-deploying-traefikshaper-security-with-pangolin/1144/9 "2025-05-03T12:19:44Z")

</div>

> [@hhf.technoloy](#):
>
> ```auto
> knock-knock-router:
> rule: "Host(`your-domain.com`) && PathPrefix(`/knock-knock`)"
> service: traefikshaper-service
> entryPoints:
> - websecure
> priority: 100
> tls:
> certResolver: letsencrypt
> 
> ```

 ![Screenshot 2025-05-03 at 9.19.56 AM](https://forum-cdn.hhf.technology/original/2X/f/f6531f9a27801853673e91e269cd18cb148acf07.png)

 ![Screenshot 2025-05-03 at 9.20.25 AM](https://forum-cdn.hhf.technology/original/2X/5/5219aa3d344db8b51ddbf6866f6629e232353124.png)

I have done what you say and I see that Traefikshaper runs in the “18-service”. I have modified it in Routers but nothing. what am I doing wrong?