Feature Request: Custom Headers for Individual Pangolin Resources

[hhftechnology]

Overview

Currently, Pangolin doesn't provide a way to set custom HTTP headers for individual resources. We request the ability to configure custom request and response headers for each resource, similar to Cloudflare's Transform Rules for HTTP Request Header Modification.

Problem Statement

When proxying to various backend services, different applications often require specific HTTP headers for proper functionality, authentication, or integration. Without the ability to customize headers at the resource level, users must:

1. Modify the target application to handle standard headers (not always possible)
2. Configure complex middleware rules in Traefik manually (outside Pangolin's management)
3. Deploy additional proxies between Pangolin and the target service

Use Cases

1. Authentication Headers: Adding Authorization, X-API-Key, or service-specific auth headers
2. CORS Configuration: Setting Access-Control-Allow-Origin for specific services
3. Proxied Client Information: Passing X-Forwarded-For, X-Real-IP with appropriate values
4. Application-Specific Headers: Some applications require custom headers like X-Requested-With
5. Cache Control: Different caching strategies for different resources
6. Content Security Policies: Adding specific CSP headers for sensitive applications

Proposed Implementation

Feature Capabilities

• Add, modify, or remove request headers (client → Pangolin → resource)
• Add, modify, or remove response headers (resource → Pangolin → client)
• Support for static header values and dynamic values (variables/expressions)
• Option to apply headers conditionally based on path patterns

UI Integration

Add a new "Headers" tab within each resource configuration alongside the existing "Connectivity" and "Authentication" tabs:

graph TD
    A[Resource Details] --> B[Connectivity Tab]
    A --> C[Authentication Tab]
    A --> D[New: Headers Tab]
    
    D --> E[Request Headers Section]
    D --> F[Response Headers Section]
    
    E --> G[Add Request Header]
    E --> H[Edit Request Header]
    E --> I[Remove Request Header]
    
    F --> J[Add Response Header]
    F --> K[Edit Response Header]
    F --> L[Remove Response Header]

Loading

Technical Architecture

flowchart TD
    A[Pangolin UI] -->|Save Header Config| B[Pangolin Backend]
    B -->|Store in Database| C[(Database)]
    B -->|Generate Config| D[Traefik Dynamic Config]
    D -->|Apply| E[Traefik Reverse Proxy]
    E -->|Add/Modify Headers| F[HTTP Request/Response]
    F -->|Forward to| G[Target Service]

Loading

Configuration Data Model

erDiagram
    Resource ||--o{ HeaderRule : has
    HeaderRule {
        string id
        string resource_id
        string name
        string description
        boolean enabled
        string type "request|response"
        string operation "add|set|remove"
        string header_name
        string header_value
        string condition_type "none|path|method"
        string condition_value
    }

Loading

Implementation Details

1. Database Schema Update:

   • Create a new header_rules table to store header configurations
   • Link header rules to resources with a foreign key

2. Backend API Endpoints:

   • GET /api/v1/resources/{resourceId}/headers - List headers for a resource
   • POST /api/v1/resources/{resourceId}/headers - Add a header
   • PUT /api/v1/resources/{resourceId}/headers/{headerId} - Update a header
   • DELETE /api/v1/resources/{resourceId}/headers/{headerId} - Delete a header

3. Traefik Integration:

   • Extend the dynamic configuration generator to include custom headers in the middleware chain
   • Generate appropriate Traefik header middleware configurations based on stored rules
   • Apply middleware to the specific router for each resource

4. UI Components:

   • Header management interface with add/edit/delete capabilities
   • Form for configuring header name, value, conditions
   • Toggle for enabling/disabling individual header rules
   • Option to specify request or response header modification

Example Configuration in Traefik

http:
  middlewares:
    resource-123-request-headers:
      headers:
        customRequestHeaders:
          X-Api-Key: "myApiKey123"
          User-Agent: "PangolinProxy/1.0"
    
    resource-123-response-headers:
      headers:
        customResponseHeaders:
          X-Powered-By: "Pangolin"
          Cache-Control: "max-age=3600"

User Experience

Adding a Header Rule

sequenceDiagram
    Actor User
    User->>Pangolin UI: Navigate to Resource
    Pangolin UI->>Pangolin UI: Open Headers Tab
    User->>Pangolin UI: Click "Add Header Rule"
    Pangolin UI->>Pangolin UI: Display Header Configuration Form
    User->>Pangolin UI: Fill out form (name, type, operation, etc.)
    User->>Pangolin UI: Save Header Rule
    Pangolin UI->>Pangolin Backend: Send Header Configuration
    Pangolin Backend->>Database: Store Header Rule
    Pangolin Backend->>Traefik: Update Dynamic Configuration
    Pangolin Backend->>Pangolin UI: Confirm Save
    Pangolin UI->>User: Display Success Message

Loading

Migration Consideration

The feature should include:

1. A database migration script to add the new tables
2. Backward compatibility for existing resources (no headers by default)
3. Documentation for users to understand how to effectively use custom headers

Security Considerations

• Restrict access to header management based on user roles (admin vs member)
• Consider sanitizing header values to prevent security issues
• Option to mask sensitive header values in logs and UI
• Provide warnings for security-sensitive headers

Next Steps

1. Gather feedback on the proposed implementation
2. Prioritize the feature request in the development roadmap
3. Design detailed UI mockups for the header management interface
4. Implement a proof of concept to validate the approach

We believe this feature would significantly improve Pangolin's flexibility and usefulness for various self-hosting scenarios, allowing it to better serve diverse applications without requiring additional proxies or manual Traefik configuration.

[hhftechnology]

https://forum.hhf.technology/t/enhancing-your-pangolin-deployment-with-middleware-manager/

With this you can set it per resources any middlwares

https://github.com/hhftechnology/middleware-manager

[gtbdf1]

jumping in to echo what others have already surfaced here.

I've been testing Pangolin + Newt for exposing multiple internal services from my home lab (Sonarr, Plex, Bookstack, etc.), and while the install experience was beautifully simple, I'm running into the same core issue:

🛑 "404 page not found" for anything relying on hostname-based routing or redirects.

My setup uses:
Newt running internally in Docker, with extra_hosts added for internal DNS names
Pangolin, Gerbil, and Traefik on a VPS
Services like Bookstack (on Kubernetes via Ingress), Sonarr (on a Windows VM), and Plex (on a host with DNS entries resolving to local IPs)

The Problem
When I expose these through Pangolin as HTTPS Resources, requests reach the internal app, but:
Absolute redirects (e.g. from / to /login) break
Internal apps generate links using their local hostname
The Host header isn't preserved, so any app routing by hostname fails
The result is often a 404, blank page, or redirect loop

This applies regardless of whether the backend is on Docker, Kubernetes, or a plain VM — if it relies on Host-based routing or absolute URLs, it fails through Pangolin.

Request for Enhancement
It would be huge if Pangolin:
Supported custom Host headers for HTTPS Resources
(Ideally) Rewrote internal redirects to preserve the public-facing URL
Allowed users to override scheme/hostname/path when apps can't be rewritten

This would bring it in line with what we get from tools like Traefik or NGINX reverse proxy, and make Pangolin + Newt a true drop-in solution for homelabbers with complex internal DNS setups.

Let me know if you'd like any logs or configs — I’m happy to help test or provide more info.

Thanks for the awesome work so far 🙌

[Aetylus]

I came across your post looking to see if Pangolin would support being a cloud-hosted reverse proxy to a locally hosted Kubernetes server.

In my particular case, I have MetalLB providing a single local IP for the ingress, which handles routing to individual services based off hostname. The service hostnames in Kubernetes is actually true to the external hostnames that would be used (e.g. Kubernetes service host is service.example.org, and I would be hosting Pangolin with the base domain of example.org). Despite this, it sounds like since Pangolin currently does not preserve the host header, it would fail if I wanted to point Pangolin to the ingress service ports on Kubernetes, where normally the ingress would handle routing based off host header?

Thanks for any clarification!

[Edit] I've been doing some internal testing and from what I can see, in my particular use case, it would work. Since the hosts are the same (Pangolin would have a service.example.org resource and the Kubernetes ingress routes to service.example.org), requests through Pangolin will work as expected.

[miloschwartz]

@gtbdf1 Hope to clean up some of this basic proxy functionality / expose more raw Traefik features soon after we knock out some of these larger system components like external IDP support, etc. I agree, stuff like this is needed for true adoption as the proxy is super basic at the moment. Thanks for the tips!

[a-oxide]

Bumping this

[yann117]

I'm really waiting on this too. I'm pretty new to the homelab/self-hosting hobby, but I now have my basic working setup and am polishing stuff.
The most annoying thing I'm facing is that end-users have to log in once into Pangolin, and then again for every connected service.

I started to look into a solution, thinking that this would be a piece of cake, as this requirement seems obvious with regard to proxy and self-hosting. But soon I realised this is far from a standard and mostly due to the diversity of solutions existing for connecting the multitude of services, choosing each their own way of implementation.

So right now, I concluded that this requires collaboration (of course) of the two endpoints (proxy/Pangolin and the connected service), which is not yet ready on either side. Many of the services I'm looking into either:

• doesn't offer external authentication at all
• support one of the many available SSO (OAuth, LDAP, SAML, custom header)

Even in a good scenario, I observed a bad result, for example, playing around with Pocket-Id OAuth as a front-end before Pangolin, and then accessing a service that supports OAuth too, I got a "two-login" phase: first OAuth sequence to Pangolin, then a second OAuth sequence to the service. The first sequence did not transfer the context, causing a bad user experience. I can't get what is missing there?

@hhftechnology
Then, in the meantime we get the custom resource's headers in Pangolin, I was wondering about your work-around suggestion/statement:

1. Modify the target application to handle standard headers (not always possible)

Inspecting the login-sequence, I don't see Pangolin setting any standard header at all. It is just using p_session_token, am I missing something? I would expect indeed to find the current log-in username, possibly the email as well, but nothing was present. This would be a first step to try modify some of the services I'm using.

Do you have implementation detail on that part, what Pangolin is doing right now?

And finally, just out of curiosity, how are you all doing currently, to address/work-around this issue? Any good tools/configuration to suggest?
Of course, I could say to the end user to pickup simple password for the backend service, but this is not really a good idea, as it means other user could also find those password and break into their account.

[hhftechnology]

https://github.com/hhftechnology/middleware-manager

[ForceConstant]

So I am having issue, where I need to add Access-Control-Allow-Origin header to the proxied response for a subdomain. Is this what is meant by this feature request? i.e. we can't do this already?

[Vertux]

What is the correct input format for the custom host header? I could not find any documentation.

[i-am-at0m]

What is the correct input format for the custom host header? I could not find any documentation.

I can't find any information on this either

[hafteto]

How to add for example custom header for transmission rpc required?

Nginx equivalent is - proxy_pass_header X-Transmission-Session-Id;

Adding as X-Transmission-Session-Id does noting.

[Crashman1983]

Hi!

I use iOS native apps (like immich) that do not support any kind of special authentication, except OIDC for login. When a ressource is secured by pangolin, this app cannot connect to it.

Using Cloudflare I setup custom authentication header - a code that's setup within the app to authenticate for access to the ressource. That is working good and the ressource does not have to be public.

Is this meant to be possible with this feature?

[oschwartz10612]

Yeah I think this would help. You can also look into either using bypass rules for immich https://docs.fossorial.io/Pangolin/bypass-rules

or look into creating a shareable link and using the header from that. I am not sure if other users have had success with this on Immich.

[shanelord01]

The shareable link headers work perfectly for this.

[yann117]

Yes, Immich App does work/support this (at least on Android).

In Settings > Advanced > custom proxy headers
Then you can add the P-Access-Token=xxx and P-Access-Token-Id=yyy

[Crashman1983]

Good idea, will try that!

[Crashman1983]

That doesn't work for me.

[shanelord01]

If it works on Cloudflare it should work here (tested on iOS and Android apps). Make sure you have the header names and values matching perfectly.

Header name:
P-Access-Token-Id

Header value:
your id from shareable link

Header name:
P-Access-Token

Header value:
your token from shareable link

[AttaInsularis]

That doesn't work for me.

Like this in Immich app, no ':' included.

And after this (confirm both are saved, sometimes Immich do not save second entry - restart app and repeat) go in Networking.

Here allow:
Automatic URL switching (add exceptions for location/WiFi name).

Then choose USE CURRENT CONNECTION (if that is the WiFi where Immich does exist on LAN, if not, wait with this when at the location).

And add in EXTERNAL NETWORK field the full path (https:// subdomain. mydomain.xyz/) > check with tick on left side of the input field > should go on green.

Done.

So now the mobile app working:
with no Pangolin SSO - seamless all actions
web still requires SSO (and my selected peers know the PIN to proceed)
rest of the web face the wall.

[lthieman]

I've run into this same problem trying to configure Wordpress. It needs X-Fordwarded-For but I cannot figure out how to add that to Pangolin.

[oschwartz10612]

X-Fordwarded-For is added by default to requests by traefik and should be present I think

[lthieman]

Well, after hours of fighting with it trying everything I could find on the internet I switched back to Nginx Proxy Manager and the errors went away. So something is different about how Traefik and Nginx handle proxy termination and headers. I wish I could tell you what, but in my ineptitude all I know is I was able to make one work and the other not. If you want to try reproducing what I had going on I was using Pangolin in front of wordpress running as an LXC on Proxmox using the Community Helper Scripts deployment. The site looked find and I could log into it and even install plugins and themes. But if you tried to make changes to the pages when you save them it couldn't. Under the site health tab the errors made it look like a loop back problem but none of the cures I was able to find fixed it.

[lhw]

For the few people just want to send some headers like basic authentication to the backend I quickly threw together a small container that adds that functionality until pangolin has it natively. https://github.com/lhw/pangolin-patcher
Deployment and configuration takes like 1-2mins. This does not replace a proper middleware manager. It simply does what it says on the tin.

[sirkelsalot]

Just wanted to say thanks. I recently switched to Pangolin after playing with sending basic auth with NPMplus and TinyAuth. It appears to be working as exactly as advertised.

[john-lazarus]

In my humble opinion, the priority on this item should be bumped to 100 and it is a real shocker (to everyone's surprise) to see that this is not treated as such!

As more and more people start replacing their HAProxy and NGINX setups to use Pangolin, they are all finding that they really cannot do it yet as something as basic as setting and tuning forwarded headers is absent from this solution without going through an increasingly complex set of workarounds and configurations.

This is definitely the last thing holding a lot of us making the switch and most definitely losing the product owners of a much larger fan base!

[hhftechnology]

this feature is really difficult to implement. once the project matures it will slide into this.

[v1rusnl]

Additionally it's the best way to get rid of path rules for a lot of Android and iOS apps that have no option the use custom headers with them. The allowed path rules open new security flaws and undermine the purpose of Pangolin security features imo.

[hhftechnology]

i agree to this. we can't have paths. we don't know what slides through. i dont like paths unless you really trust traffic naked in your home lab

[oschwartz10612]

Want to do this soon! :}

[kareemschultz]

Would love for this to be implemented

[oschwartz10612]

Tracking and actively developing: #1446