Переменные NGINX

Описание

Переменная $http_user_agent в NGINX используется для получения строки User-Agent из входящих HTTP-запросов. Эта строка идентифицирует программное обеспечение клиента, выполняющего запрос, и обычно содержит информацию о типе браузера клиента, версии и операционной системе. Заголовок User-Agent обычно задаётся веб-браузерами, мобильными приложениями и различными клиентскими программами, чтобы сообщить серверу о своих возможностях и характеристиках. Важно отметить, что эта переменная заполняется на фазе обработки запроса, когда сервер получает запрос, что делает её доступной для логирования, обработки или условной конфигурации. Когда сервер NGINX обрабатывает входящий запрос, он разбирает различные HTTP-заголовки, и среди этих заголовков находится User-Agent. Если заголовок User-Agent присутствует в запросе, его значение сохраняется в переменной $http_user_agent, что позволяет администраторам сервера реализовывать правила на основе типа клиента, выполняющего запрос. Например, администраторы могут отдавать разный контент разным браузерам или устройствам на основании их строки User-Agent. Типичными значениями этой переменной могут быть строки вроде "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36" для Google Chrome или "Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0 Mobile/15E148 Safari/604.1" для Safari на iOS.

Пример конфига

server {
    listen 80;

    location / {
        access_log /var/log/nginx/access.log;
        if ($http_user_agent ~* "MSIE") {
            return 403;  # Deny access to Internet Explorer users
        }
        # other configuration...
    }
}

Описание

Переменная $http_referer используется в NGINX для доступа к значению HTTP‑заголовка запроса 'Referer', который указывает URL веб‑страницы, ссылающейся на запрашиваемый ресурс. Эта переменная помогает определить, откуда приходят посетители, позволяя администраторам сервера выполнять логику на основе исходных страниц. Например, если сайт предлагает бонусы за рефералов, он может использовать эту переменную для отслеживания того, приходят ли пользователи с партнёрского сайта. Значение $http_referer устанавливается на основе HTTP‑заголовков, отправленных браузером. Если браузер не отправляет заголовок Referer (что может происходить из‑за настроек конфиденциальности пользователя), переменная будет пустой. Типичные значения этой переменной — URL‑адреса веб‑сайтов, но она также может отсутствовать в защищённых контекстах или при перенаправлениях между разными протоколами (например, из HTTPS в HTTP). Поэтому важно обрабатывать возможное отсутствие этой переменной в ваших конфигурациях или скриптах, чтобы избежать непредвиденного поведения. Кроме того, необходимо обеспечивать корректную санитизацию при использовании этой переменной для таких целей, как логирование или принятие решений, так как она может быть подделана клиентами. Эта переменная обычно применяется в правилах контроля доступа, логирования или перенаправления, позволяя осуществлять детальный контроль на основе источника запроса.

Пример конфига

location /example {
    if ($http_referer ~* "example.com") {
        return 403;
    }
}

Описание

Переменная `$http_via` в NGINX используется для доступа к значению заголовка 'via' из HTTP-запроса. Этот заголовок обычно добавляют веб‑прокси, чтобы указать промежуточные серверы, через которые прошёл запрос, что даёт представление о маршрутизации запроса и задействованных механизмах кэширования. Когда клиент отправляет запрос через один или несколько прокси, заголовок 'via' добавляется каждым прокси, конкатенируя информацию и позволяя нижестоящим серверам анализировать путь запроса. Установка этой переменной происходит автоматически при обработке NGINX заголовков входящих запросов. Если заголовок 'via' присутствует, `$http_via` будет содержать его значение, которое может включать несколько фрагментов информации, если запрос проходил через несколько прокси. Типичные значения этого заголовка могут включать сведения о программном обеспечении прокси‑сервера и его версии. Если в запросе нет заголовка 'via', переменная будет пустой, что позволяет использовать условную логику в конфигурации сервера на основе наличия этого заголовка.

Пример конфига

server {
    listen 80;
    location / {
        if ($http_via) {
            add_header X-Proxy-Server $http_via;
        }
        proxy_pass http://backend;
    }
}

Описание

Переменная $http_x_forwarded_for в NGINX используется для извлечения значения HTTP-заголовка X-Forwarded-For, который обычно добавляют прокси в цепочке запросов, чтобы указать исходный IP-адрес клиента. Когда запрос проходит через один или несколько прокси, исходный IP клиента включается в этот заголовок, что позволяет принимающему серверу получить эту информацию. В нём может содержаться один IP-адрес или список IP, разделённых запятыми, которые представляют адрес клиента и любые последующие прокси, обрабатывавшие запрос. Обычно заголовок X-Forwarded-For имеет значение, похожее на: "203.0.113.195" — пример прямого IP, или "203.0.113.195, 198.51.100.0" — если в цепочке были прокси. При настройке NGINX эту переменную можно использовать в логах доступа, условных конфигурациях или проверках безопасности для разрешения или запрета доступа на основе исходного адреса клиента. Важно убедиться, что любая конфигурация корректно обрабатывает значения входящих заголовков, особенно если в цепочке запросов находится несколько прокси, чтобы избежать неправильного определения IP клиента. NGINX установит эту переменную только в том случае, если клиент отправил заголовок X-Forwarded-For. Она может быть особенно полезна в окружениях с балансировкой нагрузки, где нескольким бэкенд-серверам необходимо определить реальный IP клиента. Пользователям следует учитывать, что этот заголовок легко подделать, если не применены соответствующие меры безопасности, поэтому в сценариях, где безопасность важна, необходима валидация.

Пример конфига

http {
    log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "http://$http_x_forwarded_for"';
    access_log /var/log/nginx/access.log custom;

    server {
        listen 80;
        server_name example.com;

        location / {
            # Use $http_x_forwarded_for for access control
            if ($http_x_forwarded_for ~* '203.0.113.195') {
                return 403;
            }
            proxy_pass http://backend_servers;
        }
    }
}

Описание

В NGINX переменная $http_cookie используется для доступа к значению заголовка Cookie, отправленного клиентами в их HTTP-запросах. Эта переменная устанавливается NGINX во время обработки запроса, когда он встречает клиентский заголовок Cookie. Как правило, $http_cookie содержит строку пар имени-значения для каждого cookie, при этом пары разделяются точкой с запятой. Например, если запрос включает 'Cookie: user_id=12345; session_token=abcde;', то $http_cookie вернёт 'user_id=12345; session_token=abcde'. Переменная особенно полезна для веб-приложений, которые полагаются на cookies для управления сессиями, отслеживания состояний пользователей или персонализации контента на основе пользовательских предпочтений. К ней можно обращаться в различных контекстах, таких как server, location или if directives. При использовании этой переменной важно помнить, что её вывод может варьироваться в зависимости от cookies, установленных в браузере клиента, и от того, разрешены ли они или изменяются ли какими-либо соответствующими директивами в конфигурации NGINX. Поскольку cookies могут содержать конфиденциальную информацию, рекомендуется осторожно обращаться с этой переменной, чтобы избежать непреднамеренного раскрытия данных в логах или сообщениях об ошибках, а также обеспечить соблюдение флагов secure и HTTP-only для cookie в логике приложения.

Пример конфига

location / {
    if ($http_cookie ~* "session_id") {
        # Logic that depends on the session_id cookie
    }
}

Описание

Переменная $content_length в NGINX содержит длину тела запроса, указанную в HTTP‑заголовке 'Content-Length'. Она задаётся только для запросов, в которых этот заголовок присутствует, обычно при методах POST и PUT. Если клиент не отправил заголовок 'Content-Length', переменная будет пустой. Эта переменная в первую очередь полезна для обработки запросов с известным размером содержимого, позволяя применять условную логику в зависимости от размера поступающих данных. При обработке запросов NGINX устанавливает $content_length после разбора заголовков входящего запроса. Если заголовок 'Content-Length' указан, переменная будет содержать числовое значение; однако если заголовок отсутствует или имеет неверный формат, $content_length не будет отражать корректный размер. На практике допустимые значения этой переменной — строго неотрицательные целые числа, указывающие количество байт в теле запроса. Разработчики часто используют эту переменную для установки ограничений по размеру, логирования размеров запросов или условной обработки больших полезных нагрузок более эффективно.

Пример конфига

http {
    server {
        listen 80;

        location /upload {
            if ($content_length > 10000) {
                return 413;  # Request entity too large
            }
        }
    }
}

Описание

Переменная $content_type в NGINX автоматически устанавливается при обработке ответа и отражает заголовок Content-Type этого ответа. Как правило, она используется для указания медиатипа возвращаемого ресурса в формате, определённом RFC 6838. Частые значения включают 'text/html' для HTML-документов, 'application/json' для JSON-ответов и 'image/png' для PNG-изображений. Эта переменная устанавливается в фазе обработки запроса и может быть изменена различными директивами, которые влияют на ответ, такими как 'add_header', 'default_type' и 'types'. Когда NGINX отдаёт статические файлы, Content-Type определяется на основе расширения файла и настроек конфигурации, заданных в блоке 'http' или в конкретных контекстах 'server' или 'location'. Например, если запрашивается файл с расширением '.html', то $content_type обычно устанавливается в 'text/html'. В случаях, когда явный тип не задан, NGINX использует значение, заданное директивой 'default_type', если оно доступно; в противном случае значение может остаться неустановленным.

Пример конфига

location /images/ {
    types {
        image/png png;
        image/jpeg jpg;
        image/gif gif;
    }
    default_type application/octet-stream;
    add_header Content-Type $content_type;
}

Описание

Переменная $host имеет ключевое значение для обработки входящих запросов, поскольку она напрямую извлекает имя хоста либо из Host request header, либо из соответствующего имени сервера, определённого в конфигурации NGINX. Когда поступает запрос, NGINX проверяет заголовок Host; если он присутствует, значение этого заголовка используется для установки переменной $host. Если заголовок отсутствует, NGINX возвращается к использованию имени сервера, настроенного в server block, который обработал запрос. Это поведение позволяет NGINX корректно отвечать на запросы, адресованные разным доменам или поддоменам, которые указывают на один и тот же экземпляр сервера. Этой переменной обычно присваиваются значения, соответствующие доменным именам или IP-адресам, к которым обращаются клиенты. Например, если пользователь запрашивает "http://example.com/path", переменная $host будет содержать "example.com". Если в запросе не указан hostname и в server block определён default server, $host будет хранить имя этого сервера. Важно отметить, что если NGINX настроен с несколькими server blocks для разных hostnames, значение $host может быть критичным для маршрутизации запросов в правильный блок на основе входящего URL. Переменная $host также может вести себя по-разному в зависимости от наличия директивы server_name. Если настроенные имена серверов для server block включают wildcards или regex, фактическое значение $host может зависеть от конкретного совпадения, найденного в процессе обработки запроса. Это обеспечивает корректную обработку запросов на основе конкретных hostnames, позволяя реализовывать мультиарендные конфигурации на одном экземпляре сервера NGINX.

Пример конфига

server {
    listen 80;
    server_name example.com;

    location / {
        return 200 "Host is: $host";
    }
}

Описание

Переменная $binary_remote_addr в NGINX используется для получения двоичного формата IP-адреса клиента, связанного с запросом. Эта переменная особенно полезна в конфигурациях управления доступом и фильтрации. При получении запроса NGINX извлекает IP-адрес клиента и преобразует его в 32-bit или 128-bit двоичный формат, в зависимости от того, использует ли клиент IPv4 или IPv6, соответственно. Используя эту переменную, системные администраторы могут эффективно сравнивать и сопоставлять IP-адреса в различных настройках контроля доступа, таких как 'allow' и 'deny'. Как правило, эта переменная устанавливается во время начальной обработки запроса, где она заполняется из структуры 'sockaddr', содержащей информацию об адресе клиента. Двоичное представление упрощает выполнение быстрых сравнений и проверок списков разрешённых или запрещённых IP-адресов без необходимости постоянного преобразования форматов. Благодаря тому, что она имеет двоичную форму, эта переменная значительно более эффективна для NGINX при обработке директив управления доступом, особенно в сценариях с высокой пропускной способностью.

Пример конфига

http {
    server {
        location / {
            deny 192.168.1.1;
            allow all;
        }
    }
}

Описание

Переменная $remote_addr заполняется NGINX, когда клиент делает запрос к серверу. Она получает IP-адрес клиента непосредственно из информации о сокете запроса, в частности из `struct sockaddr`, связанной с соединением. Эта переменная необходима для сценариев управления доступом и ведения логов, когда знание исходного IP запроса может определять поведение ответа или фиксировать источник для аудита. Если сервер NGINX находится за обратным прокси или балансировщиком нагрузки, значение $remote_addr может требовать дополнения другими переменными, такими как $http_x_forwarded_for, чтобы точно отразить исходный исходный IP клиента. В стандартной конфигурации значение обычно представляет собой IPv4- или IPv6-адрес, соответственно в стандартной точечно-десятичной записи или в записи, разделённой двоеточиями. При использовании этой переменной в настройках управления доступом (например, с директивами allow/deny) сервер может принимать решения в реальном времени на основе IP-адресов клиентов, повышая безопасность за счёт разрешения или блокировки доступа для конкретных IP. Гибкость этой переменной делает её фундаментальным элементом как в настройках безопасности, так и в конфигурации аналитики внутри NGINX.

Пример конфига

location / {
    deny 192.168.1.0/24;
    allow all;
    access_log /var/log/nginx/access.log combined;
}

Описание

Переменная $remote_port — встроенная переменная NGINX, которая фиксирует номер TCP-порта, с которого клиент установил соединение с сервером. Она в первую очередь полезна для логирования и организации контроля доступа на основе исходного порта запросов. Эта переменная устанавливается в процессе обработки запроса, конкретно когда NGINX обрабатывает входящее соединение и инициализирует структуру запроса, где сохраняются различные сведения, связанные с клиентом. Когда клиент подключается к серверу, удалённый порт устанавливается операционной системой и становится доступным для NGINX. В типичном сценарии этот номер порта может находиться в диапазоне от 1024 до 65535, так как порты в диапазоне 1-1023 зарезервированы для известных служб. Он также может часто меняться, поскольку клиенты могут подключаться из разных приложений или окружений, из-за чего присваиваются разные номера портов. NGINX использует эту переменную в директивах, например для логирования через директиву 'log_format', а также в правилах контроля доступа, разрешая или запрещая запросы на основе диапазонов исходных портов.

Пример конфига

server {
    listen 80;
    location / {
        access_log /var/log/nginx/access.log 'Client IP: $remote_addr, Port: $remote_port';
    }
}

Описание

Переменная $proxy_protocol_addr является частью поддержки PROXY protocol в NGINX, которая позволяет передавать исходный IP-адрес клиента через прокси-сервер. Когда клиент подключается к серверу NGINX, у которого включена поддержка PROXY protocol, NGINX может разобрать заголовок PROXY protocol, отправленный прокси, и извлечь исходный адрес клиента. Это позволяет NGINX корректно логировать запросы с фактическим IP-адресом клиента вместо IP-адреса прокси, который в противном случае был бы записан в лог. Эта переменная обычно используется в конфигурациях, где NGINX настроен за балансировщиками нагрузки или обратными прокси, реализующими PROXY protocol. Переменная заполняется только когда входящее соединение содержит соответствующий заголовок PROXY protocol; в противном случае она обычно возвращает пустое значение. Клиенты, подключающиеся напрямую к NGINX, не будут получать преимуществ от этой переменной, и она покажет IP последнего прокси. Как правило, она будет содержать либо IPv4, либо IPv6 адрес, в зависимости от типа соединения клиента.

Пример конфига

server {
    listen 80 proxy_protocol;
    location / {
        proxy_pass http://backend;
        add_header X-Real-IP $proxy_protocol_addr;
    }
}

Описание

Переменная $proxy_protocol_port используется в NGINX для получения номера порта, указанного в заголовке PROXY protocol для проксированных подключений. Она особенно актуальна в конфигурациях, где NGINX выступает в роли обратного прокси или балансировщика нагрузки, позволяя серверу точно определить исходный порт, с которого было установлено клиентское соединение. Эта информация может быть критически важна для ведения логов, мер безопасности или принятия решений на стороне бэкенда. Эта переменная устанавливается только тогда, когда PROXY protocol включён в upstream-блоке сервера. Если PROXY protocol не используется, переменная не будет содержать корректного значения и фактически примет значение 0. Типичными значениями этой переменной являются исходные номера портов, такие как 80 или 443 для HTTP и HTTPS трафика. Использование $proxy_protocol_port даёт более полное представление о входящем запросе, что особенно полезно в многоуровневых архитектурах, где обработка на бэкенде может зависеть от исходного клиентского порта.

Пример конфига

server {
    listen 80 proxy_protocol;
    location / {
        add_header X-Proxy-Port $proxy_protocol_port;
    }
}

Описание

Переменная $proxy_protocol_server_addr преимущественно используется в конфигурациях, связанных с proxy protocol — функцией, которая позволяет NGINX получать исходный IP-адрес и порт клиента при обработке запросов, проксируемых через другой уровень (например, AWS ELB или другие обратные прокси). Эта переменная заполняется, когда proxy protocol включён в блоке server или location с помощью директивы 'proxy_protocol'. Её значение отражает IP-адрес клиента, декодированный из заголовка proxy protocol, что делает её необходимой для точного ведения логов или контроля доступа на основе реального адреса клиента, а не адреса непосредственного прокси. Когда эта переменная установлена, это может значительно повысить точность метрик и логов, поскольку можно отслеживать реальные адреса клиентов вместо IP-адреса обратного прокси. Если proxy protocol не используется или настроен неверно, значение $proxy_protocol_server_addr будет пустой строкой. Поэтому часто эту переменную используют в сочетании с другими proxy-переменными, чтобы гарантировать корректное фиксирование информации об исходном клиенте.

Пример конфига

server {
    listen 80 proxy_protocol;
    location / {
        access_log /var/log/nginx/access.log '$proxy_protocol_server_addr';
    }
}

Описание

Переменная $proxy_protocol_server_port используется в конфигурациях NGINX для получения номера порта, который сервер получил из заголовка PROXY protocol. Эта переменная особенно актуальна, когда PROXY protocol включен, поскольку позволяет NGINX определить, находится ли он за прокси, который пересылает информацию о подключении клиента. При обработке запроса, если PROXY protocol активирован через директиву 'proxy_protocol on' внутри server block, номер порта сервера будет динамически устанавливаться на основе данных о входящем соединении, передаваемых прокси. Например, если запрос приходит на порт 80, то это значение вы получите при обращении к $proxy_protocol_server_port. Эта переменная может быть очень полезна для настройки завершения SSL или для корректной перенаправки трафика на основе исходного порта, использованного для соединения до любых преобразований. Она может иметь типичные значения, такие как '80' для HTTP или '443' для соединений HTTPS, в зависимости от конфигурации и поведения пересылки прокси-сервера.

Пример конфига

server {
    listen 80 proxy_protocol;
    location / {
        return 200 "Server port: $proxy_protocol_server_port";
    }
}

Описание

Переменные $proxy_protocol_tlv_ — это префиксные переменные в NGINX, которые позволяют извлекать конкретные данные в формате Type-Length-Value (TLV) при использовании Proxy Protocol. Этот протокол, часто применяемый в сценариях балансировки нагрузки, передаёт информацию о соединении (например, IP-адреса клиентов) от прокси-сервера к бэкенд-серверу в структурированном виде. Каждый фрагмент данных TLV может быть получен с помощью суффикса, идентифицирующего конкретную запрашиваемую информацию. Эти переменные обычно устанавливаются, когда NGINX настроен на приём Proxy Protocol от прямого клиентского соединения, например при получении трафика от балансировщика нагрузки или прокси-сервера, который также реализует этот протокол. Типичные типы TLV могут включать сведения, такие как адреса клиентов, номера портов и другие заголовочные данные. Эта дополнительная функциональность позволяет бэкенд-серверам принимать более обоснованные решения на основе данных клиента, которые обычно недоступны из-за NAT или других сетевых схем, скрывающих настоящий IP клиента. Например, если элемент TLV указан с суффиксом, соответствующим информации об адресе клиента, переменная вернёт соответствующие данные, отправленные прокси. Если соответствующие данные TLV не предоставлены вышестоящим прокси-сервером, переменная будет пустой или не установлена. Такое поведение особенно полезно в сценариях, требующих точного логирования трафика или настройки поведения на основе данных исходного клиента, что улучшает общую производительность приложения и опыт пользователя.

Пример конфига

server {
    listen 80 proxy_protocol;

    location / {
        default_type text/plain;
        return 200 "Client IP: $proxy_protocol_tlv_client_ip\n";
    }
}

Описание

Переменная `$server_addr` является частью модуля NGINX Core и предоставляет фактический IP-адрес сервера, который отвечает на запрос. Эта переменная устанавливается в процессе обработки запроса, в частности в контексте TCP/IP коммуникации, что позволяет ей отражать адрес, к которому подключился клиент. Если у сервера несколько IP-адресов или он находится за балансировщиком нагрузки, `$server_addr` будет представлять основной адрес, который NGINX использует для ответа на входящие клиентские запросы. Эта переменная особенно полезна для логирования или формирования заголовков ответа. Стоит отметить, что `$server_addr` отражает адрес, с которого был обработан запрос, и определяется до передачи запроса в любые `location` блоки или обработчики. В сценариях, когда NGINX работает без конкретно привязанного IP сервера (например, в контейнеризированной среде, где IP-адрес может изменяться), для этой переменной может потребоваться соответствующая настройка, чтобы она всегда возвращала корректный адрес. Обычно она возвращает либо адрес IPv4, либо IPv6, в зависимости от конфигурации сервера и характера клиентских запросов.

Пример конфига

server {
    listen 80;
    server_name example.com;
    location / {
        add_header X-Server-IP $server_addr;
        # other configurations
    }
}

Описание

Переменная $server_port в NGINX динамически устанавливается во время обработки запроса и отражает порт, на котором сервер прослушивает входящие соединения. Она особенно полезна при настройке ответов, которые могут различаться в зависимости от номера порта, например при включении определённых заголовков ответа или применении правил брандмауэра. Переменная учитывает как порт, указанный в конфигурации, так и порт, использованный клиентом для инициирования запроса, что обеспечивает ясность в конфигурациях с несколькими портами. Эта переменная обычно устанавливается при определении блока server в файле конфигурации NGINX. Например, если блок server настроен на прослушивание порта 80, любые запросы, поступающие на этот порт, установят значение переменной $server_port равным 80. Напротив, если блок server прослушивает альтернативный порт, например 443 (обычно используемый для HTTPS), переменная отразит это значение. Благодаря этому $server_port является необходимой при создании конфигураций, которые полагаются на различение, например, трафика HTTP и HTTPS, а также при управлении приложениями, работающими на нестандартных портах. Типичные значения $server_port включают 80 для HTTP, 443 для HTTPS или любой другой пользовательский порт. Переменная не включает протокол (HTTP/HTTPS), а фокусируется исключительно на номере порта, обеспечивая гибкость и точность для различных конфигураций сервера.

Пример конфига

server {
    listen 80;
    server_name example.com;

    location / {
        add_header X-Server-Port "$server_port";
    }
}

Описание

Переменная $server_protocol в NGINX динамически устанавливается во время обработки запроса и возвращает версию протокола, которую клиент использовал для подключения к серверу. Эта переменная особенно полезна для логирования, условных конфигураций и обработки ответов, поскольку она позволяет различать разные версии протокола, такие как HTTP/1.0, HTTP/1.1 или HTTP/2.0. Обычно переменная устанавливается на фазе запроса сервера и становится доступной в различных контекстах, включая http, server и location-блоки. Когда запрос поступает на NGINX-сервер, модуль анализирует сведения о входящем запросе и соответственно заполняет переменную $server_protocol. Типичными значениями являются строки, такие как "HTTP/1.1", "HTTP/2" и т.д., но переменная отражает точный протокол, согласованный в процессе установления соединения с клиентом. Понимание переменной $server_protocol важно для разработчиков и системных администраторов, так как она может служить основой для политик безопасности или переключателей функциональности. Например, вы можете захотеть разрешать или запрещать доступ в зависимости от того, было ли соединение установлено по HTTPS или HTTP. Логирование протокола также может дать ценные сведения для анализа производительности и безопасности.

Пример конфига

server {
    listen 80;
    server_name example.com;

    location / {
        add_header X-Protocol $server_protocol;
    }
}

Описание

Переменная $scheme необходима для определения протокола, с помощью которого клиент инициировал запрос к серверу. Она проверяет, было ли соединение с сервером NGINX установлено по HTTPS или HTTP. Если запрос выполнен по HTTPS, переменная $scheme вернёт 'https', а для HTTP-запросов она вернёт 'http'. Эта переменная обычно устанавливается в процессе обработки запроса в ядре NGINX, и её значение определяется наличием или отсутствием действительного SSL-сертификата на сервере. Поэтому, если SSL настроен и запрос защищён, переменная устанавливается в 'https'. В противном случае по умолчанию используется 'http'. Также важно отметить, что скрипты, редиректы или другие параметры конфигурации часто используют эту переменную для формирования корректных URL в выводе ответов или HTTP-заголовках. Например, при перенаправлении пользователя или динамической генерации ссылок использование переменной $scheme гарантирует, что ссылки будут ссылаться на соответствующий протокол в зависимости от того, как пользователь получил доступ к серверу. Таким образом, она играет ключевую роль в средах, где одновременно могут существовать защищённый и незащищённый доступ.

Пример конфига

server {
    listen 80;
    server_name example.com;

    location / {
        return 301 $scheme://www.example.com$request_uri;
    }
}

Описание

Переменная $https — встроенная переменная в NGINX, которая используется для определения, обрабатывается ли текущий запрос по HTTPS. Когда запрос обрабатывается по защищённому соединению, $https устанавливается в 'on'. Если запрос не защищён (т.е. обслуживается по HTTP), эта переменная возвращает 'off'. Эта переменная особенно полезна для перенаправления HTTP-трафика на HTTPS или для настройки условных ответов в зависимости от безопасности соединения. Значение переменной $https, как правило, устанавливается, когда NGINX настроен с корректным SSL-сертификатом и прослушивает HTTPS-порты. Например, если блок server в NGINX указывает SSL-сертификат и прослушивает порт 443, $https будет установлен в 'on' для входящих запросов в этом блоке. И наоборот, если нет конфигурации SSL и сервер прослушивает порт 80, переменная будет 'off'. Важно отметить, что эта переменная принимает только значения 'on' или 'off'.

Пример конфига

server {
    listen 443 ssl;
    server_name example.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        if ($https = off) {
            return 301 https://$host$request_uri;
        }
        # Handle the secure request
    }
}

Описание

Переменная $request_port в NGINX обозначает порт, на котором был получен запрос от клиента. Эта переменная устанавливается во время обработки запроса и получается из сведений о соединении клиента, указанных в заголовке запроса. Когда клиент делает HTTP или HTTPS запрос, запрос маршрутизируется в указанный серверный блок на основе критериев сопоставления, которые включают номер порта. Для стандартных HTTP-запросов это обычно порт 80, а для HTTPS — порт 443. Если запрос сделан через нестандартный порт, $request_port отразит этот конкретный номер порта. Например, если клиент подключается к порту 8080, то значение $request_port будет "8080". Важно отметить, что при использовании таких протоколов, как HTTP/2, порт может определяться динамически, но NGINX по-прежнему зафиксирует и отразит номер порта, использованный для этого соединения, в переменной $request_port. Осведомлённость об этом значении может быть полезна для логирования, условной конфигурации или при переписывании URL на основе полученного порта.

Пример конфига

server {
    listen 80;
    location / {
        return 200 "Request received on port: $request_port";
    }
}

Описание

The `$is_request_port` variable is used to determine if the incoming HTTP request was made on a non-standard port, allowing the server to differentiate between requests made on the standard ports (80 for HTTP and 443 for HTTPS) and those made on alternate ports. This variable is evaluated during the request processing phase, specifically when the request is being parsed and before it reaches any handlers. Когда эта переменная установлена, она содержит значение '1', если запрос был сделан на альтернативном порту, и '0', если он был сделан на стандартных портах HTTP или HTTPS. Это особенно полезно в ситуациях, когда приложениям нужно применять определённые конфигурации, логирование или правила доступа в зависимости от порта, с которого пришёл запрос. Переменная автоматически инициализируется NGINX на основе информации о сокете входящего запроса и не требует ручной настройки. Разработчики часто используют эту переменную в сочетании с директивами контроля доступа или в условных блоках, чтобы предоставлять адаптированные ответы или вести логирование в зависимости от того, был ли запрос сделан на стандартный или нестандартный порт, тем самым повышая контроль над поведением сервера исходя из запросов клиентов.

Пример конфига

server {
    listen 8080;
    location / {
        if ($is_request_port) {
            return 403;  # Deny access from non-standard ports
        }
        # Other configurations...
    }
}

Описание

Переменная $request_uri — ключевая переменная в NGINX, которая содержит полный URI, запрошенный клиентом. Это включает как путь, так и строку запроса, если она присутствует. Она устанавливается во время обработки запроса, конкретно в момент чтения NGINX строки запроса от клиента, что позволяет сформировать ответ на основе этого URI. Эта переменная важна для маршрутизации запросов, формирования логов и выполнения перенаправлений или перезаписей по необходимости. Типичные значения $request_uri могут быть путями, такими как "/products/item?id=123" или "/api/v1/users", где первый содержит строку запроса, а второй — нет. Это делает $request_uri полным способом ссылаться на точный запрос с точки зрения пользователя. Она часто используется вместе с другими переменными для логирования запросов, контроля доступа и оптимизации поведения ответов в зависимости от типа или параметров запроса.

Пример конфига

location /api {
    if ($request_uri ~* "/products") {
        # Handle product requests
        proxy_pass http://backend;
    }
}

location / {
    log_format main '$remote_addr - $remote_user [$time_local] "$request $request_uri" $status $body_bytes_sent';
    access_log /var/log/nginx/access.log main;
}

Описание

Переменная $uri устанавливается во время обработки HTTP-запроса в NGINX и в основном заполняется неэкранированным request URI, который является частью URL, следующей за доменом и протоколом. Эта переменная может включать путь и query string запрашиваемого ресурса, но не будет содержать дополнительных модификаций, внесённых server или location директивами. Значение $uri определяется на раннем этапе обработки запроса, обычно когда NGINX разбирает клиентский запрос. Это означает, что оно отражает исходное значение, отправленное клиентом, до любых внутренних rewrites или redirects. При использовании в конфигурации сервера переменная $uri позволяет принимать решения на основе фактически запрошенного ресурса. Она особенно полезна в location blocks для контроля доступа, логирования или перенаправления трафика. Значение обычно представляет собой строку, описывающую путь к файлу или маршрут, и может иметь формат '/images/photo.jpg' или '/api/v1/users'. Следует отметить, что если запрос обрабатывался в другом location block, который переписал URI, переменная $uri отразит это изменение.

Пример конфига

location /images {
    alias /var/www/images;
    error_page 404 = /404.html;
}

location /api/v1 {
    proxy_pass http://backend;
    access_log /var/log/nginx/api_access.log;
    if ($uri ~* /user/(\d+)) {
        # Do something specific for user URIs
    }
}

Описание

Переменная $document_uri устанавливается в процессе обработки запроса в NGINX и представляет ту часть URI, которая используется для идентификации запрашиваемого ресурса. В отличие от переменной $request_uri, которая включает строку запроса, $document_uri содержит исключительно путь URI, что делает её пригодной в сценариях, где строка запроса не нужна. Эта переменная особенно полезна при документировании или журналировании обращений к URI на сервере, позволяя отслеживать целевые запросы ресурсов без влияния параметров строки запроса URL. Значение $document_uri определяется после того, как запрос был обработан системой маршрутизации NGINX, конкретно в контексте location. Это означает, что оно может отражать решения NGINX относительно переписывания URI или использования определённых location-блоков. Типичные значения $document_uri могут варьироваться от простых путей, таких как "/index.html", до структурированных URI, таких как "/products/item123". Любые процентно-кодированные символы в URI декодируются для получения более чистого и удобочитаемого вывода при использовании этой переменной. Использование этой переменной в access logs, rewrites или условных выражениях может упростить конфигурацию, особенно когда требуются конкретные действия на основе запрашиваемого ресурса. Например, форматы логов могут включать $document_uri, чтобы отслеживать, какие документы запрашиваются чаще всего.

Пример конфига

log_format mylog '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$document_uri"';

access_log /var/log/nginx/access.log mylog;

Описание

Переменная `$request` в NGINX устанавливается в процессе обработки HTTP-запроса и захватывает всю строку запроса, которая включает HTTP-метод (GET, POST и т.д.), запрошенный URI и версию протокола HTTP (HTTP/1.1, HTTP/2 и т.д.). Эта переменная заполняется, когда NGINX начинает обрабатывать запрос, и используется в различных контекстах для предоставления подробной информации о обрабатываемом запросе. Как правило, её значение выглядит как 'GET /index.html HTTP/1.1' или 'POST /api/v1/resource HTTP/2'. Переменная `$request` особенно полезна для ведения логов или для настройки ответов на основе конкретных HTTP-методов или запрошенных URI. Например, анализируя содержимое переменной `$request`, можно разработать правила сервера для условного переписывания URL, логирования паттернов доступа или даже применения политик безопасности в зависимости от метода запроса. Следует отметить, что после того, как запрос был обработан и ответ сгенерирован, переменная `$request` сохраняет состояние запроса таким, каким оно было при первоначальном получении, без изменений в результате последующей обработки или внутренних действий.

Пример конфига

http {
    log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent';
    access_log /var/log/nginx/access.log custom_format;
}

Описание

Переменная $document_root в NGINX предоставляет путь в файловой системе к корневому каталогу, из которого для данного запроса обслуживаются файлы. Этот каталог обычно задаётся в server- или location-блоке с помощью директивы `root`. Её значение определяется наиболее конкретной директивой `root`, применимой к текущему запросу. Если директива `root` присутствует и в server-блоке, и в location-блоке, значение более специфичного location-блока будет иметь приоритет. Эта переменная полезна для построения путей к файлам, особенно в сочетании с другими переменными, такими как `$uri` или `$request_filename`. Когда NGINX обрабатывает входящие запросы, он разбирает конфигурацию и назначает соответствующий корневой каталог на основе совпавшей location-директивы. Если `root` не задан, переменная вернёт пустую строку, что может привести к ошибкам при использовании в конфигурациях, ожидающих действительный путь. Важно отметить, что если server-блок задаёт директиву `root` и не существует конкретного location-блока с директивой `root`, все запросы, соответствующие этому серверу, будут использовать корневой каталог из server-блока. Переменная часто используется в различных директивах NGINX, включая `try_files`, `rewrite` и `alias`, чтобы изменить способ обработки запросов в зависимости от определённой структуры файлов.

Пример конфига

server {
    listen 80;
    server_name example.com;
    root /var/www/example.com;

    location / {
        try_files $uri $uri/ =404;
    }
}

location /images/ {
    root /var/www/images;
}

# Example usage in a log: 
access_log /var/log/nginx/access.log "[$document_root]";

Описание

Переменная $realpath_root в NGINX предоставляет абсолютный путь к корневому каталогу текущего блока location для конкретного запроса, проходя через все символические ссылки. При обработке запроса NGINX сопоставляет запрошенный URI с настроенным document root, который определяется с помощью директив root или alias. Если указанный корневой каталог является символической ссылкой, NGINX разрешит её до фактического физического местоположения в файловой системе, обеспечивая точность пути и исключая указание на битые символические ссылки. Эта переменная особенно полезна в конфигурациях, где для обслуживания файлов используются директории, связанные через символические ссылки, поскольку она гарантирует использование корректного пути при проверках безопасности или при операциях с файлами. Она устанавливается во время фазы обработки запроса, когда NGINX анализирует блок конфигурации, обрабатывающий запрос. Типичные значения для $realpath_root включают такие пути, как '/var/www/html' или '/usr/share/nginx/html' в зависимости от пользовательских настроек в соответствующих контекстах `server` или `location`.

Пример конфига

location /images/ {
    alias /var/www/data/images/;
    try_files $uri $uri/ =404;
}

location = /images/logo.png {
    internal;
    root /var/www;
    error_page 404 = @fallback;
}

# Use of $realpath_root
add_header X-Realpath-Root $realpath_root;

Описание

Переменная `$query_string` в NGINX захватывает строку запроса из URI запроса клиента. Строка запроса — это часть URL, которая следует за символом '?' и обычно содержит параметры и их значения. Например, в URL `http://example.com/index.html?name=John&age=30` строка запроса — `name=John&age=30`. Эта переменная автоматически заполняется NGINX при получении запроса и может использоваться в различных контекстах, в частности внутри location blocks, где применяется условная логика. Эта переменная полезна для реализации логики, зависящей от конкретных параметров, переданных в строке запроса. Например, вы можете использовать `$query_string` в rewrites, для контроля доступа или в настройках логирования, чтобы направлять запросы в зависимости от их параметров. Важно отметить, что эта переменная представляет собой простую строковую форму строки запроса и не выполняет её разбор; разбор должен осуществлять администратор, если требуется более тонкое управление самими параметрами.

Пример конфига

location /search {
    if ($query_string ~* "keyword=(.*)") {
        set $search_keyword $1;
        add_header Search-Keyword "$search_keyword";
    }
}

Описание

В NGINX переменная $args используется для получения строки запроса из URL входящего запроса. Она включает любые параметры, передаваемые в URL после символа '?'. Например, в URL вида 'http://example.com/page?name=John&age=30' переменная $args вернёт 'name=John&age=30'. Переменная $args автоматически заполняется при обработке HTTP-запроса NGINX, поэтому она доступна в нескольких контекстах, включая блоки server или location, а также в директивах, принимающих переменные. Важно отметить, что если в строке запроса отсутствуют аргументы, значение $args будет пустой строкой. Кроме того, эту переменную следует использовать осторожно, чтобы случайно не раскрыть конфиденциальную информацию, которая может содержаться в строке запроса.

Пример конфига

location /search {
    if ($args) {
        set $search_query $args;
        # Log or handle the search query
        access_log /var/log/nginx/search.log;
    }
}

Описание

Переменная $is_args в NGINX возвращает строку, которая либо пустая, либо содержит одиночный знак вопроса ('?'). Она указывает на наличие параметров строки запроса в URI для текущего запроса. Когда есть параметры запроса (например, '/path?arg=value'), переменная $is_args будет оцениваться как '?', что может быть полезно при построении перенаправлений или правил перезаписи, которые сохраняют строку запроса в целевом URI. Переменная устанавливается во время обработки запроса в жизненном цикле обработки запросов NGINX. Если URI запроса не содержит параметров, $is_args будет пустой строкой. Напротив, если запрос содержит параметры, такие как 'arg1=value1&arg2=value2', NGINX установит $is_args в '?' и только в него, независимо от присутствующих параметров. Поэтому её значение не отражает содержимое самой строки запроса, а лишь указывает на её наличие.

Пример конфига

location /example {
    if ($is_args) {
        rewrite ^ /another_example$is_args last;
    }
}

Описание

Переменная $request_filename в NGINX устанавливается во время обработки запроса и предоставляет полный путь в файловой системе к запрашиваемому ресурсу. Она формируется на основе URI запроса и директив root или alias, указанных в конфигурации. Когда выполняется запрос, NGINX объединяет путь root, определённый в соответствующем контексте, с URI, в результате чего получается абсолютный путь на сервере, где находится запрашиваемый файл или каталог. Например, если сделан запрос к '/images/logo.png' и root в блоке server установлен в '/var/www/html', то $request_filename будет '/var/www/html/images/logo.png'. Эта переменная особенно полезна для модулей, которым нужен доступ к файлам, например при обработке статических файлов, при включении пользовательских форматов логирования или при реализации условной логики с помощью директивы `try_files`. $request_filename пересчитывается для каждого контекста запроса, обеспечивая точное соответствие цели текущего запроса. Типичные сценарии использования включают логирование пути запрашиваемого файла или проверку его существования перед дальнейшей обработкой с помощью `try_files` или других директив конфигурации.

Пример конфига

location /images/ {
    root /var/www/html;
    if (!-f $request_filename) {
        return 404;
    }
}

Описание

Переменная $server_name в NGINX автоматически заполняется именем, указанным в server-блоке конфигурации. Она может соответствовать заголовку Host входящего запроса или быть явно задана в server-блоке. Значение $server_name зависит от того, как определён server-блок; оно может принимать разные формы — одиночное имя, подстановочный шаблон или регулярное выражение. Если запрос не совпадает ни с одним из server-блоков, определённых в конфигурации, переменная $server_name останется неустановленной. Эта переменная обычно используется для логирования, страниц ошибок и директив rewrite, позволяя серверу динамически настраивать ответы в зависимости от запрошенного хоста. При работе с несколькими именами сервера в одном server-блоке NGINX выполняет простой процесс сопоставления, отдавая приоритет точным соответствиям перед подстановочными шаблонами или регулярными выражениями. Чтобы эффективно использовать переменную $server_name, важно правильно сконфигурировать server-блок и убедиться, что он соответствует входящим запросам. К этой переменной также можно обращаться в логах для получения контекста об обрабатываемых запросах, что помогает при отладке и аналитике.

Пример конфига

server {
    listen 80;
    server_name example.com www.example.com;

    location / {
        root /var/www/example;
        index index.html;
    }

    error_page 404 /404.html;
    access_log /var/log/nginx/example.access.log;
    error_log /var/log/nginx/example.error.log;
}

Описание

Переменная $request_method является частью основных переменных NGINX и используется для захвата метода обрабатываемого HTTP-запроса. Эта переменная будет содержать глагол метода, такой как GET, POST, PUT, DELETE или HEAD, который указывает действие, которое клиент намерен выполнить над данным ресурсом. Это важно в сценариях, где требуется специфическая обработка типов запросов, например, различение GET и POST для разной обработки данных. Эта переменная устанавливается в фазе обработки запроса, когда NGINX разбирает входящие заголовки HTTP-запроса. Она часто используется в условных конструкциях или в настройках логирования для фиксации деталей запроса для более точной диагностики или для применения разных правил в зависимости от типа запроса. Например, некоторые конфигурации сервера могут разрешать только POST-запросы для определённых конечных точек, и использование переменной $request_method может помочь обеспечить это: ``` if ($request_method !~ ^(GET|POST)$) { return 405; } ``` Этот пример ограничивает доступ только методами GET и POST, возвращая статус 405 (Method Not Allowed) для всех остальных.

Пример конфига

location /example {
    if ($request_method = POST) {
        # Handle POST requests
    }
    if ($request_method = GET) {
        # Handle GET requests
    }
}

Описание

В NGINX переменная $remote_user устанавливается, когда сервер настроен на использование базовой аутентификации HTTP. Это происходит, когда в конфигурационном блоке используется директива `auth_basic`, в результате чего клиенту предлагается ввести имя пользователя и пароль. Имя пользователя, введённое клиентом, затем становится доступным для сервера и может быть получено через переменную $remote_user. Если клиент не прошёл аутентификацию или запрос не требует аутентификации, переменная $remote_user будет пустой. Обычно переменная $remote_user используется для логирования или для целей авторизации в конфигурациях сервера. Она может быть включена в пользовательские форматы логов, что позволяет администраторам отслеживать, кто получает доступ к определённым ресурсам. Кроме того, эта переменная может влиять на решения по управлению доступом в сочетании с условными директивами конфигурации, позволяя разрешать или запрещать доступ на основе идентификации аутентифицированного пользователя. Эта переменная особенно полезна в сценариях, где безопасность критична, например при публикации конфиденциальных данных или сервисов, доступ к которым требует идентификации пользователя. В то же время следует учитывать, что эта информация может быть конфиденциальной, и её использование в логах должно осуществляться с учётом правил приватности и безопасности, чтобы файлы доступа не раскрывали персонально-идентифицируемую информацию.

Пример конфига

http {
    server {
        listen 80;
        server_name example.com;

        location / {
            auth_basic "Restricted Area";
            auth_basic_user_file /etc/nginx/.htpasswd;
            access_log /var/log/nginx/access.log combined;
            
            # Include the remote_user in the log
            log_format combined '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';
        }
    }
}

Описание

Переменная $bytes_sent в NGINX отслеживает общее количество байт, переданных клиенту в ходе отправки ответа. Эта переменная вычисляется на этапе обработки запроса и доступна во всех контекстах, где производится логирование. Она отражает не только само тело ответа, но и любые дополнительные отправляемые байты, такие как HTTP headers. Значение этой переменной устанавливается, когда NGINX начинает доставлять ответ клиенту, и продолжает накапливаться в процессе передачи до полного завершения отправки ответа. Обычно $bytes_sent может значительно варьироваться в зависимости от типа доставляемого контента; например, для статических файлов будет указан точный размер файла в байтах, тогда как динамически генерируемый скриптами контент может быть менее предсказуемым. Кроме того, и могут влиять на сообщаемый размер из-за различий в длине содержимого, headers и сжатии. В целом разработчики и системные администраторы используют эту переменную преимущественно для анализа использования пропускной способности, расчёта статистики передачи и настройки производительности сервера для эффективной обработки ответов клиентам.

Пример конфига

log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $bytes_sent';
access_log /var/log/nginx/access.log main;

Описание

Переменная $body_bytes_sent является значимой метрикой, используемой при логировании и мониторинге производительности NGINX. Она фиксирует общий объём данных, отправленных клиенту, а именно байты, переданные в теле ответа. Эта переменная устанавливается в процессе обработки каждого запроса, после того как тело ответа сформировано и отправлено. Важно отметить, что переменная не учитывает отправленные заголовки, а только содержимое тела. Эта переменная особенно полезна при оценке производительности и вычислении потребления полосы пропускания. По мере обработки HTTP-запросов NGINX поддерживает аккумулятор переданных байт, который в конечном итоге даёт значение $body_bytes_sent. Типичные значения могут варьироваться от 0 (в случаях, когда запрос завершился ошибкой или тело не было отправлено) до любого произвольного размера в зависимости от характера ответа — небольшие для простых HTML-страниц или большие для загрузки файлов или потоковой передачи медиаконтента. На практике значение $body_bytes_sent помогает администраторам выявлять закономерности трафика, вовлечённость пользователей в контент и потенциальные области оптимизации в их приложениях. Логирование этой переменной позволяет анализировать использование полосы пропускания и диагностировать проблемы, связанные с медленными ответами, сопоставляя переданные байты с другими переменными, такими как время ответа и частота запросов.

Пример конфига

log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent';

access_log /var/log/nginx/access.log custom_format;

Описание

Переменная $pipe используется в сервере NGINX для определения того, обрабатывается ли запрос посредством HTTP-пайплайнинга. Пайплайнинг — это техника, при которой несколько запросов могут быть отправлены по одному соединению, что позволяет клиенту отправлять дополнительные запросы до получения ответов на предыдущие. В определённых сценариях это может повысить производительность, особенно для веб‑браузеров, отправляющих несколько запросов для одновременной загрузки ресурсов. Эта переменная доступна для ссылки в конфигурационных файлах NGINX, например в директивах, которые должны условно обрабатывать запросы в зависимости от того, используются ли пайплайнинг. При получении запроса NGINX устанавливает значение переменной $pipe соответствующим образом: оно устанавливается в "pipelined", если запрос является пайплайнингом, и не устанавливается (или возвращает пустую строку) в противном случае. Типичное использование переменной $pipe включает логирование и управление доступом или обработкой ответов на основе того, обрабатывается ли запрос как пайплайнинг. Например, можно записывать разные сообщения для пайплайнинг- и непайплайнинг‑запросов или применять разные механизмы кэширования в зависимости от значения этой переменной.

Пример конфига

http {
    log_format custom_format '[$pipe] $remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"';

    access_log /var/log/nginx/access.log custom_format;
}

Описание

Переменная $request_completion используется в NGINX для предоставления информации о состоянии обработки запроса. Эта переменная в основном устанавливается в ходе жизненного цикла запроса ядром NGINX и может принимать одно из трёх значений: 'ok', 'timeout' или 'failed'. Она особенно полезна для логирования и условной логики в конфигурациях NGINX, позволяя администраторам по-разному реагировать в зависимости от того, был ли запрос успешно завершён, истёк ли таймаут или произошла другая ошибка. Переменная обычно оценивается в процессе обработки запроса после формирования ответа или при возникновении ошибки запроса. Если сервер успешно завершил обработку запроса, значение переменной устанавливается в 'ok'. В случаях, когда запрос превышает настройки таймаута, она возвращает 'timeout', а если выполнение не удалось по другим причинам, — 'failed'. Такая детализация статуса помогает при диагностике и мониторинге производительности сервера NGINX.

Пример конфига

log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $request_completion';

access_log /var/log/nginx/access.log custom_format;

Описание

Переменная $request_body в NGINX захватывает тело запроса клиента после его обработки сервером. Она в основном заполняется, когда метод запроса обычно содержит тело, например POST или PUT. Эта переменная доступна только если обработка тела запроса 'set' или 'get' включена в конфигурации сервера, обычно через директиву proxy_pass или если клиент отправляет данные непосредственно на сервер. После установки она содержит все данные, отправленные клиентом, что делает её полезной для обработки форм, загрузки файлов или любых полезных нагрузок, отправленных в запросах. При использовании переменной $request_body важно учитывать, что тело запроса буферизуется. По умолчанию оно может быть ограничено директивой client_max_body_size, которая ограничивает размер тела, обрабатываемого и в конечном итоге сохраняемого в этой переменной. Если тело превышает этот лимит, запрос может быть отклонён, и переменная не будет содержать данные. Типичные значения для $request_body могут включать данные в формате JSON, multipart form data или простой текст, в зависимости от типа содержимого и намерения клиента.

Пример конфига

server {
    listen 80;
    server_name example.com;

    location /submit {
        # Capture the request body
        proxy_pass http://backend;
        proxy_set_header X-Request-Body $request_body;
    }
}

Описание

Переменная $request_body_file используется в случаях, когда тело HTTP-запроса превышает ограничения размера буфера NGINX. При поступлении запроса NGINX считывает тело запроса; если тело больше заранее заданного размера, оно сохраняется во временный файл на файловой системе сервера. Эта переменная затем содержит путь к этому временному файлу, что позволяет далее обрабатывать тело запроса. Переменная преимущественно устанавливается во время этапа обработки запроса, в частности, когда любой из основных обработчиков, таких как модули proxy или fastcgi, решает, что тело запроса не следует полностью держать в памяти. Типичными значениями этой переменной будут пути к файлам в файловой системе, такие как `/tmp/nginx_request_body_XXXXXX`. Временный файл обычно удаляется после завершения обработки запроса, что позволяет эффективно управлять дисковым пространством сервера. В конфигурациях, где часто обрабатываются большие полезные нагрузки (например, загрузки файлов), правильная настройка обработки тела запроса, включая размеры буферов, критически важна для обеспечения оптимальной производительности и во избежание перегрузки сервера.

Пример конфига

server {
    client_max_body_size 10M;
    location /upload {
        proxy_pass http://backend;
        proxy_request_buffering on;
        # Accessing the request body file:
        if ($request_body_file) {
            log_format custom '$remote_addr $request_body_file';
            access_log /var/log/nginx/custom.log custom;
        }
    }
}

Описание

Переменная $request_length в NGINX содержит количество байт тела запроса клиента, включая заголовки, а также любые данные, отправленные клиентом в составе запроса (обычно в POST‑запросах). Эта переменная особенно полезна для мониторинга размера входящих запросов и для применения ограничения скорости на основе размера запроса. NGINX устанавливает значение $request_length при разборе входящего запроса. Оно, как правило, заполняется в процессе обработки запросов в контекстах server и location. Зафиксированный размер — это общая длина запроса, подсчитываемая в байтах. Типичные значения этой переменной сильно различаются в зависимости от характера приложения; распространённые размеры могут варьироваться от 0 байт для простых GET‑запросов без тела до нескольких килобайт для сложных POST‑запросов, содержащих формы или загрузки файлов. Эта переменная может быть полезна в ситуациях, когда нужно реализовать меры безопасности для отклонения чрезмерно больших тел запросов или отслеживания пропускной способности, потребляемой клиентскими запросами. Администраторы могут устанавливать ограничения на основе этой переменной для оптимизации производительности сервера и эффективного управления ресурсами.

Пример конфига

http {
    server {
        listen 80;
        location /upload {
            client_max_body_size 1M;
            if ($request_length > 1048576) {
                return 413;
            }
        }
    }
}

Описание

Переменная $request_time предоставляет точную оценку времени, затраченного на обработку запроса клиента в NGINX. Эта переменная вычисляется при завершении запроса, фиксируя длительность с момента его получения до отправки ответа клиенту. Конкретно, $request_time фиксирует это время в секундах и долях секунды, что позволяет оценивать производительность и устранять проблемы с задержками в вашем приложении. Значение $request_time устанавливается в процессе обработки запроса, непосредственно перед тем как NGINX отправит ответ. Важно учитывать, что зафиксированное время может зависеть от нескольких факторов, включая сетевую задержку, время обработки на сервере и поведение клиента (например, скорость соединения). В результате типичные значения $request_time сильно различаются в зависимости от приложения и нагрузки на сервер; они могут составлять от нескольких миллисекунд до нескольких секунд, особенно при высокой нагрузке или ресурсозатратных операциях.

Пример конфига

log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" request_time: $request_time';

access_log /var/log/nginx/access.log custom;

Описание

Переменная $request_id предоставляет уникальный идентификатор для каждого входящего запроса на сервер NGINX. Этот идентификатор полезен для отслеживания запросов и ведения логов, особенно в распределённых системах или архитектурах микросервисов, где корреляция логов между несколькими сервисами помогает при отладке и мониторинге. По умолчанию, если запрос не содержит явного заголовка `X-Request-ID`, NGINX генерирует и присваивает UUID (Universally Unique Identifier) в качестве идентификатора запроса. Это означает, что каждый запрос, обрабатываемый NGINX, можно отслеживать независимо от того, указал ли клиент этот заголовок. Когда запрос достигает сервера NGINX, он может пройти несколько этапов обработки (например, аутентификация, правила доступа и т.д.), и значение $request_id остаётся неизменным на протяжении этих процессов. Важно включить эту переменную с помощью модуля `request_id`, который может отсутствовать в минимальных сборках NGINX. В случаях, когда вовлечены внешние системы или сервисы (например, API-шлюзы или балансировщики нагрузки), передача идентификатора запроса через заголовки запроса обеспечивает согласованное отслеживание на всём протяжении жизненного цикла запроса. Типичные значения $request_id имеют формат строк UUID, обеспечивая глобальную уникальность. Например, пример вывода может выглядеть как `3e4e989c-45c6-4de4-b7d6-2b4ebc4fc417`. Это делает идентификатор крайне полезным для поиска и корреляции записей логов, относящихся к одному и тому же запросу в разных компонентах или слоях системы.

Пример конфига

http {
    log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$_http_referer" "$_http_user_agent" "$request_id"';

daily_log { 
    access_log /var/log/nginx/access.log main;
    
    proxy_set_header X-Request-ID $request_id;
} 
}

Описание

Переменная $status в NGINX представляет код состояния ответа, сгенерированного сервером для текущего запроса. Она устанавливается автоматически NGINX во время обработки запроса и отражает результат обработки. К распространённым HTTP-кодам состояния относятся 200 для успешных ответов, 404 для ошибок «не найдено» и 500 для ошибок сервера, среди прочих. Эта переменная становится доступной после того, как NGINX обработает запрос и сформирует соответствующий ответ. Вы можете использовать эту переменную для различных целей, например для логирования статусов запросов или для реализации условных действий в зависимости от результата обработки запросов. Например, если запрос возвращает код 404, вы можете задействовать специфическую обработку ошибок или логирование, чтобы отслеживать, как часто пользователи сталкиваются с ошибками «страница не найдена».

Пример конфига

log_format custom '$remote_addr - $remote_user [$time_local] "${request}" $status ${body_bytes_sent} "$http_referer" "$http_user_agent"';

access_log /var/log/nginx/access.log custom;

Описание

Переменная $sent_http_content_type — это встроенная переменная NGINX, которая захватывает значение заголовка Content-Type в HTTP-ответе, отправляемом сервером. Эта переменная часто используется после формирования ответа и позволяет получить Content-Type, определённый или заданный в конфигурации сервера или во время обработки запроса. При обработке запроса NGINX определяет подходящий Content-Type на основе различных факторов, таких как расширение файла запрашиваемого ресурса, согласование содержимого или явные настройки в файлах конфигурации. После создания ответа и непосредственно перед его отправкой клиенту переменная $sent_http_content_type может быть использована для оценки или логирования исходного Content-Type. Она не определена до тех пор, пока заголовок ответа не будет сформирован, и поэтому может быть недоступна для некоторых запросов, если ответ не является действительным или не был задан. Типичные значения этой переменной могут включать стандартные MIME-типы, такие как "text/html", "application/json", "image/png" и т.д., в зависимости от содержимого, которое обслуживает NGINX. Если ответ не отправлен или Content-Type не указан, эта переменная будет пустой. Поэтому рекомендуется проверять, задана ли она, прежде чем использовать в логировании или при принятии решений.

Пример конфига

location / {
    add_header Custom-Header "$sent_http_content_type";
    proxy_pass http://backend;
}

Описание

Когда NGINX обрабатывает запрос, он собирает различные заголовки ответа, которые будут отправлены клиенту. Переменная $sent_http_content_length специально фиксирует заголовок Content-Length, который указывает размер тела ответа в байтах. Эта переменная устанавливается во время фазы обработки запроса и обычно содержит числовое значение, представляющее длину ответа, сформированного сервером, либо может быть пустой, если длина ответа неизвестна или вместо конкретного значения Content-Length используется chunked transfer encoding. Заголовок Content-Length важен для коммуникаций по HTTP/1.1, поскольку он позволяет клиенту точно знать, сколько байт ожидать в теле ответа. В сценариях, где генерируется динамический контент, NGINX может не определить длину содержимого до тех пор, пока тело полностью не будет обработано. Поэтому использование этой переменной может помочь в ситуациях, требующих специальной обработки длины ответа, например для условного логирования или изменения ответа на основе размера содержимого.

Пример конфига

server {
    listen 80;
    location / {
        add_header X-Content-Length $sent_http_content_length;
        proxy_pass http://backend;
    }
}

Описание

Переменная $sent_http_location заполняется во время внутренней переадресации в NGINX, в частности когда модуль обрабатывает запрос, который приводит к 3xx HTTP-ответу. Этой переменной присваивается значение заголовка 'Location', установленного такими директивами, как `rewrite`, `error_page` или `proxy_redirect`. Она содержит перенаправляемый URL, на который будет отправлен клиент, что особенно полезно при обработке ситуаций, когда управление доступом или логика применяются на основе вводимых пользователем данных или путей запроса. Переменная устанавливается только если происходит внутренняя переадресация на другой URI и может использоваться в разных контекстах, включая логирование конечного URL, на который перенаправлен запрос, или использование её совместно с другими переменными NGINX для расширенной логики ответа. Типичные значения включают абсолютные URL (например, "http://example.com/target") или относительные URI (например, "/target") в зависимости от того, как настроена переадресация в сервере NGINX.

Пример конфига

server {
    listen 80;
    location /example {
        return 302 /new-location;
    }
    location /new-location {
        add_header Location $sent_http_location;
        return 200 'Redirected to new location';
    }
}

Описание

Переменная $sent_http_last_modified автоматически устанавливается NGINX при обработке запроса, который включает получение ресурса. Когда NGINX отвечает на запрос и включает заголовок Last-Modified в HTTP-ответе, эта переменная фиксирует значение этого заголовка. Заголовок Last-Modified используется для указания даты и времени последней модификации ресурса, что позволяет клиентам принимать решения о кэшировании или повторном получении ресурса на основе его актуальности. Эта переменная полезна в ситуациях, когда поведение кэширования нужно тонко настраивать, или при реализации условных GET-запросов с использованием заголовка If-Modified-Since на стороне клиента. Анализируя значение $sent_http_last_modified, на стороне сервера можно реализовать логику, изменяющую заголовки или содержимое ответов в зависимости от свежести обслуживаемых ресурсов. Типичные значения этой переменной соответствуют распространённым HTTP-форматам дат, таким как 'Wed, 21 Oct 2015 07:28:00 GMT'. Обратите внимание, что если заголовок Last-Modified не отправляется, переменная будет пустой.

Пример конфига

location /example {
    add_header Last-Modified $sent_http_last_modified;
}

Описание

Переменная $sent_http_connection в NGINX фиксирует значение ответного заголовка 'Connection', который отправляется клиенту. Этот заголовок указывает клиенту, следует ли удерживать соединение с сервером открытым после обработки текущего запроса. Типичными значениями для этой переменной могут быть 'keep-alive' или 'close', в зависимости от конфигурации сервера и характера запроса клиента. Эта переменная преимущественно полезна в сценариях, когда серверу нужно динамически изменять поведение соединения на основе запроса клиента или шаблонов его использования. Например, если некоторые клиенты запрашивают постоянные соединения, сервер может отвечать соответствующим образом. Значение $sent_http_connection устанавливается в процессе обработки запроса, конкретно при формировании заголовков ответа. Присваиваемое значение определяется директивами конфигурации сервера в соответствующем контексте. Важно отметить, что если заголовок 'Connection' не указан в конфигурации или не установлен явно во время обработки, эта переменная не будет содержать никакого значения и поэтому её следует осторожно использовать в условных выражениях или в логах, чтобы избежать непреднамеренного отображения пустых заголовков.

Пример конфига

server {
    listen 80;
    location / {
        add_header Connection $sent_http_connection;
    }
}

Описание

Переменная $sent_http_keep_alive устанавливается ядром NGINX при подготовке ответа для клиента. Она отражает заголовок 'Keep-Alive', отправляемый в HTTP-ответе, который информирует клиента о том, хочет ли сервер оставить соединение открытым для нескольких HTTP-запросов или закрыть его после текущей транзакции. Эта переменная может принимать значения, такие как 'timeout=5', что указывает, как долго соединение должно поддерживаться перед тайм-аутом, или 'timeout=0', что означает, что соединение должно быть закрыто сразу после отправки ответа. При настройке параметров keep-alive NGINX эффективно управляет постоянными соединениями и использует эту переменную, чтобы сообщать клиенту о предпочтениях сервера. Если keep-alive отключен или неприменим, эта переменная может оставаться пустой. Состояние $sent_http_keep_alive также может быть изменено различными директивами, например 'keepalive_timeout', которая определяет, как долго сервер позволит соединению оставаться неактивным перед его закрытием, что делает эту переменную критически важной для производительности в условиях высокой нагрузки, когда поддержание открытых соединений может снизить задержки для последующих запросов от того же клиента.

Пример конфига

http {
    keepalive_timeout 65;
    server {
        listen 80;
        location / {
            add_header Keep-Alive "$sent_http_keep_alive";
        }
    }
}

Описание

$sent_http_transfer_encoding переменная в NGINX содержит значение заголовка 'Transfer-Encoding', отправленного в HTTP-ответе клиенту. Эта переменная особенно полезна при HTTP-ответах, которые используют chunked transfer encoding. Для успешного присвоения этой переменной конфигурация NGINX должна указывать метод transfer encoding, что обычно происходит, когда используется механизм генерации динамического содержимого (например, PHP или an upstream server). Когда NGINX сам формирует ответ, значение этой переменной по умолчанию может быть пустой строкой, если оно явно не задано. Эта переменная может принимать несколько значений, чаще всего `chunked`, что означает, что ответ будет отправляться серией частей, а не одним целым сообщением. Это особенно полезно для больших ответов, которые можно передавать потоково небольшими частями, или когда общий размер ответа заранее неизвестен. Если сервер не устанавливает transfer encoding, переменная не будет содержать значения, что отражает отсутствие использования transfer encoding.

Пример конфига

location /api {
    proxy_pass http://backend;
    proxy_set_header Accept-Encoding '';  
}


location /stream {
    proxy_pass http://stream_backend;
    add_header Transfer-Encoding chunked;
}

Описание

Переменная $sent_http_cache_control получает значение HTTP-заголовка 'Cache-Control', который NGINX отправляет клиенту. Она задаётся при обработке ответа NGINX и может изменяться в зависимости от различных настроек, таких как `expires`, `add_header` или `proxy_cache`. Эта переменная особенно полезна при отладке или настройке заголовков ответа сервера, поскольку позволяет фиксировать и логировать отправляемые директивы кэширования. Как правило, значение этой переменной может содержать директивы, такие как 'no-cache', 'private', 'max-age=3600', 'public', либо быть пустым, если заголовок не задан. Её можно использовать в сочетании с другими переменными для динамической корректировки заголовков ответа в зависимости от условий сервера или конфигурации, что даёт больше контроля над тем, как клиенты и промежуточные узлы в HTTP-цепочке кешируют ответы. Переменная вычисляется только после отправки заголовков ответа, то есть отражает окончательное значение, включённое в ответ. Если заголовок Cache-Control устанавливается или изменяется несколько раз, переменная будет содержать последнее значение, установленное перед завершением ответа.

Пример конфига

location /example {
    proxy_pass http://backend;
    add_header Cache-Control "private, max-age=3600";
    log_format custom '$remote_addr - $remote_user [$time_local] "$request" $status $sent_http_cache_control';
    access_log /var/log/nginx/access.log custom;
}

Описание

Переменная `$sent_http_link` используется в NGINX, когда в ответе задан заголовок Link. Эта переменная особенно полезна для API и веб‑сервисов, где предоставление информации о связанных ресурсах может улучшить обработку и навигацию на стороне клиента. Она заполняется на основе заголовка `Link`, определённого в контексте ответа, обычно сформированного с использованием нескольких URI, которые могут иметь отношение к текущему ресурсу. Когда формируется HTTP‑ответ, если заголовок `Link` был задан в конфигурации или динамически через Lua, `$sent_http_link` будет содержать это значение для последующей обработки. Его можно использовать при переписывании, логировании или дальнейших манипуляциях с ответом. Типичными значениями этой переменной будут строка, представляющая один или несколько URI, часто с указанием отношений (например, `rel=\"next\"` или `rel=\"prev\"`). Эта переменная особенно полезна при реализации пагинации в API, позволяя клиентам легко определить следующие или предыдущие страницы. Правильно устанавливая заголовок Link, NGINX может передавать релевантную информацию в ответе без необходимости существенной логики в приложении для обработки этих ссылок.

Пример конфига

http {
    server {
        location /api {
            add_header Link "; rel='next'";
        }
    }
}

Описание

Переменная `$limit_rate` в NGINX используется для ограничения скорости передачи ответов, отправляемых клиентам. Настраивая эту переменную, администраторы могут задать максимальное потребление пропускной способности для конкретного соединения, что может быть особенно полезно в ситуациях, когда управление ресурсами сервера становится критичным, например, в периоды высокой нагрузки. Переменная может быть установлена в конкретное значение в байтах или получать своё значение из других переменных, что позволяет гибко настраивать конфигурацию в зависимости от потребностей приложения. Эта переменная может задаваться динамически, в зависимости от различных условий в конфигурации, таких как IP-адреса или определённые характеристики запроса. По умолчанию `$limit_rate` равен нулю, что означает отсутствие ограничения скорости передачи. Если заданное значение больше нуля, NGINX применит ограничение на каждый запрос и скорректирует скорость соответственно, что может значительно повлиять на пользовательский опыт, если значение установлено слишком низко. Обычно значения задаются в байтах в секунду; например, установка `1048576` ограничит скорость до `1MB/s`.

Пример конфига

http {
    server {
        location / {
            # Limit transfer rate
            limit_rate 500k;
        }
    }
}

Описание

Переменная $connection — это встроенная переменная в NGINX, которая предоставляет уникальный идентификатор соединения для каждого запроса, обрабатываемого сервером. Она особенно полезна при отладке и ведении логов, позволяя администраторам отслеживать данные о соединении между несколькими запросами. Значение основано на дескрипторе сокета и является целым числом, которое меняется для каждой отдельной сессии соединения. Каждый раз, когда обрабатывается новый запрос, эта переменная устанавливается, чтобы идентифицировать используемое соединение, что помогает обнаруживать параллельные запросы от одного и того же клиента или различать разных пользователей в файле журнала. В процессе обработки запроса, когда клиент подключается к серверу NGINX, создаётся объект соединения, который содержит различную информацию, связанную с соединением, например адрес клиента, состояние соединения и другие данные. Переменная $connection напрямую коррелирует с этим объектом соединения. Поскольку каждый клиент может отправлять несколько запросов по одному соединению, эта переменная незаменима в ситуациях, где реализована логика, зависящая от соединения, например ограничение скорости, контроль доступа и кастомизированное ведение логов. Типичные значения этой переменной — целые числа, соответствующие текущим соединениям в системе, и они также могут быть связаны с запросами по мультиплексированным потокам HTTP/2, где одно и то же соединение может обслуживать несколько запросов одновременно. Обратите внимание, что поскольку NGINX использует асинхронную, событийно-ориентированную модель, один и тот же $connection будет разделяться между запросами до закрытия соединения, после чего для новых соединений будет назначен новый идентификатор.

Пример конфига

server {
    listen 80;
    location / {
        access_log /var/log/nginx/access.log;
        log_format main '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$connection"';
    }
}

Описание

Переменная $connection_requests в NGINX используется для отслеживания количества запросов, обработанных в течение жизни одного соединения. Она увеличивается каждый раз, когда по этому соединению поступает новый запрос, начиная с нуля при установлении соединения. Каждый запрос — будь то начальный запрос или последующие запросы, вызванные keep-alive — будет увеличивать этот счётчик. Эта переменная особенно полезна для мониторинга и понимания шаблонов запросов, оптимизации повторного использования соединений и отладки проблем с производительностью, связанных с обработкой соединений. В NGINX жизненный цикл переменной $connection_requests начинается при установке нового соединения. При каждом входящем запросе по этому соединению сервер увеличивает значение переменной до тех пор, пока соединение не будет закрыто или обработка запроса не завершится. Типичные значения для этой переменной могут начинаться с 1 для соединения с одним запросом и соответственно увеличиваться при нескольких запросах, выполненных клиентом в рамках того же соединения. В сценариях, когда соединения поддерживаются в режиме keep-alive, эта переменная позволяет веб-администраторам анализировать, насколько эффективно keep-alive соединения обрабатывают несколько запросов по сравнению с открытием нового соединения для каждого запроса. Поскольку эта переменная отражает количество запросов, она может быть полезна в конфигурациях, направленных на настройку производительности или детальное логирование запросов, где данные, полученные при мониторинге переменной, могут привести к улучшению распределения ресурсов и времени отклика. Логирование этой переменной может дать ценные сведения о поведении клиентов и паттернах их запросов, что облегчает выявление потенциальных узких мест и повышение эффективности.

Пример конфига

log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$connection_requests"';

access_log /var/log/nginx/access.log custom_format;

Описание

Переменная $connection_time в NGINX фиксирует продолжительность (в секундах), необходимую для установления соединения с клиентом после того, как NGINX получил запрос. Это значение определяется в момент установления соединения, что позволяет измерять задержку с точки зрения сервера NGINX. Переменная обновляется в рамках потока обработки соединения и в основном подходит для логирования или сбора метрик, связанных со временем соединений. Типичные значения могут варьироваться от долей секунды в оптимальных условиях до нескольких секунд в сценариях с высокой задержкой или проблемами с подключением. Контекст установки $connection_time начинается с того момента, как рабочий процесс NGINX принимает новое соединение от клиента, что соответствует началу обработки запроса. Разработчики и администраторы могут использовать эту переменную для получения сведений о характеристиках производительности, особенно при мониторинге поведения веб-сервера в различных сетевых условиях или при нагрузке. Анализ этих значений помогает оценить состояние сервера и выявить потенциальные узкие места производительности, связанные с подключениями клиентов.

Пример конфига

log_format main '$remote_addr - $remote_user [$time_local] "$request" ' \
                    '$status $body_bytes_sent "$http_referer" ' \
                    '"$http_user_agent" "$http_x_forwarded_for" ' \
                    'Connection time: $connection_time';

access_log /var/log/nginx/access.log main;

Описание

Переменная $nginx_version устанавливается NGINX при запуске и отражает версию сервера NGINX, который в данный момент запущен. Эта переменная получается непосредственно из информации о версии, содержащейся в исходном коде NGINX во время компиляции, что позволяет пользователям проверить точную версию используемого сервера. Обычно она указывается в формате, например '1.21.0' или '1.19.10'. К переменной можно обращаться в разных контекстах внутри конфигурационных файлов NGINX, например в форматах логов или в заголовках ответа. Это делает её особенно полезной для целей отладки и обслуживания, поскольку администраторы могут быстро определить версию NGINX без необходимости выполнять команды на сервере. Кроме того, знание версии может быть критически важным для обеспечения совместимости с определёнными модулями или конфигурациями, особенно в окружениях, где может существовать несколько экземпляров NGINX с разными версиями. В целом переменная $nginx_version служит преимущественно информационной целью для администраторов и разработчиков, предоставляя быстрый доступ к данным о версии, необходимым для сопровождения и обновления настроек NGINX.

Пример конфига

http {
    log_format my_log '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" NGINX/$nginx_version';
    access_log /var/log/nginx/access.log my_log;
}

Описание

Переменная $hostname задается во время обработки запроса и отражает имя хоста сервера, определенное в конфигурации NGINX. Она берет значение из директивы 'server_name', если она задана; в противном случае по умолчанию используется имя хоста операционной системы сервера. Эта переменная особенно полезна для приложений, которым необходимо знать имя хоста, обслуживающего запросы, что упрощает конфигурации, зависящие от идентичности сервера. NGINX вычисляет переменную $hostname на стадии обработки запроса, поэтому её можно использовать в различных контекстах, таких как логирование, перенаправления или условная маршрутизация запросов. Значения формируются на основе серверного блока, где обрабатывается запрос — это позволяет реализовывать динамические конфигурации, если определено несколько серверных блоков с разными именами. Если директива 'server_name' не указана, NGINX будет использовать имя хоста системы, которое можно проверить в командной строке с помощью команды 'hostname' в Linux. Для корректного задания этой переменной рекомендуется определять директиву 'server_name' в ваших серверных блоках, чтобы обеспечить предсказуемое поведение, особенно в средах с несколькими доменами или виртуальными хостами. Такой подход устраняет неоднозначности и гарантирует, что приложение будет использовать правильное доменное имя, соответствующее полученным запросам.

Пример конфига

server {
    listen 80;
    server_name example.com;

    location / {
        add_header X-Host $hostname;
    }
}

Описание

Переменная $pid в NGINX предоставляет идентификатор процесса (PID) рабочего процесса, который в данный момент обрабатывает клиентский запрос. Эта переменная особенно полезна для отладки и ведения логов, позволяя администраторам определить, какой рабочий процесс обрабатывает конкретные запросы. PID инициализируется при запуске рабочих процессов NGINX и остаётся неизменным в течение всего времени жизни соответствующего рабочего процесса. Значение $pid является числовым и соответствует системно назначенному PID соответствующего рабочего процесса, что полезно в сценариях, когда необходимо логировать детальную информацию об обработке процессов. Поскольку NGINX может порождать несколько рабочих процессов, каждый из которых может одновременно обрабатывать разные запросы, переменная $pid помогает соотнести записи логов с конкретными PID, что облегчает диагностику и мониторинг. Обычно значения $pid начинаются с определённого номера и увеличиваются для каждого нового процесса, порождаемого операционной системой. Пользователи могут использовать эту переменную в настраиваемых форматах логирования, чтобы получить информацию о том, какие процессы обслуживают трафик, либо при диагностике узких мест в производительности или проблем с отдельными рабочими процессами.

Пример конфига

log_format custom_log '$remote_addr - $remote_user [$time_local] "$request" '
'"$status $body_bytes_sent "$http_referer" "-" "$http_user_agent" 'Ver: $nginx_version Pid: $pid';

access_log /var/log/nginx/access.log custom_log;

Описание

Переменная $msec — это встроенная переменная в NGINX, которая предоставляет информацию о времени высокого разрешения. Она возвращает текущее системное время в миллисекундах, прошедшее с эпохи Unix (1 января 1970 г.). Это значение устанавливается в момент обработки запроса и обычно используется для ведения логов, отладки и измерения производительности. Когда приходит запрос, NGINX получает текущее время и преобразует его в миллисекунды, которые затем можно использовать в различных контекстах, таких как журналы доступа, пользовательские заголовки или для условной обработки на основе времени. Точность этой переменной делает её особенно полезной, когда нужно измерять время ответа или вычислять задержки между различными этапами обработки запроса. Значение, возвращаемое $msec, — десятичное число, представляющее общее количество миллисекунд, прошедших с эпохи. Эта переменная часто используется вместе с другими переменными, связанными со временем, такими как $time_iso8601, для формирования подробных логов, которые требуют и отформатированной даты, и точности до миллисекунд. Важно помнить, что точность переменной $msec зависит от операционной системы и разрешающей способности аппаратных часов.

Пример конфига

log_format custom_format '$remote_addr - [$time_local] "${request}" $status $body_bytes_sent "$http_referer" "$http_user_agent" $msec';
access_log /var/log/nginx/access.log custom_format;

Описание

Переменная $time_iso8601 выводит дату и время в формате, соответствующем стандарту ISO 8601. Эта метка времени обычно имеет формат 'YYYY-MM-DDTHH:MM:SS+ZONE', например '2023-10-04T12:34:56+00:00'. Переменная заполняется NGINX во время обработки запроса и доступна в разных контекстах внутри файла конфигурации. Она использует настройки локального часового пояса сервера, чтобы отображаемое время соответствовало текущим настройкам времени сервера. Она особенно полезна для целей логирования или в контексте HTTP-заголовков, где однозначное представление даты и времени может помочь клиентам в интерпретации, отладке и анализе данных. Как правило, NGINX устанавливает эту переменную при обработке каждого запроса, что гарантирует её актуальность при обращении в течение жизненного цикла запроса. В составе выходного значения метки времени переменная включает информацию о часовом поясе, что делает её пригодной для сценариев, где имеет значение различие часовых поясов. Благодаря своему стандартному формату $time_iso8601 предпочитают в ответах RESTful API и веб-службах, которым требуются точные метки времени, поскольку это позволяет клиентам корректно интерпретировать полученные данные в разных часовых поясах. Переменную можно форматировать так же, как традиционные форматы команды date в NGINX, сохраняя её удобство использования в различных средах установки.

Пример конфига

http {
    log_format combined '$remote_addr - $remote_user [$time_iso8601] "$request" '
                  '$status $body_bytes_sent "$http_referer" "$http_user_agent"';
    access_log /var/log/nginx/access.log combined;
}

Описание

Переменная $time_local в NGINX предоставляет локальное время сервера в момент получения запроса. Она форматируется как 'day/month/year:hour:minute:second zone' в соответствии с Common Log Format, который повсеместно используется для записей в логах. Эта переменная особенно полезна для целей журналирования, поскольку позволяет администраторам отслеживать время совершения запросов с учётом настроек часового пояса сервера. Значение $time_local устанавливается в ходе обработки запроса, конкретно — в момент получения запроса приложением. Таким образом оно гарантирует, что временная метка точно соответствует моменту обработки запроса. По умолчанию эта переменная форматируется в соответствии с локальным часовым поясом сервера, который можно задать с помощью директив в конфигурации NGINX. Типичные значения этой переменной могут выглядеть как '12/Apr/2023:18:30:12 +0300', указывая точную дату и время вместе со смещением часового пояса. Учитывая её важность для журналирования, её часто используют в пользовательских форматах логов, чтобы точно фиксировать временные метки запросов, что облегчает отладку и мониторинг активности сервера.

Пример конфига

log_format my_log_format '$remote_addr - $remote_user [$time_local] "$request"';

access_log /var/log/nginx/access.log my_log_format;

Описание

Переменная $tcpinfo_rtt является частью модуля TCP‑соединений NGINX и используется для получения метрик производительности TCP‑соединения. Она возвращает измерения времени круговой поездки (RTT) для TCP‑соединения, отражающие время, требующееся пакету данных, чтобы пройти от отправителя до получателя и обратно. Эта переменная особенно полезна при диагностике сетевой задержки и оценке отзывчивости сервера на входящие запросы. Значение $tcpinfo_rtt доступно только после установления соединения и может быть не сразу установлено для входящих подключений. Как правило, оно возвращает целочисленное значение, представляющее время в микросекундах. Для нового соединения, если информация о RTT ещё недоступна, оно может возвращать ноль до тех пор, пока данные не будут получены из стека TCP. На практике типичные значения могут значительно варьироваться в зависимости от сети, и разработчики могут использовать этот показатель для тонкой настройки своих приложений с целью лучшей обработки задержек. Эту переменную можно использовать в директивах логирования, когда администраторы сервера хотят отслеживать производительность соединений с течением времени. Включая эту метрику в логи доступа, администраторы могут анализировать тенденции и выявлять потенциальные узкие места в доставке сервиса.

Пример конфига

log_format custom_log '$remote_addr - $remote_user [$time_local] "$request" $status $tcpinfo_rtt';
access_log /var/log/nginx/access.log custom_log;

Описание

Переменная $tcpinfo_rttvar в NGINX предоставляет диагностическую информацию, связанную со стабильностью задержки TCP-соединений, указывая на вариацию времени прохождения туда и обратно (RTT). Эта метрика выводится из информации стека TCP, конкретно измеряя дисперсию значений RTT, наблюдаемых для пакетов, отправленных по TCP-соединению. Когда клиент отправляет запрос, NGINX фиксирует TCP-информацию для этой сессии, которая включает значения RTT, как они сообщаются стеком TCP операционной системы. Как правило, $tcpinfo_rttvar становится доступной только после завершения TCP-рукопожатия, и она особенно полезна при настройке производительности и в сценариях мониторинга. Типичные значения могут существенно варьироваться в зависимости от сетевых условий и особенностей трафика: более низкие значения указывают на более стабильную и последовательную сетевую задержку, тогда как более высокие значения свидетельствуют о нестабильности. Поэтому мониторинг этой переменной может помочь в диагностике сетевых проблем, влияющих на производительность приложения и опыт пользователя. Эта переменная в основном устанавливается каждый раз, когда NGINX обрабатывает запрос по TCP-соединению в сценариях, где применимы метрики TCP. Вы можете использовать её значение в различных контекстах, например в логировании или условных конфигурациях, чтобы применять адаптированные оптимизации в зависимости от наблюдаемой вариации RTT во время запроса.

Пример конфига

log_format my_logging_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $tcpinfo_rttvar';

access_log /var/log/nginx/access.log my_logging_format;

Описание

Переменная $tcpinfo_snd_cwnd в NGINX предоставляет текущий размер окна перегрузки отправки TCP для соединения, что имеет решающее значение для понимания потока и отзывчивости передачи данных по сети. Эта переменная актуальна в сценариях, где NGINX используется в качестве обратного прокси или балансировщика нагрузки, поскольку она позволяет в реальном времени отслеживать метрики TCP, что может быть критично для настройки производительности и оптимизации. Размер окна перегрузки указывает на объём данных, который можно отправить до ожидания подтверждения от получателя, влияя на общую пропускную способность сети. Значение $tcpinfo_snd_cwnd устанавливается во время активного TCP‑соединения (т.е. когда TCP является транспортным уровнем) и отражает изменения размера окна перегрузки по мере передачи данных. Типичные значения сильно варьируются в зависимости от условий сети, нагрузки и конфигурации; они могут быть очень маленькими — эквивалентными нескольким TCP‑пакетам, или достаточно большими, если маршрут сети надёжен и имеет достаточную пропускную способность. Мониторинг этой переменной помогает администраторам выявлять потенциальные узкие места в производительности и соответственно корректировать конфигурацию серверов.

Пример конфига

location /status {
    default_type text/plain;
    add_header Content-Length 0;
    return 200 "Current congestion window size: $tcpinfo_snd_cwnd bytes\n";
}

Описание

Переменная $tcpinfo_rcv_space в NGINX предоставляет информацию о размере буфера приёма TCP, что важно для управления входящими TCP-соединениями. Эта переменная отражает текущее значение объёма приёма, выделенного TCP-стеком для обработки входящих пакетов данных. Она устанавливается при установлении соединения на уровне TCP и определяется параметрами системы и приложения, такими как TCP_MAX_RCV_SPACE, который может ограничивать максимальный размер буфера приёма. При установлении соединения TCP-ядро выделяет часть памяти для входящих пакетов данных, которая заполняется до достижения указанного предела. По мере приёма данных доступный объём приёма уменьшается, влияя на поток входящих соединений. Эта переменная особенно полезна для выявления проблем с сетевой производительностью или для мониторинга поведения приложения под нагрузкой, так как она может показать, использует ли приложение доступные ресурсы эффективно. Типичные значения $tcpinfo_rcv_space могут значительно варьироваться в зависимости от конфигурации системы и состояния сети, но часто соответствуют стандартным размерам TCP-буферов, которые могут составлять от нескольких килобайт до нескольких мегабайт в зависимости от системных настроек и нагрузки. Корректная настройка этих параметров может привести к оптимизированной производительности и снижению задержек при передаче данных.

Пример конфига

server {
    listen 80;

    location /status {
        add_header X-TCP-Receive-Space "$tcpinfo_rcv_space";
        # Additional status logic...
    }
}

Описание

В NGINX переменная "$http_" является динамическим префиксом для доступа к HTTP-заголовкам запроса, отправленным клиентом. Синтаксис этой переменной — "$http_", где `` приводится к нижнему регистру, а дефисы заменяются на подчёркивания. Например, если клиент отправляет заголовок `X-Forwarded-For`, его значение можно получить с помощью `$http_x_forwarded_for`. Эта функциональность позволяет NGINX удобно обрабатывать различные заголовки, обеспечивая простой доступ к любому HTTP-заголовку по стандартной схеме именования. Когда клиент делает запрос к серверу, все HTTP-заголовки доступны в контексте запроса, и NGINX заполняет переменные `$http_` в процессе обработки запроса. Эти переменные могут использоваться в различных контекстах в конфигурационном файле, таких как `server`, `location` и `if` блоки. Часто через эту переменную получают доступ к заголовкам авторизации, пользовательским заголовкам приложения и стандартным заголовкам, таким как `User-Agent` или `Accept-Encoding`, что позволяет гибко управлять запросом или выполнять условную обработку в зависимости от наличия или значения тех или иных заголовков.

Пример конфига

server {
    listen 80;
    location /example {
        if ($http_user_agent ~* "Googlebot") {
            return 403;
        }
        add_header X-Your-Header "$http_x_your_header";
    }
}

Описание

В NGINX префиксная переменная $sent_http_ автоматически создаётся, когда в блоке server или location устанавливаются определённые заголовки ответа. Для каждого заголовка HTTP-ответа, отправляемого клиенту, существует соответствующая переменная с префиксом $sent_http_. Например, если вы отправляете HTTP-заголовок 'X-My-Header' из конфигурации сервера, соответствующая переменная будет $sent_http_x_my_header. Эти переменные позволяют получить доступ к значениям HTTP-заголовков, которые были отправлены в ответе, непосредственно в конфигурации NGINX или в форматах логов. Эта переменная особенно полезна в сценариях, когда необходимо выполнять условную запись в лог или настраивать вывод на основе значений конкретных заголовков. Переменные $sent_http_ заполняются только в том случае, если соответствующие заголовки действительно установлены в ответе. Если заголовок не установлен, соответствующая переменная будет пустой. Этот механизм помогает отслеживать и управлять различной информацией о заголовках, что имеет решающее значение в таких сценариях, как отладка или проверка поведения сервера, особенно при тестировании.

Пример конфига

location /example {
    add_header X-My-Header "MyValue";
    add_header X-Another-Header "AnotherValue";

    # Log sent headers
    access_log /var/log/nginx/example.log custom_format;
}

log_format custom_format 'Sent HTTP Headers: $sent_http_x_my_header, $sent_http_x_another_header';

Описание

Переменная $sent_trailer_ используется в сочетании с HTTP/1.1-ответами, которые включают трейлеры — дополнительные поля, отправляемые после тела сообщения. Эта переменная позволяет NGINX получить доступ к конкретным полям трейлера, которые могли быть установлены в ответе. Она может использоваться в виде префикса к имени трейлера, например `$sent_trailer_myfield`, что вернёт значение трейлера `myfield`, если он был указан в HTTP-ответе. Обычно эта переменная задаётся на этапе формирования HTTP-ответа, когда трейлеры определены и готовы к отправке. Сами трейлеры определяются в полях заголовка ответа, и, следовательно, значения, связанные с переменными $sent_trailer_, будут зависеть от того, как приложение или бэкенд-сервис заполняют эти поля трейлеров до того, как NGINX отправит окончательный ответ. Если указанный трейлер существует, переменная вернёт его значение; в противном случае она вернёт пустую строку. Использование трейлеров не очень распространено в ответах фронтенд-серверов, и их поддержка в значительной степени зависит от реализации клиента и сервера. Некоторые сценарии применения трейлеров включают передачу контрольных сумм или другой метаданных, которые должны идти после полезной нагрузки в потоковых сценариях, что делает трейлеры полезной функцией для отдельных приложений.

Пример конфига

location /example {
    add_header My-Trailer myvalue;
    # The value of the trailer can be accessed
    echo "$sent_trailer_My-Trailer";
}

Описание

В NGINX переменные с префиксом $cookie_ обеспечивают простой доступ к значениям cookie, установленным клиентами в их HTTP-запросах. Когда клиент отправляет запрос на сервер NGINX, в нём могут присутствовать различные cookie, содержащие информацию о пользователе, сведения о сессии или предпочтения. Обращаясь к $cookie_, где — конкретное имя cookie, NGINX извлекает соответствующее значение из cookie, отправленных в запросе. Этот механизм позволяет динамически формировать содержимое на основе данных, специфичных для пользователя, хранящихся в cookie. Например, если клиент отправил cookie с именем 'user_id', её можно получить как $cookie_user_id в конфигурации. Если cookie существует, переменная возвращает его значение; если нет — возвращает пустую строку. Эта возможность широко используется в веб-приложениях для адаптации ответов в зависимости от предыдущих взаимодействий пользователя или его предпочтений. Кроме того, cookie-переменные могут использоваться в различных контекстах, например внутри блоков location или server, что позволяет задавать условные конфигурации и настраивать обработку ошибок в зависимости от состояния пользователя. Неправильная обработка значений cookie, например отсутствие проверки входных данных, может привести к уязвимостям безопасности, поэтому важно обращаться с ними с надлежащей осторожностью.

Пример конфига

server {
    listen 80;
    server_name example.com;

    location / {
        if ($cookie_user_id) {
            add_header X-User-ID $cookie_user_id;
        }
    }
}

Описание

В NGINX переменные с префиксом $arg_ используются для извлечения параметров запроса из URI. Когда клиент отправляет HTTP-запрос, он может включать строку запроса, состоящую из пар «ключ=значение», добавленных к URL. Например, в URL запроса `http://example.com/path?arg1=value1&arg2=value2` NGINX позволяет обратиться к этим параметрам через соответствующие переменные, такие как `$arg_arg1` и `$arg_arg2`. Значение, возвращаемое конкретной переменной `$arg_`, соответствует значению связанного параметра запроса; если параметр отсутствует, переменная возвращает пустую строку. Эти переменные особенно полезны в случаях, когда обработка запроса должна зависеть от параметров клиента, например при перенаправлениях, контроле доступа или условных ответах. Они вычисляются при обработке каждого запроса, что делает их удобными для динамической генерации контента на основе ввода клиента. Важно отметить, что поскольку они чувствительны к контексту, их правильное использование требует понимания конфигурации NGINX, особенно в части расположения директив, зависящих от этих переменных.

Пример конфига

location /example {
    if ($arg_user_id) {
        return 200 "User ID: $arg_user_id";
    }
    return 400 "No User ID provided";
}

Описание

В NGINX переменная $proxy_host играет ключевую роль в конфигурациях обратного проксирования, которые перенаправляют клиентские запросы на backend‑серверы. Когда запрос проксируется, эта переменная устанавливается в значение части URL, отвечающей за хост, указанного в директиве proxy_pass. Она отражает имя хоста upstream‑сервера, определённое настройками прокси в файле конфигурации. Переменная $proxy_host доступна во время обработки запроса, особенно в тех контекстах, где запрос проксируется — например, внутри блока location, использующего директиву proxy_pass. Если upstream‑сервер задан именем хоста или IP‑адресом, $proxy_host вернёт соответствующее значение, что позволяет динамически обрабатывать запросы в зависимости от идентичности целевого сервера. Типичными значениями $proxy_host могут быть фактическое имя хоста, например "api.example.com", или IP‑адрес, если он указан непосредственно в определении upstream. При использовании нескольких upstream‑серверов эта переменная становится жизненно важной для ведения логов и отладки. Она помогает отслеживать, на какой сервер был отправлен запрос, особенно в конфигурациях с балансировкой нагрузки. Она также полезна при формировании пользовательских заголовков или изменении запросов на основе разрешённого имени хоста upstream‑сервера.

Пример конфига

location /api {
    proxy_pass http://backend;
    proxy_set_header Host $proxy_host;
}

Описание

Переменная $proxy_port в NGINX используется для указания номера порта проксируемого сервера, заданного в директиве proxy_pass. Эта переменная особенно полезна, когда нужно вести логирование или условно обрабатывать запросы на основе порта целевого сервера. Она устанавливается всякий раз, когда запрос проксируется с помощью директивы `proxy_pass`. Если в `proxy_pass` указано имя хоста, NGINX разрешает его в адрес и порт, и переменная $proxy_port получает этот порт. Как правило, этот порт будет 80 для HTTP-запросов и 443 для HTTPS, но он может отличаться в зависимости от конфигурации вашего upstream-сервера. В сценариях, когда запрос не проксируется, или если порт явно не определён в конфигурации proxy_pass, $proxy_port может возвращать пустую строку. Важно убедиться, что конфигурация proxy_pass корректно указывает протокол и порт, чтобы эффективно использовать эту переменную. Вы также можете комбинировать её с другими переменными, такими как $proxy_host, чтобы создавать динамическое поведение в ваших конфигурациях.

Пример конфига

location /example {
    proxy_pass http://backend_server:8080;
    access_log /var/log/nginx/proxy_access.log "Proxy to port: $proxy_port";
}

Описание

Переменная $proxy_add_x_forwarded_for используется в NGINX для формирования заголовка X-Forwarded-For, который необходим в прокси-настройках для сохранения исходного IP-адреса клиента. Она фактически объединяет IP-адрес клиента с любыми существующими IP-адресами, уже указанными в заголовке X-Forwarded-For, обеспечивая сохранение цепочки адресов прокси при наличии нескольких прокси. Переменная устанавливается во время обработки запроса, когда сервер NGINX находится в режиме прокси, обычно в конфигурации блока location, использующего директиву proxy_pass. Когда NGINX обрабатывает запрос, если заголовок X-Forwarded-For присутствует, эта переменная возьмёт его текущее значение и добавит IP-адрес клиента. Если заголовок отсутствует, она будет содержать только IP-адрес клиента. Например, если IP клиента 192.168.1.5, а предыдущий прокси установил заголовок X-Forwarded-For как 10.1.1.1, то $proxy_add_x_forwarded_for будет равен "10.1.1.1, 192.168.1.5". Это важный механизм для приложений, размещённых за несколькими уровнями прокси, позволяющий корректно регистрировать и отслеживать исходные IP-адреса клиентов. Он особенно используется в сценариях балансировки нагрузки, чтобы сохранить целостность следа запроса.

Пример конфига

location /api {
    proxy_pass http://backend;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Описание

Переменная $proxy_add_via динамически формируется NGINX, когда HTTP-запрос проксируется на другой сервер. Она формирует заголовок 'Via', который помогает идентифицировать использованный метод проксирования. Эта переменная обычно устанавливается в формате '1.1 NGINX' при проксировании запроса, указывая версию протокола и имя сервера. Это особенно полезно при отладке и управлении системами кэширования, поскольку позволяет клиентским приложениям и промежуточным прокси отслеживать происхождение запроса через NGINX-прокси. Эта переменная обычно задаётся при использовании директивы proxy_pass в конфигурации. Например, если директива `proxy_pass` правильно настроена для upstream server, NGINX автоматически заполнит $proxy_add_via соответствующим значением для всех запросов, перенаправляемых на этот сервер. Если в цепочке используется несколько прокси, заголовки 'Via' будут отражать весь маршрут запроса, обеспечивая лучший контроль и видимость общих кэшей и механизмов маршрутизации. Типичные значения могут включать '1.1 NGINX' или указывать дополнительные сервисы прокси, если они используются вместе с NGINX.

Пример конфига

location /api {
    proxy_pass http://backend_service;
    proxy_set_header Host $host;
    add_header Via $proxy_add_via;
}

Описание

Переменная $proxy_internal_host в NGINX используется преимущественно в конфигурациях, где запросы проксируются во внутренние локации. Ее роль — сохранять и возвращать внутреннее (или бэкенд) имя хоста, которое обычно определяется настройками внутренней сети сервера. Эта переменная особенно полезна в сценариях, связанных с балансировкой нагрузки или настройками обратного прокси, когда несколько upstream-серверов могут обрабатывать входящие запросы. В зависимости от контекста переменная будет установлена в внутреннее имя хоста, указанное в конфигурации прокси, или по умолчанию примет имя хоста сервера, если оно явно не задано. $proxy_internal_host вычисляется во время обработки запроса, который был изменён с помощью директив, связанных с прокси, таких как "proxy_pass". Если задан proxy_name, это имя будет использовано в качестве значения этой переменной. Если внутреннее имя хоста не задано, система может вернуться к поведению по умолчанию, предусмотренному конфигурацией NGINX. Это гарантирует корректную маршрутизацию запросов на основе явно заданных конфигураций или внутренних значений по умолчанию. Это позволяет реализовывать продвинутые конфигурации, в которых решения принимаются на основе переменной $proxy_internal_host, обеспечивая управление внутренними политиками маршрутизации или проверками безопасности, основанными на внутренних именах хостов. Также это может улучшить процессы логирования и отладки, когда администраторам нужно более наглядно изучать настройки внутреннего проксирования.

Пример конфига

location /api {
    proxy_pass http://backend_server;
    proxy_set_header Host $proxy_internal_host;
}

Описание

Переменная $proxy_internal_connection устанавливается в контексте обработки проксируемого запроса в NGINX, когда запрос перенаправляется на другой upstream-сервер. Она проверяет, использует ли исходящее соединение внутреннюю сеть: это определяется тем, является ли сокет для соединения частью правил внутренней маршрутизации, настроенных в вашей конфигурации NGINX. По умолчанию значение этой переменной будет равно '1' (true), если исходящее соединение внутреннее, и '0' (false), если оно внешнее. Эта переменная особенно полезна в сценариях с несколькими уровнями проксирования или в конфигурациях, где ограничения безопасности применяются в зависимости от того, являются ли соединения внутренними или внешними. Например, если у вас заданы правила, ограничивающие доступ или изменяющие заголовки в зависимости от типа соединения, эта переменная поможет тонко настроить такое поведение. Пользователи могут задать специальные конфигурации в своей настройке NGINX, чтобы реагировать по-разному в зависимости от значения этой переменной, усиливая контроль над обработкой соединений в проксируемых запросах. Типичные варианты использования могут включать повышенный уровень логирования, изменение заголовков запроса для внутренних соединений, но не для внешних, или применение специальных мер безопасности, чтобы не допустить раскрытия определённых функций через публичные соединения. Журналы затем могут указывать разные маршруты в зависимости от состояния этой переменной, что облегчает диагностику и мониторинг производительности.

Пример конфига

location /proxy {
    proxy_pass http://backend;
    # Log whether the connection is internal or not
    access_log /var/log/nginx/internal_access.log;
    if ($proxy_internal_connection) {
        # Internal requests can have specific handling 
        set $internal 'true';
    }
}

Описание

Переменная `$proxy_internal_body_length` в NGINX используется в контексте проксирования между серверами, в частности когда NGINX выступает в роли обратного прокси. Эта переменная отслеживает размер тела запроса, полученного от вышестоящего сервера. Значение этой переменной устанавливается после того, как NGINX обработает запрос, пришедший от вышестоящего сервера, обычно в момент пересылки запроса или получения ответа. Эта переменная особенно полезна в конфигурациях, где требуется отслеживать или изменять размер содержимого тела. Например, если вы реализуете фильтрацию содержимого, логирование или условную обработку на основе размера тела, `$proxy_internal_body_length` обеспечивает быстрый и точный способ получить длину входных данных тела. Типичные значения этой переменной будут варьироваться в зависимости от сценария запроса и ответа, но в целом она отражает количество байт, присутствующих в теле запроса. В данном сценарии проксирования, когда NGINX обрабатывает запрос, он вычисляет длину тела, полученную из проксированного содержимого, и присваивает её этой переменной перед выполнением дальнейших операций или директив, где размер может иметь значение.

Пример конфига

location /proxy {
    proxy_pass http://backend;
    access_log /var/log/nginx/proxy.log "$proxy_internal_body_length";
}

Описание

Переменная $proxy_internal_chunked управляет методом кодирования передачи, используемым NGINX для внутренних ответов, пересылаемых модулем proxy. Когда она установлена в "on", это означает, что ответы без заранее заданного заголовка Content-Length должны передаваться с использованием chunked transfer encoding, что позволяет отправлять данные клиентам по мере их готовности. Это особенно полезно для динамического контента, когда длина ответа заранее неизвестна. Эта переменная обычно задается в location blocks или server contexts, преимущественно при proxying, когда запрос клиента обрабатывается backend server. Поведение по умолчанию в NGINX использует chunked encoding, если upstream server не указывает заголовок Content-Length, что позволяет клиентам начинать обработку ответа сразу, не ожидая отправки всего тела. Разработчики могут выборочно включать или отключать эту функцию в зависимости от конкретных сценариев использования и поведения upstream services, к которым они подключаются, что делает её гибким инструментом управления тем, как данные обслуживаются. На практике $proxy_internal_chunked может дать прирост производительности при обработке больших или потоковых ответов, но он может вносить сложности для клиентов, которые могут неправильно обрабатывать chunked responses. Поэтому при настройке NGINX для использования этой переменной следует внимательно учитывать совместимость клиентов и возможные последствия для производительности.

Пример конфига

location /api {
    proxy_pass http://backend;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_buffering off;
    # Enable chunked transfer for internal responses
    set $proxy_internal_chunked on;
}

Описание

Переменная $fastcgi_script_name используется в конфигурации NGINX для получения имени скрипта, который передаётся FastCGI-серверу. Эта переменная в основном устанавливается при использовании директивы `fastcgi_pass`, которая перенаправляет запросы на FastCGI-сервер. При обработке входящего запроса NGINX извлекает часть URI, соответствующую скрипту, из запроса и устанавливает значение этой переменной соответственно. Это гарантирует, что FastCGI-приложение получит корректный путь к скрипту для обработки, что критично для приложений, которые полагаются на определённые механизмы маршрутизации, например PHP- или Python-приложений, работающих под FastCGI. В типичном использовании $fastcgi_script_name будет возвращать значение типа `/index.php` или `/app/script.php`, отражая скрипт, который должен быть выполнен. Если скрипт не найден или запрос не нацелен на скрипт, переменная может быть пустой. Поэтому эта переменная важна не только для маршрутизации к правильному скрипту, но и играет критическую роль в приложениях, где доступ к файлам строго контролируется структурой URL.

Пример конфига

location / {
    include fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
}

Описание

Переменная $fastcgi_path_info используется в NGINX при взаимодействии с приложениями FastCGI. Она предоставляет дополнительную информацию о пути, которая может идти после имени скрипта в URL. Это значение особенно важно при работе с RESTful APIs или веб‑приложениями, которым нужно передавать части URL бэкенд‑приложению для обработки. Например, если выполняется запрос к /api/users/123, то '123' будет считаться path info и будет возвращено как значение переменной $fastcgi_path_info. Эта переменная в первую очередь устанавливается при использовании конфигурации FastCGI в серверном блоке NGINX, конкретно при обработке запросов к скриптам. Она позволяет NGINX корректно сопоставлять входящие запросы с соответствующим приложением FastCGI, обеспечивая более гибкую маршрутизацию и интеграцию с различными веб‑фреймворками, которые могут полагаться на разбор этой path info для своей работы. Важно отметить, что если в URL нет дополнительных сегментов пути после имени скрипта, $fastcgi_path_info будет пустой. В типичном сценарии, при определении FastCGI location блока в NGINX вы указываете путь к FastCGI-скрипту, одновременно позволяя NGINX обрабатывать дополнительную информацию пути через эту переменную, которую затем могут использовать указанные веб‑приложения.

Пример конфига

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass 127.0.0.1:9000;
    fastcgi_index index.php;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_param PATH_INFO $fastcgi_path_info;
}

Описание

Переменная $grpc_internal_trailers используется в контексте протоколов gRPC для доступа к полям трейлеров ответа gRPC. Трейлеры в gRPC — это пары ключ-значение, которые могут быть отправлены в конце ответа, аналогично HTTP-заголовкам, что позволяет передавать дополнительные метаданные вместе с телом ответа. Эта переменная заполняется только тогда, когда сервер обрабатывает gRPC-запрос и способен обрабатывать поля трейлеров. При обработке ответа gRPC, если соответствующая информация трейлеров включена, она становится доступной через $grpc_internal_trailers. Поэтому эта переменная обычно будет содержать строковое представление полей трейлеров, отформатированное аналогично HTTP-заголовкам, разделённое запятыми или переводами строк. Если запрос не возвращает трейлеров, эта переменная останется пустой. Использование трейлеров может повысить эффективность обмена, позволяя серверу отправлять важную информацию вместе с ответом без увеличения объёма тела.

Пример конфига

location /example {
    grpc_pass grpc://backend;
    add_header Trailer 'grpc-status';
    set $status $grpc_internal_trailers;
}

Описание

Переменная $ssl_protocol в NGINX показывает конкретную версию протокола SSL/TLS, согласованную для защищённого соединения между клиентом и сервером. Эта переменная устанавливается только тогда, когда SSL включён в конфигурации, и отражает последнюю версию протокола, использованную для текущего запроса во время выполнения. Она может возвращать значения, такие как 'TLSv1.2', 'TLSv1.3' или 'SSLv3', в зависимости от протоколов, включённых в SSL-конфигурации сервера. При использовании $ssl_protocol особенно полезна для логирования и условной обработки внутри конфигураций NGINX. Например, администратор может захотеть скорректировать настройки в зависимости от уровня безопасности используемого протокола. Переменная обычно заполняется во время TLS handshake, и, как и другие переменные уровня соединения, её можно получить в различных контекстах, таких как блоки location или server. Это упрощает применение условной логики или усиление мер безопасности на основе используемой версии протокола. Важно, чтобы пользователи понимали, что доступность разных значений протокола в значительной степени зависит от cipher suites и протоколов, сконфигурированных в блоке сервера. Если конкретная версия протокола (например, TLSv1.3) не включена, значение $ssl_protocol может отражать следующую доступную версию, которую сервер и клиент смогут согласовать.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    # Log the SSL protocol used
    access_log /var/log/nginx/ssl_protocol.log 'SSL Protocol: $ssl_protocol';
}

Описание

Переменная $ssl_cipher в NGINX предоставляет имя набора шифров, который в данный момент используется для SSL/TLS‑соединения. Эта переменная особенно полезна для целей логирования и отладки, так как позволяет администраторам определить, какой шифр был согласован для защищённых соединений. Значение $ssl_cipher устанавливается во время процесса SSL‑рукопожатия, который происходит, когда клиент инициирует соединение по HTTPS. В зависимости от выбранного набора шифров переменная $ssl_cipher может содержать значения, например 'ECDHE-RSA-AES256-GCM-SHA384' или 'ECDHE-ECDSA-CHACHA20-POLY1305' и др. При настройке SSL/TLS в NGINX важно учитывать шифры, поддерживаемые как сервером NGINX, так и SSL‑реализацией клиента. Поддерживаемые шифры можно задать в конфигурационном файле NGINX с помощью директивы ssl_ciphers. Эффективное значение $ssl_cipher будет отражать конфигурацию, заданную этой директивой, и может также зависеть от версии OpenSSL, использованной при сборке NGINX. Если клиент попытается подключиться, используя шифр, который не поддерживается сервером, соединение не установится, и переменная $ssl_cipher не будет задана. Помимо присутствия во время обработки SSL‑соединения, $ssl_cipher также можно использовать вместе с директивами логирования для фиксации данных, связанных с безопасностью, что помогает при анализе и мониторинге защищённых сессий. Такая видимость помогает лучше понимать соединения клиентов, обеспечивать соблюдение требований безопасности и оптимизировать конфигурации шифров.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    ssl_ciphers 'HIGH:!aNULL:!MD5';
    access_log /var/log/nginx/access.log combined;
    location / {
        add_header X-SSL-Cipher $ssl_cipher;
    }
}

Описание

Переменная `$ssl_ciphers` в NGINX автоматически устанавливается при обработке HTTPS-запросов. Эта переменная содержит строковое представление наборов шифров, согласованных между клиентом и сервером в процессе SSL/TLS-рукопожатия. Она особенно полезна для целей логирования и отладки, поскольку позволяет администратору сервера выяснить, какие наборы шифров используются для защищённых соединений. Эта переменная заполняется только при включённом SSL-модуле в NGINX и применима только в server blocks, обрабатывающих SSL-соединения. Типичные значения для `$ssl_ciphers` могут выглядеть как 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384', представляя собой список имён наборов шифров, разделённых запятыми. Конкретные шифры, которые появятся в этой переменной, зависят от директивы конфигурации `ssl_ciphers`, определённой в контексте сервера NGINX, а также от возможностей и предпочтений клиента во время рукопожатия. На практике `$ssl_ciphers` также может способствовать реализации мер безопасности, таких как HSTS (HTTP Strict Transport Security), позволяя администраторам условно корректировать свои настройки на основе силы используемых шифров. Соблюдение протоколов безопасной связи повышает общую безопасность веб-приложений.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate     /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    ssl_ciphers 'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';
    access_log /var/log/nginx/ssl_ciphers.log combined;
}

location / {
    add_header X-Cipher-Used "$ssl_ciphers";
}

Описание

Переменная $ssl_curve используется в NGINX для отображения эллиптической кривой, применяемой при установлении SSL/TLS-соединения. Эта переменная относится к соединениям, использующим протокол SSL, и устанавливается после успешного завершения SSL handshake. Значение этой переменной может различаться в зависимости от эллиптической кривой, согласованной между клиентом и сервером в процессе handshake. Типичные значения включают 'P-256', 'P-384', 'P-521' и другие, указанные в конфигурации SSL/TLS сервера. Значение $ssl_curve особенно полезно для логирования или условных сценариев управления доступом в конфигурации NGINX. Оно помогает администраторам понимать, какие кривые используются, что может отражаться на производительности или требованиях соответствия безопасности. Важно отметить, что эта переменная будет действительна только в контекстах, где активен SSL, и её не следует использовать за пределами SSL-enabled server block или location, обрабатывающего защищённый трафик. Использование переменной $ssl_curve в конфигурациях должно сопровождаться пониманием протоколов SSL/TLS и значимости выбранной эллиптической кривой для криптографических операций, особенно в условиях постоянно меняющейся области безопасности.

Пример конфига

server {
    listen 443 ssl;
    server_name example.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        add_header X-Ssl-Curve $ssl_curve;
        # Other location directives
    }
}

Описание

$ssl_curves — это переменная в NGINX, которая содержит названия эллиптических кривых, согласованных для использования в ходе SSL/TLS-сессии. Эта переменная особенно важна при использовании современных стандартов шифрования для обеспечения защищённой связи. Значение этой переменной устанавливается при установлении SSL-соединения и может включать несколько кривых, если согласованная сессия их поддерживает. Типичные значения этой переменной могут включать такие имена, как "P-256", "P-384" или "P-521", в зависимости от кривых, поддерживаемых на стороне сервера и клиента. Эта переменная особенно полезна для мониторинга и устранения неполадок SSL/TLS-соединений, поскольку она даёт возможность получать информацию в реальном времени о криптографических методах, принимаемых и используемых в защищённой связи. Администраторы могут использовать эти данные, чтобы убедиться, что их конфигурация настроена на использование оптимальных кривых, что способствует лучшим практикам безопасности при развертывании веб-приложений. Стоит отметить, что конкретные эллиптические кривые, доступные для использования, зависят от версии библиотеки OpenSSL и её конфигурации. Если вы хотите контролировать или оптимизировать настройки кривых для ваших SSL-соединений, использование переменной $ssl_curves может дать ценные сведения о соответствии ваших конфигураций текущим лучшим практикам безопасности.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /status {
        # Show the negotiated SSL curves for monitoring
        add_header Content-Type text/plain;
        return 200 "$ssl_curves";
    }
}

Описание

Переменная $ssl_sigalg устанавливается в процессе SSL-рукопожатия, конкретно когда клиент устанавливает защищённое соединение с сервером NGINX. Эта переменная фиксирует и предоставляет информацию об алгоритме подписи, использованном при обмене, что важно для аудита, логирования или условных настроек, основанных на параметрах безопасности, установленных во время соединения. Типичные значения для $ssl_sigalg могут включать различные криптографические алгоритмы, используемые в SSL/TLS-коммуникации, такие как `SHA256 with RSA Encryption`, `SHA1` или даже подписи `ECDSA`, среди прочих, в зависимости от SSL-конфигурации сервера и поддерживаемых клиентом протоколов. По мере эволюции протоколов SSL/TLS доступные алгоритмы и их представления также могут меняться, что отразится в значениях, возвращаемых этой переменной. Переменная обычно используется в сценариях, где требуется специфическая обработка в зависимости от стойкости алгоритма подписи, позволяя администраторам сервера применять политики безопасности. Переменная $ssl_sigalg в первую очередь используется в контексте виртуальных серверов с включённым SSL, где она может применяться в условных выражениях в директивах вроде `if`, или просто выводиться в форматах логов для целей мониторинга. Она добавляет уровень настраиваемости и информативности для пользователей, желающих обеспечить безопасные практики в отношении алгоритмов подписи, используемых клиентами, подключающимися к их сервисам.

Пример конфига

log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$ssl_sigalg"';

access_log /var/log/nginx/access.log custom_format;

Описание

В NGINX переменная $ssl_session_id представляет идентификатор сессии, связанный с текущей активной SSL-сессией. Эта переменная становится доступной после установления SSL-соединения и часто используется вместе с настройками кэширования SSL-сессий для оптимизации SSL/TLS-рукопожатий. Каждая установленная SSL-сессия может быть идентифицирована по своему ID сессии, который используется для возобновления сессии без необходимости повторно проводить рукопожатие. Эта переменная особенно полезна для мониторинга, логирования или безопасного управления пользовательскими сессиями. Как правило, $ssl_session_id представляет собой шестнадцатеричную строку, которая уникально идентифицирует SSL-сессию. Она создаётся в процессе рукопожатия и используется всякий раз, когда клиент пытается возобновить SSL-сессию. Если возобновление сессий не поддерживается или отключено, эта переменная может возвращать пустую строку. Поэтому важно убедиться, что на сервере включено кэширование SSL-сессий, чтобы эффективно использовать преимущества этой переменной. Типичные значения могут выглядеть как '00:11:22:33:44:55:66:77:88:99:AA:BB', что указывает на шестнадцатеричное представление ID сессии. Переменная применима в различных контекстах, например, в настройках логирования для фиксации информации о SSL-сессии или когда включены специальные политики доступа, основанные на свойствах SSL-сессии. Кроме того, использование связанных переменных, таких как $ssl_protocol и $ssl_cipher, в сочетании с $ssl_session_id может дать более полное представление.

Пример конфига

http {
    server {
        listen 443 ssl;
        ssl_certificate /etc/ssl/certs/my_cert.pem;
        ssl_certificate_key /etc/ssl/private/my_cert.key;

        location / {
            access_log /var/log/nginx/access.log combined;
            add_header X-SSL-Session-ID $ssl_session_id;
        }
    }
}

Описание

Переменная $ssl_session_reused устанавливается в 'on', если SSL-сессия была успешно повторно использована во время SSL handshake, и в 'off', если была создана новая сессия. Такое повторное использование обычно происходит, когда клиент переподключается к серверу с теми же параметрами SSL, что ускоряет процесс рукопожатия, поскольку устраняет необходимость полной повторной переговорки. NGINX использует session IDs или session tickets для облегчения повторного использования сессий. Если клиент предъявляет действительный session ID или ticket, который сервер распознаёт, он будет использовать существующую сессию, что приводит к снижению задержки и повышению производительности. Мониторинг этой переменной может помочь диагностировать эффективность управления SSL-сессиями в вашей конфигурации NGINX и особенно полезен в высокопроизводительных приложениях с частыми SSL-соединениями. Возможные значения $ssl_session_reused — 'on' или 'off', где 'on' указывает на повторное использование сессии, а 'off' обозначает новое SSL-соединение без повторного использования. Переменная обычно может быть найдена в response headers или log formats и помогает при устранении неполадок и анализе производительности.

Пример конфига

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

access_log /var/log/nginx/access.log main;

Описание

В NGINX переменная $ssl_early_data используется, когда сервер настроен на поддержку TLS 1.3, который предусматривает функцию, известную как "0-RTT" или ранние данные. Эта функция позволяет клиентам отправлять данные до полного завершения TLS-рукопожатия, что ускоряет обмен, но влечёт за собой определённые соображения по безопасности. Когда ранние данные получены, значение $ssl_early_data устанавливается в "1"; в противном случае оно устанавливается в "0". Эта переменная особенно полезна для определения того, как обрабатывать запросы, которые могли быть отправлены с использованием ранних данных. Например, опора на ранние данные может привести к рискам, таким как атаки повторного воспроизведения, поэтому пользователи должны реализовать необходимую логику для защиты от таких уязвимостей. NGINX может использовать значение этой переменной в условных конфигурациях, чтобы применять разные ограничения или ответы в зависимости от того, использовались ли ранние данные при запросе.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        # Check if early data was received
        if ($ssl_early_data) {
            return 400;  # Reject early data requests if needed
        }
        # Normal processing for regular requests
        proxy_pass http://backend;
    }
}

Описание

Переменная $ssl_server_name устанавливается в контексте NGINX server block с включённым SSL и в основном используется для определения того, какой виртуальный сервер обслуживает запрос на основе его имени сервера во время фазы SSL handshake. Когда клиент инициирует SSL-соединение с NGINX, сервер сравнивает запрошенное имя хоста с настроенными директивами 'server_name' в каждом server block. Используется первый совпавший сервер, и соответствующее имя сервера сохраняется в переменной $ssl_server_name. Если совпадающее имя сервера не найдено, $ssl_server_name будет пустой, и вместо него может использоваться имя сервера по умолчанию (если оно настроено). Эта переменная ведёт себя аналогично $server_name; однако она заполняется специально во время процесса SSL handshake, что позволяет использовать её для различных целей, таких как логирование, контроль доступа и формирование ответов на основе запрошенного имени хоста. Типичными значениями для $ssl_server_name будут DNS-имена, настроенные в server blocks, например 'example.com' или 'www.example.com'.

Пример конфига

server {
    listen 443 ssl;
    server_name example.com www.example.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    location / {
        add_header X-SSL-Server-Name "$ssl_server_name";
    }
}

Описание

Переменная $ssl_alpn_protocol характерна для конфигураций, которые используют HTTP/2 или другие протоколы, применяющие ALPN во время TLS-рукопожатия. Эта переменная устанавливается при установлении соединения по HTTPS и позволяет серверу определить, какой протокол прикладного уровня был выбран клиентом. Она особенно полезна для серверов, реализующих вариативность протоколов в сервисе, например при предоставлении контента как по HTTP/1.1, так и по HTTP/2, в зависимости от возможностей клиента. Значение этой переменной может быть названием протокола, например 'h2' для HTTP/2 или 'http/1.1', обозначающим согласованный протокол. Эта переменная особенно важна для оптимизации производительности, поскольку позволяет серверу отвечать на запросы клиента с использованием наиболее подходящего протокола, поддерживаемого клиентом согласно списку ALPN. Когда клиент инициирует TLS-рукопожатие, он может предлагать несколько протоколов, а сервер выбирает наиболее подходящий для этой сессии. Если клиент не поддерживает ни один из протоколов, предлагаемых сервером, переменная останется неустановленной, и обычно происходит откат к протоколу по умолчанию, часто HTTP/1.1. Механизм согласования повышает совместимость и производительность различных реализаций клиентов.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    # Using the variable in a log format to capture the negotiated protocol
    access_log /var/log/nginx/access.log custom_format;

    location / {
        if ($ssl_alpn_protocol = 'h2') {
            # Perform actions specific to HTTP/2
        }
        # Other processing...
    }
}

log_format custom_format '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" Protocol: $ssl_alpn_protocol';

Описание

Переменная $ssl_ech_status устанавливается в контексте SSL‑соединения, которое поддерживает Encrypted ClientHello (ECH). Она передаёт статус ECH клиента, определённый в процессе SSL‑handshake. Переменная может возвращать разные значения, указывающие, использовался ли ECH, или были ли какие‑либо ошибки, связанные с его использованием во время handshake. Обычные значения включают 'on', если ECH было успешно согласовано, 'off', если клиент не поддерживает его, и коды ошибок для других конкретных проблем. Обработка этой переменной происходит, когда сервер NGINX настроен с включённой поддержкой SSL и ECH. Когда клиент подключается и пытается инициировать ECH‑handshake, сервер оценивает запрос и соответствующим образом устанавливает $ssl_ech_status. Это позволяет вебмастерам реализовывать тонкую настройку управления доступом или настраивать ответы в зависимости от статуса ECH, что повышает возможности конфиденциальности для клиентов, которые его поддерживают. На практике переменная полезна для ведения логов или для написания условий в конфигурационных файлах, которые могут адаптировать ответы в зависимости от поддержки шифрования клиентом. Это может включать настройку поведения серверов приложений или даже перенаправление клиентов в зависимости от их возможностей по безопасности.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/key.pem;
    
    location / {
        if ($ssl_ech_status = 'on') {
            add_header X-ECH-Status 'Enabled';
        }
        if ($ssl_ech_status = 'off') {
            return 403;
        }
    }
}

Описание

Переменная `$ssl_ech_outer_server_name` — уникальная возможность, доступная в SSL-модуле NGINX, которая фиксирует внешнее имя сервера, предоставленное клиентом во время TLS-рукопожатия при использовании расширения Encrypted ClientHello (ECH). Это позволяет клиентам сохранять приватность относительно реального сервера, к которому они подключаются, одновременно давая серверам возможность решать, как обрабатывать запросы на основе предполагаемого имени назначения сервера. Эта переменная устанавливается во время SSL-рукопожатия, когда клиент согласовывает расширение ECH. Если клиент включает внешнее имя сервера в своём Encrypted ClientHello, эта переменная будет содержать это имя. Типичные значения для этой переменной — доменные имена или заголовки хоста, такие как 'www.example.com' или 'api.example.com', в зависимости от реализации ECH на стороне клиента. Если внешнее имя сервера не предоставлено или согласование ECH не удалось, переменная будет пустой. Использование этой переменной особенно полезно для приложений, которые хотят отвечать по-разному в зависимости от исходного предполагаемого назначения клиента, при этом сохраняя определённый уровень приватности в коммуникации. Однако для этой функциональности требуется совместимая настройка клиента для использования ECH, что означает, что не все запросы будут включать эту переменную в зависимости от конфигурации клиента во время рукопожатия.

Пример конфига

server {
    listen 443 ssl;
    server_name example.com;
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/cert.key;
    location / {
        if ($ssl_ech_outer_server_name) {
            add_header X-Outer-Server-Name $ssl_ech_outer_server_name;
        }
    }
}

Описание

Переменная $ssl_client_cert используется при проверке клиентского SSL-сертификата в NGINX. Эта переменная хранит SSL-сертификат клиента, предоставленный в ходе SSL-рукопожатия, в формате PEM-кодированной строки. Она устанавливается в значение сертификата клиента, когда директива 'ssl_verify_client' настроена в 'on' и сертификат успешно подтверждён. Она особенно полезна в сценариях, требующих защищённой связи, где проверка личности клиента необходима, например в API-службах или системах аутентификации пользователей. Если клиентский сертификат не предоставлен или проверка неуспешна, эта переменная будет пустой. Содержимое этой переменной может быть записано в лог, проверено в условных выражениях или при необходимости передано бэкенд-приложениям. Типичные случаи использования включают авторизацию доступа на основе атрибутов клиентского сертификата, таких как Common Name (CN) или Subject Alternative Name (SAN), что повышает безопасность на уровне приложения. Такой подход критичен для сервисов, которым необходимо надёжно удостоверять личность каждого клиента с использованием протоколов SSL/TLS.

Пример конфига

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;

    ssl_client_certificate /path/to/ca.pem;
    ssl_verify_client on;

    location / {
        if ($ssl_client_cert) {
            add_header X-Client-Cert $ssl_client_cert;
        }
    }
}

Описание

Переменная $ssl_client_raw_cert заполняется, когда NGINX настроен на обработку SSL/TLS-соединений и клиент предоставляет сертификат для аутентификации. Эта переменная становится доступной в контексте запроса, обрабатываемого по SSL-соединению, когда директива 'ssl_verify_client' установлена в 'on' или 'optional'. Необработанный клиентский сертификат выводится как одна строка, закодированная в base64, которую можно использовать для логирования, управления доступом или любой специфичной для приложения обработки, требующей информации о сертификате клиента. Эта переменная особенно полезна в защищённых средах, где реализована взаимная TLS-аутентификация (mTLS), поскольку она позволяет администраторам серверов и разработчикам приложений устанавливать правила на основе сертификата клиента, например логирование конфиденциальной информации для аудита или динамическое изменение обработки запроса на основе действительности сертификата или его атрибутов. Типичные значения этой переменной будут в формате base64, представляя X.509-сертификат клиента, переданный во время SSL handshake, что делает её критически важной в ситуациях, требующих проверки личности между доверенными сторонами. На практике NGINX может напрямую записывать содержимое сертификата в логи или условно перенаправлять запросы на основе атрибутов сертификата (например, subject или issuer). Параметры, такие как 'ssl_verify_client', требуют тщательной настройки, поскольку они могут напрямую повлиять на безопасность приложения.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_verify_client on;

    location / {
        add_header X-Client-Cert $ssl_client_raw_cert;
        # Additional processing...
    }
}

Описание

Переменная $ssl_client_escaped_cert используется в контексте HTTP-сервера, когда HTTPS-соединения применяют аутентификацию по клиентским сертификатам. Когда клиент устанавливает защищённое соединение и предоставляет сертификат, эта переменная фиксирует полные сведения о сертификате в формате, который одновременно является URL-encoded и безопасно экранирован для передачи. Это особенно полезно для ведения журналов или передачи в качестве параметров запроса без возникновения синтаксических ошибок в URL. Эта переменная устанавливается только в случае, если проверка клиентского сертификата включена и при SSL-рукопожатии представлен действительный клиентский сертификат. Она содержит закодированное содержимое сертификата клиента, позволяя приложениям на стороне сервера использовать идентичность клиента для целей авторизации или управления доступом. Типичные значения этой переменной включают фактические данные сертификата в формате PEM-encoded, которые состоят из компонентов сертификата, закодированных в Base64-encoded, и заключённых между соответствующими PEM-заголовком и PEM-футером. Если клиентский сертификат не представлен, переменная остаётся пустой. В сочетании с другими переменными, связанными с SSL, такими как $ssl_client_cert и $ssl_client_verify, $ssl_client_escaped_cert обеспечивает всесторонний механизм управления проверкой клиента в защищённых средах, охватывающий сценарии, требующие не только подтверждения личности, но и безопасной передачи данных сертификата для дальнейшей обработки.

Пример конфига

server {
    listen 443 ssl;
    server_name example.com;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_client_certificate /path/to/client_ca.crt;
    ssl_verify_client on;

    location /secure-data {
        add_header X-Client-Cert "$ssl_client_escaped_cert";
    }
}

Описание

Переменная $ssl_client_s_dn заполняется, когда клиент предоставляет действительный SSL/TLS-сертификат во время обмена рукопожатием SSL/TLS, и содержит имя субъекта (DN) клиента, указанное в этом сертификате. Эта переменная извлекается из сертификата клиента и служит способом идентификации владельца сертификата путём представления атрибутов имени субъекта, которые обычно включают информацию, такую как common name, organization, country и другие соответствующие поля. Наличие и содержимое этой переменной зависят от установки директивы `ssl_verify_client` в значение "on" или "optional", что гарантирует, что NGINX требует либо запрашивает клиентский сертификат. Только после успешной проверки действительного клиентского сертификата эта переменная становится доступна в контексте NGINX.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_verify_client on;

    location / {
        if ($ssl_client_s_dn) {
            add_header X-Client-DN $ssl_client_s_dn;
        }
    }
}

Описание

Переменная $ssl_client_i_dn заполняется при установлении SSL/TLS-соединения с использованием клиентских сертификатов. Конкретно, она содержит distinguished name (DN) клиента, представленный сертификатом клиента во время TLS handshake process. Эта переменная доступна прежде всего в контекстах, требующих аутентификации клиента по SSL/TLS, которую нужно включить в конфигурации NGINX с помощью директив, таких как 'ssl' и 'ssl_verify_client'. Как правило, DN будет включать информацию, такую как общее имя клиента (CN), организация (O) и страна (C), отформатированные в соответствии со стандартом X.500. Когда переменная установлена, её можно использовать в различных конфигурациях — от настройки контроля доступа на основе идентичности клиента до кастомизации ответов в зависимости от того, кто является клиентом. Однако если клиентские сертификаты не используются в SSL/TLS-соединении, эта переменная не будет содержать данных. Важно отметить, что эта переменная зависит от успешной аутентификации клиента; если клиент не предоставит действительный сертификат или если проверка не пройдет, $ssl_client_i_dn будет пустой. Наличие этой переменной критично для приложений, где требуется проверка личности пользователя на основе клиентских сертификатов.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_verify_client on;

    location / {
        if ($ssl_client_i_dn) {
            return 200 'Client DN: $ssl_client_i_dn';
        }
        return 403 'Access denied';
    }
}

Описание

Переменная $ssl_client_s_dn_legacy заполняется, когда сервер NGINX устанавливает SSL/TLS‑соединение, требующее аутентификации клиента. Конкретно, она извлекает различительное имя субъекта (DN) сертификата клиента, которое содержит информацию, например, об идентификации клиента, организации и стране, отформатированную в соответствии со стандартами X.509. Значение обычно возвращается как строка, где элементы DN представлены в текстовом формате, например 'C=US, ST=California, L=San Francisco, O=Example Corp, CN=example.com'. Эта переменная устанавливается только при включённой директиве `ssl_verify_client`, которая требует от клиентов предъявления действительных SSL-сертификатов. Если клиентский сертификат не представлен или не проходит проверку, переменная будет пустой. Это может быть полезно для целей логирования, контроля доступа или логики приложения, зависящей от идентичности клиента. Типичные значения могут сильно различаться в зависимости от используемых клиентских сертификатов, а формат соответствует стандартному представлению DN. На практике эта переменная может применяться в разных конфигурациях для проверок безопасности, условной обработки на основе идентичности клиента или просто для записи сведений о соединении с целью лучшего аудита доступа к веб‑сервису. Например, приложение может использовать эту переменную для обеспечения контроля доступа на основе организации клиента или для записи данных о клиенте в аналитических целях.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_client_certificate /path/to/ca.crt;
    ssl_verify_client on;

    location /protected {
        if ($ssl_client_s_dn_legacy) {
            add_header X-Client-DN $ssl_client_s_dn_legacy;
        }
    }
}

Описание

Переменная $ssl_client_i_dn_legacy устанавливается при обработке клиентских запросов на сервере NGINX, настроенном для использования SSL/TLS с аутентификацией клиента. Когда клиент предъявляет SSL-сертификат во время рукопожатия, сервер обрабатывает этот сертификат и извлекает различные сведения, включая имя субъекта (DN) клиента. DN включает атрибуты, такие как общее имя (CN), организация (O) и страна (C). В случае $ssl_client_i_dn_legacy переменная возвращает этот DN в формате, совместимом с более ранними версиями NGINX, и предназначена главным образом для обратной совместимости. Формат этой строковой записи DN может различаться в зависимости от способа выдачи клиентского сертификата и конкретных данных сертификата.

Пример конфига

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /path/to/your/cert.pem;
    ssl_certificate_key /path/to/your/key.pem;

    ssl_client_certificate /path/to/your/ca.pem;
    ssl_verify_client on;

    location / {
        add_header X-Client-DN $ssl_client_i_dn_legacy;
    }
}

Описание

Переменная $ssl_client_serial устанавливается, когда NGINX настроен на обработку SSL/TLS-соединений, которые требуют клиентских сертификатов для аутентификации. Она извлекает серийный номер клиентского SSL-сертификата, если проверка клиента включена, что обычно происходит в серверном блоке, сконфигурированном с директивой "ssl_verify_client", установленной в значение "on" или "optional". При представлении действительного клиентского сертификата во время TLS-рукопожатия NGINX может получить доступ к различным атрибутам сертификата, включая серийный номер, который является уникальным идентификатором экземпляра сертификата. Значение $ssl_client_serial часто представлено в виде шестнадцатеричной строки, представляющей серийный номер сертификата. Если проверка клиента не включена или клиент не предоставил сертификат, эта переменная не будет установлена и вернёт пустую строку. Эта переменная особенно полезна для реализации механизмов контроля доступа, логирования или аудита на основе идентичности используемых клиентских сертификатов.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate     /path/to/your/server.crt;
    ssl_certificate_key /path/to/your/server.key;
    ssl_verify_client on;

    location / {
        if ($ssl_client_serial) {
            add_header X-Client-Serial $ssl_client_serial;
        }
    }
}

Описание

Переменная $ssl_client_fingerprint используется в NGINX, когда включена аутентификация SSL-клиента. Она предоставляет уникальный отпечаток SSL-сертификата клиента, основанный на криптографическом хеше, обычно вычисляемом с помощью алгоритмов хеширования SHA-1 или SHA-256. Этот отпечаток получается из данных сертификата, в частности из структуры `tbsCertificate`. Переменная устанавливается только в случае успешного выполнения аутентификации SSL-клиента, то есть когда сервер настроен требовать клиентские сертификаты и клиент предоставил действительный сертификат во время SSL handshake. Типичные значения этой переменной будут представлять собой шестнадцатеричную строку, соответствующую хешу сертификата клиента. Это полезно для ведения логов, контроля доступа и применения дополнительной пользовательской логики на основе идентичности клиента.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_client_certificate /path/to/ca.crt;
    ssl_verify_client on;

    location / {
        # Use the fingerprint in access logs
        access_log /var/log/nginx/access.log combined; # Redis or any other designated log format
        set $client_fp $ssl_client_fingerprint;
        if ($client_fp) {
            # More logic can be applied here based on the fingerprint
        }
    }
}

Описание

Переменная $ssl_client_verify устанавливается, когда сервер NGINX настроен на использование проверки клиентских сертификатов в SSL. Эта переменная может принимать определённые значения, которые представляют результат процесса проверки клиентского SSL-сертификата. Она может быть установлена в 'none', если клиентский сертификат не был представлен, в 'off', если проверка клиента не включена, и в 'success' или 'failed' в зависимости от исхода процесса проверки. Эта функциональность является частью основного SSL-модуля NGINX, который управляет защищёнными соединениями и обеспечивает, чтобы клиенты предъявляли действительные сертификаты, которые можно проверить относительно доверенных CA-сертификатов, настроенных в NGINX. Когда проверка клиентских сертификатов включена через директивы, таких как "ssl_verify_client", сервер использует эту переменную для оценки того, был ли предоставлен действительный клиентский сертификат в процессе SSL-рукопожатия. Проверка может включать проверки срока действия сертификата, статуса отзыва и того, подписан ли сертификат доверенным удостоверяющим центром (CA). При обработке запроса NGINX устанавливает значение $ssl_client_verify, чтобы отразить результат, который затем может использоваться для условной обработки или логирования в блоках конфигурации.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_client_certificate /path/to/trusted_ca.crt;
    ssl_verify_client on;

    location /private {
        if ($ssl_client_verify != "success") {
            return 403;
        }
        # handle the request for authenticated clients
    }
}

Описание

Переменная $ssl_client_v_start является частью поддержки SSL/TLS в NGINX и особенно полезна для целей логирования и отладки. Она фиксирует время начала SSL handshake — точнее, момент, когда устанавливается SSL connection между клиентом и сервером. Эта временная метка выражается в секундах с начала эпохи (1 января 1970 года). Эта переменная становится доступной после установления SSL connection в процессе обработки запроса. Значение $ssl_client_v_start доступно в контексте запроса, что позволяет NGINX записывать точный момент наступления этого события. Знание времени начала SSL connection помогает разработчикам и системным администраторам при мониторинге производительности, поскольку это помогает понять длительность SSL handshake и устранять связанные с этим проблемы задержек. Типичные значения этой переменной будут иметь формат UNIX timestamps, такие как '1672531199'.

Пример конфига

server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate /etc/ssl/certs/example.com.crt;
    ssl_certificate_key /etc/ssl/private/example.com.key;

    access_log /var/log/nginx/access.log combined;

    location / {
        add_header X-SSL-Client-V-Start "$ssl_client_v_start";
    }
}

Описание

Переменная $ssl_client_v_end доступна, когда NGINX настроен на использование SSL, и предоставляет доступ ко времени окончания SSL-сессии клиента. Эта метка времени обычно устанавливается, когда SSL-соединение завершено и клиент закончил SSL-рукопожатие. Значение выражается в количестве секунд, прошедших с 1 января 1970 года (эпоха Unix). При установлении SSL-соединения с клиентом регистрируется несколько отметок времени для различных событий, включая моменты начала и окончания сессии. Переменная $ssl_client_v_end конкретно фиксирует момент, когда SSL-соединение клиента официально завершается. Это может быть полезно для логирования, аналитики и других задач, где важно понимать длительность или время SSL-соединения. Значения этой переменной — отметки времени в формате Unix-времени, например, типичное значение может выглядеть как 1682467654, соответствующее определённой дате и времени в UTC. В сценариях, где сессии нужно управлять или контролировать, эта переменная помогает отслеживать жизненный цикл защищённого взаимодействия между клиентом и сервером, давая представление о том, когда соединения устанавливаются и завершаются; это особенно полезно в условиях высокого трафика, где производительность обеспечения безопасности имеет первостепенное значение.

Пример конфига

server {
    listen       443 ssl;
    server_name  example.com;

    ssl_certificate      /path/to/cert.pem;
    ssl_certificate_key  /path/to/key.pem;

    location / {
        access_log /var/log/nginx/access.log;
        set $end_time $ssl_client_v_end;
        # additional configuration
    }
}

Описание

Переменная $ssl_client_v_remain является частью SSL-модуля NGINX и используется при обработке сертификатов клиента. Когда клиент предоставляет сертификат для аутентификации, он часто отправляет цепочку сертификатов. Переменная $ssl_client_v_remain показывает, сколько байт остаётся в этой цепочке после обработки текущего сертификата. Это особенно полезно при управлении сложными сценариями аутентификации, где участвуют несколько сертификатов, например при настройках взаимной TLS-аутентификации (mTLS). Эта переменная устанавливается во время рукопожатия SSL и доступна директивам сервера после успешного завершения рукопожатия SSL. Она возвращает числовое значение, отражающее остаток данных сертификата, которые ещё предстоит прочитать. Как правило, значение может варьироваться от нуля (когда все сертификаты обработаны) до общей длины исходной цепочки сертификатов, отправленной клиентом. Например, если клиент отправляет цепочку из трёх сертификатов общей длиной 300 байт, и первый сертификат (примерно 100 байт) обработан, то $ssl_client_v_remain покажет 200 байт после этой обработки. Эта информация позволяет NGINX принимать обоснованные решения на основе конфигурации SSL-сервера и любых заданных требований к аутентификации на основе действительных сертификатов.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate     server.crt;
    ssl_certificate_key server.key;

    location / {
        if ($ssl_client_v_remain > 0) {
            add_header X-SSL-Client-Remain $ssl_client_v_remain;
        }
    }
}

Описание

Переменная $ssl_client_sigalg устанавливается, когда клиент предоставляет SSL-сертификат в ходе TLS-рукопожатия. Она хранит алгоритм подписи, которым был подписан сертификат клиента. Эта переменная критически важна для приложений, которые проверяют клиентские сертификаты и могут принять решение о предоставлении или отказе в доступе на основании уровня безопасности алгоритма подписи. Значения $ssl_client_sigalg могут различаться; распространённые алгоритмы включают 'sha256WithRSAEncryption', 'sha1WithRSAEncryption' и другие, в зависимости от конфигурации клиента и политик безопасности. NGINX будет устанавливать эту переменную только в контекстах, где включены клиентские SSL-сертификаты, конкретно в блоках 'server' и 'location', где директива ssl_verify_client установлена в 'on' или 'optional'. Если клиентский сертификат не предоставлен, переменная будет пустой. Это особенно полезно для ведения логов или отладки, поскольку позволяет администраторам серверов увидеть, какие алгоритмы подписи используют клиенты при обращении к их сервисам, и принимать обоснованные решения на основе этой информации. Кроме того, изменения в конфигурациях клиентского SSL могут изменить генерируемые здесь значения и должны соответствующим образом контролироваться.

Пример конфига

server {
    listen 443 ssl;
    ssl_certificate /path/to/server.crt;
    ssl_certificate_key /path/to/server.key;
    ssl_client_certificate /path/to/client_ca.crt;
    ssl_verify_client on;

    location / {
        if ($ssl_client_sigalg = 'sha256WithRSAEncryption') {
            # Log or take action for clients using SHA256
            access_log /var/log/nginx/ssl.log;
        }
    }
}

Описание

Переменная $realip_remote_addr предназначена для получения фактического удалённого IP-адреса клиента, когда NGINX настроен на работу за прокси или балансировщиком нагрузки. Такая ситуация часто возникает, когда клиент подключается через промежуточный сервер, и по стандартным методам соединения сложно определить исходный IP-адрес клиента. NGINX эффективно решает эту задачу с помощью заголовков X-Real-IP или X-Forwarded-For HTTP, которые являются общепринятыми стандартами передачи исходного IP-адреса. Когда NGINX получает запрос, он проверяет эти заголовки в указанном порядке, и если в одном из заголовков найден IP-адрес, переменная $realip_remote_addr устанавливается в это значение. Если заголовки отсутствуют, переменная по умолчанию принимает прямой IP-адрес клиента, видимый с точки зрения NGINX. Правильная интерпретация этой переменной обычно требует корректной настройки как параметров вышестоящего прокси, так и заголовков, используемых для передачи IP-адресов клиентов. Это обеспечивает корректное отображение и запись информации, что приводит к более точным данным и мерам безопасности. Как правило, значение $realip_remote_addr отражает либо фактический удалённый IP-адрес клиента, отправившего запрос, либо возвращается к последнему известному IP-адресу, если исходный определить не удалось. Это особенно важно в сценариях с множественными уровнями сетей, поскольку улучшает ведение журналов и возможности контроля доступа, обеспечивая точную идентификацию клиента.

Пример конфига

http {
    set_real_ip_from 192.0.2.0/24; # Allow this range to set the real IP
    real_ip_header X-Forwarded-For;   # Specify the header to use

    server {
        listen 80;
        location / {
            # Access can be logged with the original client's IP
            access_log /var/log/nginx/access.log main;
        }
    }
}

Описание

Переменная $realip_remote_port используется в контексте реверс-проксирования и указывает исходный номер порта, который использовал клиент при подключении к серверу. Она особенно полезна, когда NGINX работает за балансировщиком нагрузки или прокси, и фактические данные о подключении клиента необходимы для логирования или другой обработки. Эта переменная становится доступной при использовании модуля real_ip, который позволяет NGINX корректно определять IP и порт клиента, когда запросы пересылаются с другого сервера, например с веб-аппликационного межсетевого экрана (WAF) или балансировщика нагрузки. Обычно эта переменная содержит числовые значения, представляющие номер порта, например 443 для HTTPS или 80 для HTTP, в зависимости от того, как клиент изначально подключился. Если директива `real_ip_header` в конфигурации NGINX корректно настроена для захвата заголовков входящих запросов (например, X-Forwarded-For), то переменная $realip_remote_port будет точно отражать порт, который использовал клиент, при условии, что конфигурация верна и соответствующие заголовки присутствуют. Неправильная настройка может привести к некорректному логированию и неверной идентификации подключений клиентов. В сущности, переменная $realip_remote_port повышает возможности безопасности и мониторинга, обеспечивая возможность приложениям ссылаться на реальные данные о подключениях клиентов при их обработке через различные промежуточные серверы.

Пример конфига

http {
    set_real_ip_from 192.168.1.1;  # Example trusted proxy
    real_ip_header X-Forwarded-For;
}

server {
    location / {
        access_log /var/log/nginx/access.log combined;
    }
}

# In the combined log format, you can include the realip remote port
log_format combined '$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" $realip_remote_port';

Описание

Переменная $invalid_referer используется в NGINX, чтобы указать, считается ли заголовок referer входящего HTTP-запроса недействительным в соответствии с заранее определёнными правилами доступа. Эта переменная в первую очередь связана с `ngx_http_access_module`, который позволяет администраторам задавать разрешённые или запрещённые referer с помощью директив `allow` и `deny` в конфигурационном файле. Когда запрос обрабатывается, модуль проверяет заголовок `Referer` по отношению к настроенным правилам. Если referer не соответствует ни одной из разрешённых записей и попадает под условие deny, $invalid_referer устанавливается в 1. Эта функциональность особенно полезна в сценариях, где важна безопасность содержимого, например для предотвращения использования ресурсов неавторизованными сайтами. Переменная обычно возвращает значение 1, когда referer неверен; в противном случае она не установлена, что означает корректный referer. Важно учитывать, что referer может быть подделан клиентом, поэтому полагаться только на проверку referer для обеспечения безопасности не следует. Переменная $invalid_referer может помочь контролировать доступ к ресурсам, реализуя условную логику в конфигурации NGINX на основе её значения, что позволяет более тонко управлять доступом и механизмами безопасности.

Пример конфига

location /protected {
    valid_referers none blocked example.com;
    if ($invalid_referer) {
        return 403;
    }
}

Описание

Переменная $secure_link используется в NGINX для управления и проверки защищённых ссылок на ресурсы, такие как файлы или данные, обеспечивая, что доступ ограничен авторизованными пользователями на основе токенов. Когда защищённая ссылка генерируется, она обычно хэшируется с использованием параметров, включая document root, URI и expiration timestamp, среди прочих. Таким образом, эта переменная содержит значение этого хэшированного линка, которое клиенты используют для аутентификации и получения доступа к защищённому ресурсу. Переменная устанавливается при определённых условиях, в частности, когда включён secure_link module и в конфигурации задана соответствующая `secure_link` директива в контексте http, server или location. Она валидирует запросы, сравнивая предоставленный токен с ожидаемой защищённой ссылкой, гарантируя, что ссылки имеют ограниченный срок действия (действительны только в течение определённого периода) и уникальны для каждого клиента. Типичные значения для этой переменной обычно отражают хэш, сгенерированный на основе настроек, установленных в директивах secure_link. На практике это помогает предотвратить несанкционированный доступ к конфиденциальным файлам, что делает механизм полезным для приложений, которым требуется защита контента, таких как приватные медиафайлы или загрузки программного обеспечения. Для обеспечения корректной работы необходимо тщательно управлять не только генерацией этих токенов, но и их сроком действия и политиками деактивации для повышения безопасности доступа.

Пример конфига

location /protected_file {
    secure_link $arg_st,$arg_e;
    secure_link_secret your_secret;

    # Validate secure link
    if ($secure_link = "") {
        return 403; # deny access
    }

    # Allow access if validation passes
    root /path/to/your/files;
    add_header Content-Disposition "attachment; filename=protected_file";
}

Описание

Переменная `$secure_link_expires` в NGINX содержит время истечения срока действия защищённой ссылки, которое задаётся при использовании директивы `secure_link`. Эта переменная обычно устанавливается вместе с переменной `$secure_link`, которая генерирует уникальную подпись для доступа к защищённым URL. Возвращаемое время истечения определяется в Unix timestamp формате, указывая, когда защищённый ресурс станет недоступен. Если значение не задано явно, оно по умолчанию равно 0, что делает ссылку действительной бесконечно долго, если только это не ограничено настройками конфигурации. При использовании механизма `$secure_link` обычно задают и саму ссылку, и её срок действия, чтобы предоставить временный доступ к ресурсам. Время истечения можно установить параметром `expires` в директиве `secure_link`, указанной в конфигурации NGINX. Указывая подходящие значения истечения, например текущее время плюс некоторый промежуток (например, один день в секундах), вы можете эффективно управлять доступом к ресурсам на основе временных ограничений. Эта переменная может быть полезна в сценариях, когда требуется ограничить доступ к файлам по времени, например к медиа-контенту, файлам для скачивания или другим конфиденциальным ресурсам. Комбинируя её с директивами управления доступом, вы можете создавать безопасные краткосрочные ссылки для аутентифицированного доступа пользователей, повышая безопасность вашего приложения.

Пример конфига

location /protected {
    secure_link $arg_md5,$secure_link_expires;
    secure_link_md5 "$uri$time$key";
    if ($secure_link = 0) {
        return 403;
    }
}

Описание

Переменная $uid_got в NGINX представляет собой уникальный идентификатор пользователя, связанного с запросом. Эта переменная обычно устанавливается ядром NGINX при обработке запроса. Она особенно полезна в конфигурациях, которые требуют управления доступом на основе прав пользователя или при отслеживании действий пользователя в логах. Когда запрос поступает, NGINX проверяет связанный идентификатор пользователя, который может быть получен из различных источников, включая системных пользователей, для проверок аутентификации и авторизации. В средах, использующих управление доступом на основе пользователей, например при интеграции с приложениями, требующими отдельных прав для разных пользователей, переменная $uid_got становится важной. Переменная заполняется при установлении соединения и отражает UID, назначенный этому соединению. Учитывая свою природу, значение может варьироваться в зависимости от того, как обрабатывается запрос и в каком контексте он выполняется. Обычно вы увидите значения в диапазоне от 0 до 65535, соответствующие распространённым идентификаторам пользователей (или зарезервированным идентификаторам) в UNIX-подобной системе. Для повышения безопасности и точного логирования переменную $uid_got можно записывать в настраиваемом формате логов NGINX или использовать в условных конфигурациях для ограничения доступа на основе идентификации пользователя, что помогает выстроить надёжную стратегию управления доступом.

Пример конфига

location /protected {
    if ($uid_got = 1001) {
        return 403;  # Deny access to users with UID 1001
    }
    proxy_pass http://backend;
}

Описание

Переменная $uid_set определяется в NGINX Core и используется для отражения идентификатора пользователя, установленного для текущего запроса. Эта переменная особенно важна при обработке специфических правил контроля доступа и настроек безопасности, основанных на идентичности пользователя. Идентификатор пользователя обычно устанавливается через механизмы аутентификации, когда пользователь успешно проходит вход или отправляет запрос с учетными данными. Значение $uid_set часто изменяется внутренними модулями, которые извлекают учетные данные пользователя из заголовков или токенов сессии. Значение этой переменной может измениться в ходе выполнения запроса, если запрос подвергается перенаправлению или если серверное приложение изменяет контекст аутентификации. Типичными значениями для $uid_set могут быть числовое представление идентификатора пользователя или пустая строка, когда аутентифицированный пользователь не обнаружен.

Пример конфига

server {
    listen       80;
    server_name  example.com;

    location / {
        if ($uid_set) {
            return 200 'User ID is set';
        }
        return 403 'Access denied';
    }
}

Описание

Переменная $uid_reset используется в контексте контроля доступа на сервере NGINX. Она предназначена для управления сбросом идентификаторов пользователей (UID) для входящих соединений в соответствии с заданными правилами доступа. Переменная устанавливается в '1', когда запрос отклонён на основании совпадающего критерия контроля доступа, например блоков IP-адресов, заданных директивами 'allow' и 'deny'. Если запрос разрешён, $uid_reset остаётся '0'. Такое поведение важно для приложений, которым требуется логика, зависящая от того, был ли доступ пользователя отклонён, что позволяет реализовать настраиваемые ответы или механизмы журналирования на основе этого состояния. Фактическая установка переменной происходит во время выполнения модуля доступа, в частности при обработке входящих запросов. Конкретно, если правило явно запрещает доступ по определённому условию, NGINX обновляет переменную $uid_reset, чтобы отразить это отклонение. Поэтому пользователи этой переменной в своих конфигурациях могут использовать её для условного выполнения директив или для записи конкретных случаев, когда UID пользователя сбрасывается в рамках логики контроля доступа, что способствует усилению безопасности и управлению правами доступа.

Пример конфига

http {
    server {
        location / {
            allow 192.168.1.0/24;
            deny all;
            if ($uid_reset) {
                return 403;
            }
            proxy_pass http://backend;
        }
    }
}

Описание

Переменная $gzip_ratio — это динамическая переменная в NGINX, которая представляет отношение размера сжатого ответа к исходному размеру ответа при включённой gzip-компрессии. Эта переменная вычисляется в момент отправки ответа, конкретно когда используется модуль 'gzip' для сжатия вывода перед его отправкой клиенту. Значение рассчитывается на основе сравнения размера несжатого ответа с размером сжатого ответа, что позволяет оценить, насколько эффективно сжатие. Когда модуль 'gzip' включён в NGINX и ответ сжимается, переменная $gzip_ratio устанавливается после завершения сжатия. Типичное выходное значение может варьироваться от 1 до 100: значение 100 означает, что ответ вовсе не был сжат, а более низкие значения указывают на лучшую эффективность сжатия. Разработчики могут использовать эту переменную для мониторинга производительности и настройки параметров gzip, обеспечивая оптимальное использование пропускной способности и более быструю загрузку для пользователей. В случаях, когда gzip не может эффективно сжать ответ, переменная может показывать коэффициент сжатия 100. Это позволяет администраторам выявлять ситуации, когда определённые типы содержимого (такие как уже сжатые файлы — например, изображения JPEG) не следует обрабатывать настройками gzip, поскольку дополнительное сжатие не даст преимуществ.

Пример конфига

gzip on;
gzip_min_length 1024;
set $compression_ratio $gzip_ratio;

Описание

Переменная $limit_conn_status используется в NGINX для указания состояния ограничений соединений, применённых к запросам от клиентов. Когда ограничение соединений включено с помощью директив 'limit_conn', эта переменная устанавливается, чтобы отразить состояние соединений клиента относительно заданных лимитов. Типичные значения этой переменной включают 'none' (указывает, что никакое ограничение не превышено), 'exceeded' (когда клиент превышает разрешённое число соединений) или 'aborted' (когда обработка соединения прерывается). Значение $limit_conn_status особенно полезно для ведения логов или для условной обработки в конфигурации NGINX. Оно даёт важную информацию об ограничениях соединений, наложенных сервером на клиентов. Эту информацию можно использовать для создания пользовательских ответов или для записи в журнал конкретных событий на основе поведения соединений клиента. NGINX устанавливает эту переменную во время обработки запроса после оценки ограничений соединений, задаваемых такими директивами, как 'limit_conn_zone' и 'limit_conn'.

Пример конфига

http {
    limit_conn_zone $binary_remote_addr zone=addr:10m;

    server {
        limit_conn addr 1;

        location / {
            if ($limit_conn_status = exceeded) {
                return 503;
            }
            # Other configurations...
        }
    }
}

Описание

Переменная $limit_req_status используется в конфигурации NGINX для указания кода ответа, возникающего в результате директив ограничения частоты запросов, определённых в модуле 'limit_req'. Когда запрос превышает установленный предел, NGINX может возвращать определённые коды состояния, такие как 503 (Сервис недоступен) или 503 с сообщением 'превышен лимит'. Переменная $limit_req_status фиксирует эти коды и делает их доступными для логирования или дальнейшей обработки. Эта переменная особенно полезна для создания пользовательских страниц ошибок или для различной обработки ответов в зависимости от кода состояния. Например, если запрос был ограничен из-за слишком большого количества запросов за короткий период, вы можете использовать значение $limit_req_status в конфигурации, чтобы управлять тем, как информировать пользователей о достижении лимита. Обычно она может возвращать такие значения, как 200 для нормальных запросов, 503 для запросов, отклонённых в результате ограничения частоты, или другие коды состояния, настроенные в приложении. Важно понимать, что переменная $limit_req_status заполняется только тогда, когда корректный запрос проходит через директиву limit_req и подпадает под поведение ограничения частоты. Если ограничение частоты не применяется или запрос не достигает этой директивы, переменная остаётся неустановленной.

Пример конфига

server {
    location /api {
        limit_req zone=one burst=5;
        if ($limit_req_status = 503) {
            return 429 'Too Many Requests';
        }
    }
}

Описание

В stream-модуле NGINX переменная $bytes_received динамически задаётся, чтобы отражать количество байтов, полученных от клиента в течение конкретного соединения. Она помогает контролировать объём данных, который сервер получил через потоки данных TCP или UDP. Каждый раз при получении данных от клиента эта переменная обновляется соответствующим образом и может использоваться в логах или при сборе метрик производительности. Следовательно, $bytes_received по сути считает все байты, включая заголовки и полезную нагрузку, что делает её удобным инструментом для анализа пропускной способности.\n\nЭта переменная инициализируется в начале соединения и доступна для использования в различных контекстах, связанных с активными соединениями. Например, в форматах логов, модулях мониторинга или при реализации ограничения скорости на основе общего количества полученных байтов. Типичные значения $bytes_received могут сильно варьироваться в зависимости от приложения, но обычно масштабируются от нескольких байтов до нескольких мегабайт и более при высокой нагрузке, в зависимости от типа трафика и настроек stream-сервера NGINX.

Пример конфига

stream {
    server {
        listen 12345;
        access_log /var/log/nginx/stream_access.log "$remote_addr - $bytes_received bytes received";
    }
}

Описание

Переменная $session_time в NGINX используется для измерения продолжительности текущей потоковой сессии, в частности в модуле Stream. Эта переменная устанавливается, когда сервер NGINX устанавливает соединение для потока, и продолжает обновляться до тех пор, пока соединение не будет закрыто или завершено. Она представляет собой общее время в секундах, в течение которого сессия была активна, что делает её полезной для целей мониторинга и ведения журналов, а также для настройки ограничений на сессии на основе их продолжительности. Как правило, $session_time начинается с нуля при инициации соединения и будет увеличиваться по мере течения времени, отражая текущую длительность сессии. Это значение может быть особенно полезно в конфигурациях, где необходимо применять таймауты сессий, или при анализе производительности и шаблонов использования сессий в потоковом приложении. Важно отметить, что эта переменная специфична для модуля Stream и недоступна в HTTP или других модулях. Соответственно, она в основном используется в сценариях, где задействована потоковая передача на основе TCP/UDP, а не в стандартных сценариях обслуживания веб-контента.

Пример конфига

stream {
    server {
        listen 12345;
        log_format custom_format '$remote_addr - $session_time';
        access_log /var/log/nginx/stream_access.log custom_format;
    }
}

Описание

Переменная $protocol в NGINX Stream — автоматически задаваемая переменная, которая становится доступной в той же области видимости, что и другие stream directives, особенно во время stream block execution. Эта переменная указывает протокол установленного соединения — TCP или UDP. Она преимущественно используется для организации логирования, управления доступом или условной конфигурации в зависимости от типа обрабатываемого протокола. Переменная устанавливается при установлении соединения с сервером, в зависимости от протокола, указанного в server и upstream blocks. Типичные значения этой переменной включают 'tcp' и 'udp', что даёт чёткое различие типов обрабатываемого трафика. Это особенно полезно в средах, где один и тот же процесс сервера обрабатывает как TCP, так и UDP, позволяя применять разные конфигурации и стратегии логирования в зависимости от протокола.

Пример конфига

stream {
    server {
        listen 12345;
        proxy_pass backend;
        log_format custom_format '$remote_addr - $protocol';
        access_log /var/log/nginx/access.log custom_format;
    }
}

Описание

Переменная $remote_passwd является частью модуля NGINX CoolKit и играет ключевую роль в обработке базовой HTTP-аутентификации. Конкретно, она извлекает декодированный пароль, который содержится в заголовке 'Authorization' HTTP‑запроса, когда клиент проходит аутентификацию с помощью имени пользователя и пароля. Когда клиент отправляет запрос аутентификации, имя пользователя и пароль обычно кодируются в base64 и отправляются в формате 'Authorization: Basic base64(username:password)'. NGINX с помощью модуля CoolKit декодирует эту информацию, чтобы пароль мог быть использован в последующей обработке. Переменная устанавливается во время обработки HTTP‑запросов, которые содержат заголовок Authorization. Если заголовок отсутствует или не соответствует ожидаемому формату для базовой аутентификации, значение $remote_passwd будет пустым. Это означает, что в защищённых приложениях, где важны авторизация и проверка личности, эту переменную необходимо использовать осторожно, проверяя наличие действительных учетных данных перед использованием пароля в логике приложения. На практике $remote_passwd может быть критически важной информацией при работе с аутентификацией на бэкенде против баз данных или сервисов, которые требуют проверки имени пользователя и пароля, как показано в примерах конфигурации, приведённых в документации модуля.

Пример конфига

location = /auth {
    internal;
    set_quote_sql_str  $user $remote_user;
    set_quote_sql_str  $pass $remote_passwd;
    postgres_pass      database;
    postgres_query     "SELECT login FROM users WHERE login=$user AND pass=$pass";
    postgres_rewrite   no_rows 403;
    postgres_output    none;
}

Описание

Переменная $location в NGINX CoolKit Module содержит имя совпавшего блока location для входящего запроса. Она вычисляется при обработке HTTP-запроса всякий раз, когда NGINX обрабатывает директивы location в своей конфигурации. По мере прохождения запроса через конфигурацию NGINX проверяет каждый блок location, чтобы найти наиболее конкретное совпадение для запрошенного URI. Как только совпадение найдено, имя соответствующего блока location сохраняется в этой переменной. Типичные значения переменной $location могут быть точными путями, например '/auth', или более сложными шаблонами, определёнными регулярными выражениями. Эта функциональность полезна для логирования, условной обработки и настройки ответов в зависимости от совпавшего location. Переменная $location особенно полезна в конфигурациях, где URL-перенаправления или правила доступа определяются совпавшим location. Как некешируемая переменная, $location отражает изменения в контексте обработки запроса в реальном времени. Это гарантирует её динамическое обновление по мере того, как NGINX обрабатывает запросы в рамках определённых контекстов location, что делает её необходимой в сценариях, где поведение должно меняться в зависимости от совпавшего URI.

Пример конфига

http {
    server {
        location = /auth {
            internal;
        }
        location / {
            add_header X-Matched-Location $location;
            proxy_pass http://backend;
        }
    }
}

Описание

Переменная $google является частью NGINX Module for Google, специально разработанного для облегчения развертывания зеркальных сайтов Google. Эта переменная динамически устанавливается во время обработки запросов, для которых в конфигурации NGINX задана директива `google`. При обработке запроса переменная заполняется соответствующей информацией, определяющей, обрабатывается ли запрос как зеркало Google, что позволяет NGINX соответственно корректировать своё поведение. Как правило, это значение — строка, указывающая состояние Google‑фильтра, и оно может варьироваться в зависимости от конкретной конфигурации и обрабатываемого запроса.\n\nКогда директива `google` включена в блоке location, как показано в приведённом ниже практическом примере, переменная $google может изменяться в зависимости от того, включены ли дополнительные настройки для таких функций, как Google Scholar, или параметры языка. Она особенно полезна в сочетании с условными конструкциями или для целей логирования — чтобы отлаживать или проверять, корректно ли зеркалируются запросы в соответствии с заданными правилами. Типичные значения включают состояния (например, включено) или специфические идентификаторы, относящиеся к работе зеркала, что обеспечивает упрощённую обработку ресурсов Google.

Пример конфига

location / {
    google on;
    error_log  /var/log/nginx/google_error.log;
    access_log /var/log/nginx/google_access.log google;
}

Описание

Переменная `$google_host` является частью NGINX Module for Google, специально разработанной для создания зеркал сервисов Google. Эта переменная динамически задаётся во время запроса, когда включена функциональность зеркалирования Google. По сути, она извлекает часть host входящего URL, направленного на Google, что позволяет серверам при необходимости изменять или логировать host. Как правило, её используют в тех местах, где необходимы манипуляции с ответом или логирование на основе хоста Google. Когда фильтр Google активирован, модуль подключается к жизненному циклу запроса, фиксируя детали запроса, включая информацию о host. Если запрос направлен к действительному сервису Google, эта переменная будет отражать имя хоста этого сервиса (например, `www.google.com`, `news.google.com` и т.д.). Переменная отмечена как changeable, то есть её можно изменять или обновлять во время обработки запроса, что позволяет вносить корректировки в реальном времени в зависимости от логики приложения или условий в различных контекстах запроса.

Пример конфига

location / {
    google on;
    add_header X-Google-Host $google_host;
}

Описание

Переменная $google_schema используется в модуле NGINX для создания Google Mirror, чтобы динамически предоставлять тип схемы, связанный с текущим контекстом запроса. Она заполняется, когда google filter включён через конкретную `location` директиву, что позволяет ей отражать и использовать параметры, настроенные в этой директиве, для представления структурированных данных, преимущественно для индексирования и сбора данных Google. Эта переменная вычисляет и получает тип схемы во время обработки запросов. Соответствующий тип схемы может быть задан в конфигурации NGINX и часто привязан к конкретному обслуживаемому контенту. Распространённые значения этой переменной могут включать 'WebSite', 'Article' или другие релевантные типы схем, распознаваемые schema.org, которые помогают информировать поисковые системы о предоставляемых данных, тем самым повышая SEO и видимость сайта. В зависимости от конфигурации эта переменная даёт гибкость в изменении типов схем в зависимости от типа контента, необходимого для текущего окружения запроса. При определении этого для использования следует тщательно учитывать JSON-LD скрипты, которые могут использовать эти типы схем, гарантируя, что выбранная схема соответствует обслуживаемому содержимому для максимизации видимости и распознавания содержимого сайта поисковыми системами. Поскольку на эту переменную влияют другие настройки NGINX, часто требуется скоординированная настройка, чтобы обеспечить возврат точных значений для соответствующих запросов.

Пример конфига

location / {
    google on;
    google_schema "WebSite";
}

Описание

Переменная $google_schema_reverse используется в модуле фильтра NGINX для Google, чтобы управлять направлением реализации схем Google при обработке запросов. Эта переменная устанавливается, когда определённые условия в конфигурации NGINX запускают её поведение, например, когда определённые URI запросов или параметры совпадают с заранее заданными шаблонами в логике модуля. Если она активирована, переменная влияет на то, как информация о схеме представляется в HTTP-ответе, в частности определяя, должна ли она отражать обратное отображение или интерпретацию стандартной схемы Google. Обычно значения $google_schema_reverse могут быть 'true' или 'false', что позволяет просто выполнять условную проверку в конфигурационных файлах. Это даёт более точный контроль над тем, как NGINX взаимодействует с запросами, предназначенными для сервисов Google, особенно когда требуется по-разному представлять или обрабатывать данные схемы в зависимости от требований приложения, например для совместимости или нужд обратного индексирования поисковыми системами. Эта возможность обеспечивает, что конечные пользователи смогут пользоваться зеркальным опытом Google с требуемым представлением схемы, соответствующим их конкретному сценарию использования.

Пример конфига

location / {  
    google on;  
    if ($google_schema_reverse) {  
        # Additional configuration for reverse schema processing  
        add_header X-Google-Schema 'Reversed';  
    }  
}

Описание

Переменная `$ssl_session_reused` является частью функциональности NGINX, которая оценивает SSL‑соединения. Конкретно она помогает определить, была ли при обработке входящих запросов повторно использована SSL‑сессия. Эта оптимизация может повысить производительность, избегая накладных расходов на установление новых сессий, что приводит к более быстрому времени отклика для HTTPS‑соединений. Значение переменной устанавливается в '1' или '0' на этапе обработки запроса: '1' означает, что сессия успешно повторно использована из предыдущего соединения, а '0' — что была создана новая SSL‑сессия. Эта переменная применима только тогда, когда SSL/TLS активированы в конфигурации сервера NGINX. Управление SSL‑сессиями обычно настраивается с помощью директив, таких как `ssl_session_cache` и `ssl_session_timeout`. При повторном использовании сессий процесс рукопожатия упрощается, что значительно снижает задержку и вычислительную нагрузку. Поэтому эта возможность особенно ценна на серверах, обрабатывающих значительный объём защищённого трафика, поскольку успешное повторное использование сессий может улучшить пропускную способность и опыт пользователя. Чтобы использовать эту переменную, убедитесь, что ваш сервер NGINX собран с поддержкой SSL. Также проверьте, что соответствующие настройки кеша SSL‑сессий настроены корректно для эффективной оптимизации повторного использования сессий. Мониторинг `$ssl_session_reused` может дать представление об эффективности SSL‑настройки, что важно для поддержания производительности в безопасной среде.

Пример конфига

http {
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 10m;
    server {
        listen 443 ssl;
        
        location / {
            add_header X-SSL-Session-Reused $ssl_session_reused;
        }
    }
}