Feature Request: Custom Headers for Individual Pangolin Resources #934

New Issue

MrUnknownDE · 2026-04-05T18:01:30+02:00

MrUnknownDE commented

2026-04-05 18:01:30 +02:00

Originally created by @oschwartz10612 on 9/11/2025

Discussed in https://github.com/orgs/fosrl/discussions/455

^{Originally posted by hhftechnology April 4, 2025}

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:

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

Use Cases

Authentication Headers: Adding Authorization, X-API-Key, or service-specific auth headers
CORS Configuration: Setting Access-Control-Allow-Origin for specific services
Proxied Client Information: Passing X-Forwarded-For, X-Real-IP with appropriate values
Application-Specific Headers: Some applications require custom headers like X-Requested-With
Cache Control: Different caching strategies for different resources
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]

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]

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
    }

Implementation Details

Database Schema Update:
- Create a new header_rules table to store header configurations
- Link header rules to resources with a foreign key
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
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
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

Migration Consideration

The feature should include:

A database migration script to add the new tables
Backward compatibility for existing resources (no headers by default)
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

Gather feedback on the proposed implementation
Prioritize the feature request in the development roadmap
Design detailed UI mockups for the header management interface
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.

*Originally created by @oschwartz10612 on 9/11/2025* ### Discussed in https://github.com/orgs/fosrl/discussions/455 <div type='discussions-op-text'> <sup>Originally posted by **hhftechnology** April 4, 2025</sup> ## 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: ```mermaid 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] ``` ### Technical Architecture ```mermaid 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] ``` ### Configuration Data Model ```mermaid 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 } ``` ## 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 ```yaml 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 ```mermaid 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 ``` ## 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.</div>

MrUnknownDE closed this issue

2026-04-05 18:01:30 +02:00

Sign in to join this conversation.

Branches Tags

main

dev

dependabot/npm_and_yarn/dev-minor-updates-b4e5d6b9c5

revert-2766-feature/systemd-install-instructions

dependabot/npm_and_yarn/prod-patch-updates-05702d39f2

dependabot/npm_and_yarn/next-16.2.1

dependabot/npm_and_yarn/recharts-3.8.1

alerting-rules

private-site-ha

dependabot/docker/docker/library/node-25-slim

ssh

delete-account

msg-delivery

org-only-idp

cicd

patch

site-targets-auto-login

No Label

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github/pangolin#934