Traefik Real IP

A Traefik middleware plugin that extracts the real client IP address from various HTTP headers.

Overview

Traefik Real IP extracts and validates the actual client IP address from commonly used headers such as X-Forwarded-For, X-Real-IP, and Cf-Connecting-Ip. This plugin is particularly useful when Traefik is behind a CDN, proxy, or load balancer like Cloudflare.

Features

• Extracts real IP from Cf-Connecting-Ip, Eo-Connecting-Ip, X-Real-IP, and X-Forwarded-For headers
• Validates whether the source IP is trusted before accepting header values
• Built-in support for Cloudflare IP ranges
• Optional support for EdgeOne IP ranges
• Supports local/private IP ranges
• Custom trusted IP configuration
• Configurable logging level

Installation

From Traefik Pilot

The easiest way to install this plugin is through the Traefik Plugin Catalog.

Manual Installation

Add the plugin to your Traefik static configuration:

Copy
experimental:
  plugins:
    traefik-real-ip:
      moduleName: github.com/zekihan/traefik-real-ip
      version: v0.1.19

Configuration

Static Configuration Example

Copy
# Static configuration
experimental:
  plugins:
    traefik-real-ip:
      moduleName: github.com/zekihan/traefik-real-ip
      version: v0.1.19

Middleware Configuration

Copy
# Dynamic configuration
http:
  middlewares:
    traefik-real-ip:
      plugin:
        traefik-real-ip:
          thrustLocal: true
          thrustCloudFlare: true
          thrustEdgeOne: false
          trustedIPs: 
            - "1.2.3.4/32"
            - "10.0.0.0/8"
          logLevel: info

Configuration Options

Option	Type	Default	Description
thrustLocal	boolean	true	Trust local and private IP ranges
thrustCloudFlare	boolean	true	Trust Cloudflare IP ranges
thrustEdgeOne	boolean	false	Trust EdgeOne IP ranges
trustedIPs	array of strings	[]	Additional IP ranges to trust in CIDR notation
logLevel	string	info	Log level (debug, info, warn, error)

How It Works

1. The plugin extracts the source IP from the incoming request
2. It checks if the source IP is in the trusted IPs list
3. If trusted, it looks for real IP in headers in this order: Cf-Connecting-Ip, Eo-Connecting-Ip, X-Real-IP, then X-Forwarded-For.
4. It updates the request headers with the discovered real IP
5. Adds an X-Is-Trusted: yes|no header indicating if the source was trusted

Development

Testing Locally

A Docker Compose setup is provided in the testing folder to test the plugin locally:

Copy
cd testing
docker-compose up -d

Running Tests

Copy
go test ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.