Testing Forwarded Headers

This document describes how to test the X-Forwarded-For and Forwarded header support in Qdrant access logs.

Configuration

Enable trusted forwarded headers in your config:

service:
  trust_forwarded_headers: true

Or via environment variable:

export QDRANT__SERVICE__TRUST_FORWARDED_HEADERS=true

Warning: Only enable this when Qdrant is behind a trusted reverse proxy or load balancer. Enabling this without a trusted proxy allows clients to spoof their IP address.

Enable gRPC Access Logs

gRPC access logs are disabled by default (trace level). Enable them with:

export QDRANT__LOG_LEVEL=info,qdrant::tonic::logging=trace

Testing Without Load Balancer

Simulate proxy headers directly with curl/grpcurl.

HTTP (REST API)

# Standard Forwarded header (RFC 7239)
curl -H "Forwarded: for=203.0.113.50" http://localhost:6333/collections

# Legacy X-Forwarded-For header
curl -H "X-Forwarded-For: 203.0.113.50" http://localhost:6333/collections

# Multiple proxies (leftmost IP is the original client)
curl -H "X-Forwarded-For: 203.0.113.50, 198.51.100.178, 192.0.2.1" http://localhost:6333/collections

gRPC

# Standard Forwarded header (RFC 7239)
grpcurl -plaintext -H "Forwarded: for=203.0.113.50" localhost:6334 qdrant.Qdrant/HealthCheck

# Legacy X-Forwarded-For header  
grpcurl -plaintext -H "X-Forwarded-For: 203.0.113.50" localhost:6334 qdrant.Qdrant/HealthCheck

# IPv6 address
grpcurl -plaintext -H "Forwarded: for=\"[2001:db8::1]\"" localhost:6334 qdrant.Qdrant/HealthCheck

Expected Log Output

With trust_forwarded_headers: true:

203.0.113.50 gRPC /qdrant.Qdrant/HealthCheck Ok 0.000123

With trust_forwarded_headers: false (default):

gRPC /qdrant.Qdrant/HealthCheck Ok 0.000123

Testing With Nginx as Load Balancer

Nginx Configuration

upstream qdrant_http {
    server 127.0.0.1:6333;
}

upstream qdrant_grpc {
    server 127.0.0.1:6334;
}

# HTTP proxy
server {
    listen 8080;
    
    location / {
        proxy_pass http://qdrant_http;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Host $host;
    }
}

# gRPC proxy
server {
    listen 8081 http2;
    
    location / {
        grpc_pass grpc://qdrant_grpc;
        grpc_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Start Nginx

# Test config
nginx -t -c /path/to/nginx.conf

# Start
nginx -c /path/to/nginx.conf

Stop Nginx

# Graceful shutdown (finish current requests)
nginx -s quit

# Immediate shutdown
nginx -s stop

# Reload config without stopping
nginx -s reload

Test Through Nginx

# HTTP - your real IP will be logged
curl http://localhost:8080/collections

# gRPC - your real IP will be logged
grpcurl -plaintext localhost:8081 qdrant.Qdrant/HealthCheck

Testing With Docker Compose

version: '3.8'

services:
  nginx:
    image: nginx:alpine
    ports:
      - "8080:8080"
      - "8081:8081"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
    depends_on:
      - qdrant

  qdrant:
    image: qdrant/qdrant
    environment:
      - QDRANT__SERVICE__TRUST_FORWARDED_HEADERS=true
      - QDRANT__LOG_LEVEL=info,qdrant::tonic::logging=trace
    ports:
      - "6333:6333"
      - "6334:6334"

Security Verification

Verify that IP spoofing is blocked when trust_forwarded_headers: false:

# With trust_forwarded_headers: false (default)
curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:6333/collections
# Log should NOT show 1.2.3.4

Verify that headers are trusted when enabled:

# With trust_forwarded_headers: true
curl -H "X-Forwarded-For: 1.2.3.4" http://localhost:6333/collections
# Log SHOULD show 1.2.3.4

Header Priority

1. Standard Forwarded header (RFC 7239) - checked first
2. Legacy X-Forwarded-For header - fallback

Example with both headers:

# Forwarded header takes precedence
curl -H "Forwarded: for=10.0.0.1" -H "X-Forwarded-For: 10.0.0.2" http://localhost:6333/collections
# Log shows: 10.0.0.1

All Submissions:

• Contributions should target the dev branch. Did you create your branch from dev?
• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same update/change?

New Feature Submissions:

1. Does your submission pass tests?
2. Have you formatted your code locally using cargo +nightly fmt --all command prior to submission?
3. Have you checked your code using cargo clippy --workspace --all-features command?

Changes to Core Features:

• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your core changes, as applicable?
• Have you successfully ran tests with your changes locally?