Что означает $http_x_real_ip в Nginx log_format

Переменная $http_x_real_ip в Nginx — это стандартная системная переменная, которая содержит значение HTTP-заголовка X-Real-IP. Эта переменная используется для доступа к реальному IP-адресу клиента, переданному через прокси-серверы или CDN, и является частью встроенной системы переменных Nginx, где префикс $http_ указывает на доступ к значениям HTTP-заголовков.

Содержание

• Что такое $http_x_real_ip
• Как работает переменная $http_x_real_ip
• Примеры использования в log_format
• Отличия от других переменных IP
• Настройка и конфигурация
• Безопасность и валидация
• Заключение

Что такое $http_x_real_ip

Переменная $http_x_real_ip является частью стандартного набора переменных Nginx, который предоставляет доступ к значениям HTTP-заголовков. В Nginx существует общая система переменных, где любой HTTP-заголовок может быть доступен через переменную с именем $http_<имя_заголовка>, где имя заголовка преобразуется в нижний регистр, а дефисы заменяются на подчеркивания.

Таким образом, переменная $http_x_real_ip напрямую соответствует HTTP-заголовку X-Real-IP, который часто используется прокси-серверами и CDN для передачи реального IP-адреса клиента сквозь цепочку прокси.

Важно: Эта переменная не является пользовательской или кастомной — она является стандартной частью Nginx и доступна во всех сборках Nginx, начиная с ранних версий.

Как работает переменная $http_x_real_ip

Когда запрос проходит через Nginx, сервер автоматически создает переменные для всех полученных HTTP-заголовков. Процесс работы с $http_x_real_ip можно описать следующим образом:

1. Клиент отправляет запрос через прокси-сервер
2. Прокси-сервер добавляет заголовок X-Real-IP с реальным IP-адресом клиента
3. Nginx получает этот заголовок и создает соответствующую переменную $http_x_real_ip
4. В конфигурации Nginx можно использовать эту переменную в директивах, включая log_format

Пример базового использования:

log_format main '$http_x_real_ip - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';

Этот формат записи будет отображать реальный IP-адрес клиента, переданный через заголовок X-Real-IP.

Примеры использования в log_format

В исследованных конфигурациях были найдены различные примеры использования $http_x_real_ip в директиве log_format:

Базовый формат с реальным IP

log_format specialLog '$remote_addr forwarded for $http_x_real_ip - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';

Комбинированный формат с несколькими IP-заголовками

log_format combined_realip '$http_x_forwarded_for - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';

Формат для Cloudflare

log_format combined_realip_cf '$http_cf_connecting_ip $http_x_forwarded_for - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';

Таблица сравнения форматов логирования

Как отмечается в исследованиях, для Nginx можно просто использовать переменную $http_x_real_ip вместо IP-адреса, чтобы получить реальный IP клиента, переданный через заголовок.

Отличия от других переменных IP

Важно понимать различия между различными IP-переменными в Nginx:

Сравнение IP-переменных

Как объясняется в обсуждениях на Stack Overflow, выбор между заголовками зависит от того, какой тип прокси-сервера используется и можно ли доверять получаемым данным.

Настройка и конфигурация

Для корректной работы с $http_x_real_ip может потребоваться дополнительная настройка Nginx:

Базовая конфигурация

http {
    log_format main '$http_x_real_ip - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';
    
    server {
        access_log /var/log/nginx/access.log main;
    }
}

Настройка с модулем realip

Если используется модуль ngx_http_realip_module, можно доверять определенным прокси-серверам:

http {
    set_real_ip_from 192.168.1.0/24;
    set_real_ip_from 10.0.0.0/8;
    real_ip_header X-Real-IP;
    
    log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';
}

Как указано в документации Nginx, при отключенном рекурсивном поиске исходный адрес клиента, соответствующий одному из доверенных адресов, заменяется последним адресом, отправленным в заголовке запроса.

Безопасность и валидация

При использовании $http_x_real_ip важно учитывать аспекты безопасности:

Проверка доверенных прокси

http {
    # Доверяем только определенным прокси-серверам
    set_real_ip_from 192.168.1.0/24;
    set_real_ip_from 10.0.0.0/8;
    real_ip_header X-Real-IP;
}

Защита от подмены IP

Как отмечается в ответах на Server Fault, по умолчанию real_ip_header использует X-Real-IP, что означает, что вредоносный пользователь может отправить запрос с случайным X-Real-IP и это будет использовано как $remote_addr.

Рекомендации по безопасности

1. Всегда указывайте доверенные прокси-серверы через set_real_ip_from
2. Используйте безопасные сетевые сегменты для доверия
3. Рассмотрите использование PROXY Protocol для более надежной передачи IP
4. Валидируйте IP-адреса в приложении

Заключение

1. $http_x_real_ip — это стандартная переменная Nginx, содержащая значение заголовка X-Real-IP, а не пользовательская переменная.

2. Основное назначение — доступ к реальному IP-адресу клиента, переданному через прокси-серверы или CDN в виде HTTP-заголовка.

3. Применение в log_format позволяет включать реальный IP-адрес в логи вместо IP-адреса последнего прокси-сервера, что важно для анализа и мониторинга.

4. Настройка безопасности требует указания доверенных прокси-серверов через set_real_ip_from для предотвращения подмены IP-адресов.

5. Альтернативные заголовки — в зависимости от инфраструктуры можно использовать X-Forwarded-For, CF-Connecting-IP или другие заголовки через соответствующие переменные Nginx.

Для более глубокого изучения рекомендую ознакомиться с официальной документацией по ngx_http_realip_module и изучить примеры конфигураций в реальных проектах.

Источники

1. NGINX access_log: log the real client IP from X-Forwarded-For/X-Real-IP/cf-connecting-ip instead of the proxy IP
2. nginx with real_ip – log both client remote_addr and proxies address - Server Fault
3. NGINX and X-Forwarded-For Header (XFF) | Loadbalancer
4. Get user real ip in nginx behind nginx reverse proxy – Yannick Pereira-Reis
5. Module ngx_http_realip_module - Nginx Documentation
6. Forwarding Visitor’s Real-IP in Nginx Proxy/Fastcgi backend correctly
7. Difference between X-Forwarded-For and X-Real-IP headers - Stack Overflow
8. How to use multiple real IP headers with nginx | Medium