RT
Все инструменты
На главную

Справочники

Директивы nginx

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

69 директив для этого контекста. Директива не в своём блоке — ошибка «is not allowed here» при nginx -t.

Показано 69 из 69 директив.

Процессы и соединения

Контекст main — верхний уровень nginx.conf, вне любых блоков.

  • user www-data;

    user — От чьего имени работают рабочие процессы.

    Синтаксис: user пользователь [группа]; · Контекст: main · По умолчанию: nobody nobody

  • worker_processes auto;

    worker_processes — Число рабочих процессов; auto — по числу ядер.

    Синтаксис: worker_processes число | auto; · Контекст: main · По умолчанию: 1

  • events { worker_connections 4096; }

    worker_connections — Сколько соединений держит один рабочий процесс, включая соединения к бэкендам.

    Синтаксис: worker_connections число; · Контекст: events · По умолчанию: 512

  • worker_rlimit_nofile 65535;

    worker_rlimit_nofile — Лимит открытых файлов на процесс; должен быть не меньше worker_connections.

    Синтаксис: worker_rlimit_nofile число; · Контекст: main · По умолчанию: —

  • multi_accept on;

    multi_accept — Принимать все новые соединения разом, а не по одному.

    Синтаксис: multi_accept on | off; · Контекст: events · По умолчанию: off

  • pid /run/nginx.pid;

    pid — Файл с PID главного процесса.

    Синтаксис: pid файл; · Контекст: main · По умолчанию: logs/nginx.pid

  • include /etc/nginx/conf.d/*.conf;

    include — Вставить содержимое других файлов конфига.

    Синтаксис: include файл | маска; · Контекст: любой · По умолчанию: —

  • error_log /var/log/nginx/error.log warn;

    error_log — Журнал ошибок; уровни от debug до emerg.

    Синтаксис: error_log файл [уровень]; · Контекст: main, http, server, location · По умолчанию: logs/error.log error

Серверы и адреса

  • listen 443 ssl; listen [::]:443 ssl;

    listen — На каком адресе и порту принимать запросы. default_server — сервер для запросов с незнакомым Host.

    Синтаксис: listen адрес[:порт] [default_server] [ssl] …; · Контекст: server · По умолчанию: *:80 | *:8000

  • server_name example.com www.example.com;

    server_name — Имена сервера: точные, с * в начале или конце, или регулярка с ~.

    Синтаксис: server_name имя …; · Контекст: server · По умолчанию: ""

  • root /var/www/site/public;

    root — Корень файлов: к нему дописывается весь путь запроса.

    Синтаксис: root путь; · Контекст: http, server, location, if · По умолчанию: html

  • location /static/ { alias /srv/assets/; }

    alias — Замена части пути: адрес location вырезается и заменяется на alias. В отличие от root.

    Синтаксис: alias путь; · Контекст: location · По умолчанию: —

  • index index.html index.php;

    index — Какой файл отдавать на запрос каталога.

    Синтаксис: index файл …; · Контекст: http, server, location · По умолчанию: index.html

  • location ~* \.(css|js|png)$ { expires 30d; }

    location — Блок настроек для части адресов. Порядок: точное =, затем самый длинный префикс, ^~ отключает регулярки, затем регулярки ~ и ~* по порядку в файле.

    Синтаксис: location [ = | ~ | ~* | ^~ ] адрес { … } · Контекст: server, location · По умолчанию: —

  • try_files $uri $uri/ /index.html;

    try_files — Проверить файлы по очереди и отдать первый существующий, иначе — последний аргумент.

    Синтаксис: try_files файл … uri | =код; · Контекст: server, location · По умолчанию: —

  • error_page 404 /404.html; error_page 500 502 503 504 /50x.html;

    error_page — Своя страница для кодов ошибок.

    Синтаксис: error_page код … [=[ответ]] uri; · Контекст: http, server, location, if · По умолчанию: —

  • location /protected/ { internal; }

    internal — Location доступен только для внутренних перенаправлений, снаружи — 404.

    Синтаксис: internal; · Контекст: location · По умолчанию: —

  • autoindex on;

    autoindex — Показывать список файлов каталога.

    Синтаксис: autoindex on | off; · Контекст: http, server, location · По умолчанию: off

  • default_type application/octet-stream;

    default_type — MIME-тип, если расширение не нашлось в types.

    Синтаксис: default_type тип; · Контекст: http, server, location · По умолчанию: text/plain

  • server_tokens off;

    server_tokens — Показывать ли версию nginx в заголовке Server и на страницах ошибок.

    Синтаксис: server_tokens on | off | build | строка; · Контекст: http, server, location · По умолчанию: on

Редиректы и переменные

if внутри location — известный источник сюрпризов: безопасно в нём только return и rewrite … last.

  • return 301 https://$host$request_uri;

    return — Сразу ответить кодом или редиректом. Проще и быстрее rewrite.

    Синтаксис: return код [текст | URL]; · Контекст: server, location, if · По умолчанию: —

  • rewrite ^/old/(.*)$ /new/$1 permanent;

    rewrite — Переписать адрес по регулярке. last — заново искать location, break — остаться в текущем.

    Синтаксис: rewrite регулярка замена [last | break | redirect | permanent]; · Контекст: server, location, if · По умолчанию: —

  • if ($request_method = POST) { return 405; }

    if — Условие по переменной: =, !=, ~, ~*, -f, -d, -e.

    Синтаксис: if (условие) { … } · Контекст: server, location · По умолчанию: —

  • set $backend "http://127.0.0.1:3000";

    set — Задать переменную.

    Синтаксис: set $переменная значение; · Контекст: server, location, if · По умолчанию: —

  • map $http_upgrade $connection_upgrade { default upgrade; "" close; }

    map — Вычислить переменную по таблице соответствий. Ленивое: считается только когда используется.

    Синтаксис: map строка $переменная { … } · Контекст: http · По умолчанию: —

Проксирование

Слеш в конце proxy_pass меняет смысл: proxy_pass http://app/ вырезает префикс location из адреса, без слеша — передаёт адрес как есть.

  • proxy_pass http://127.0.0.1:3000;

    proxy_pass — Передать запрос бэкенду или группе upstream.

    Синтаксис: proxy_pass URL; · Контекст: location, if · По умолчанию: —

  • proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme;

    proxy_set_header — Заголовки запроса к бэкенду. Наследуется, только если на текущем уровне нет ни одного своего.

    Синтаксис: proxy_set_header поле значение; · Контекст: http, server, location · По умолчанию: Host $proxy_host; Connection close;

  • proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade;

    proxy_http_version — Версия HTTP к бэкенду; 1.1 нужна для keepalive и WebSocket.

    Синтаксис: proxy_http_version 1.0 | 1.1; · Контекст: http, server, location · По умолчанию: 1.0

  • proxy_read_timeout 300s;

    proxy_read_timeout — Сколько ждать между двумя чтениями ответа бэкенда. Долгие отчёты и SSE упираются сюда.

    Синтаксис: proxy_read_timeout время; · Контекст: http, server, location · По умолчанию: 60s

  • proxy_connect_timeout 5s;

    proxy_connect_timeout — Сколько ждать установки соединения с бэкендом; обычно больше 75 с не бывает.

    Синтаксис: proxy_connect_timeout время; · Контекст: http, server, location · По умолчанию: 60s

  • proxy_buffering off;

    proxy_buffering — Буферизовать ответ бэкенда. Для потоков (SSE, долгие ответы) выключают.

    Синтаксис: proxy_buffering on | off; · Контекст: http, server, location · По умолчанию: on

  • proxy_redirect http://127.0.0.1:3000/ /;

    proxy_redirect — Переписать Location и Refresh в ответах бэкенда.

    Синтаксис: proxy_redirect default | off | было стало; · Контекст: http, server, location · По умолчанию: default

  • proxy_cache_path /var/cache/nginx keys_zone=api:10m max_size=1g inactive=60m;

    proxy_cache_path — Где хранить кэш и зона для ключей в памяти (1 МБ ≈ 8 тыс. ключей).

    Синтаксис: proxy_cache_path путь keys_zone=имя:размер …; · Контекст: http · По умолчанию: —

  • proxy_cache api; proxy_cache_valid 200 10m;

    proxy_cache — Включить кэш ответов в указанной зоне.

    Синтаксис: proxy_cache зона | off; · Контекст: http, server, location · По умолчанию: off

  • proxy_next_upstream error timeout http_502 http_503;

    proxy_next_upstream — В каких случаях пробовать следующий сервер группы.

    Синтаксис: proxy_next_upstream error | timeout | http_502 … | off; · Контекст: http, server, location · По умолчанию: error timeout

  • fastcgi_pass unix:/run/php/php8.3-fpm.sock; include fastcgi_params; fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

    fastcgi_pass — Передать запрос FastCGI-серверу, например PHP-FPM.

    Синтаксис: fastcgi_pass адрес; · Контекст: location, if · По умолчанию: —

Балансировка (upstream)

  • upstream app { server 127.0.0.1:3000; server 127.0.0.1:3001; }

    upstream — Группа серверов для proxy_pass; по умолчанию — по кругу с весами.

    Синтаксис: upstream имя { … } · Контекст: http · По умолчанию: —

  • server 10.0.0.5:8080 weight=3 max_fails=3 fail_timeout=30s;

    server — Сервер группы и его параметры.

    Синтаксис: server адрес [weight=n] [max_fails=n] [fail_timeout=время] [backup] [down]; · Контекст: upstream · По умолчанию: weight=1 max_fails=1 fail_timeout=10s

  • keepalive 32;

    keepalive — Держать открытыми соединения к бэкендам. Нужны proxy_http_version 1.1 и пустой Connection.

    Синтаксис: keepalive число; · Контекст: upstream · По умолчанию: —

  • least_conn;

    least_conn — Отправлять на сервер с наименьшим числом активных соединений.

    Синтаксис: least_conn; · Контекст: upstream · По умолчанию: —

  • ip_hash;

    ip_hash — Привязывать клиента к серверу по IP (липкие сессии).

    Синтаксис: ip_hash; · Контекст: upstream · По умолчанию: —

  • hash $request_uri consistent;

    hash — Выбирать сервер по хэшу ключа; consistent — согласованное хэширование.

    Синтаксис: hash ключ [consistent]; · Контекст: upstream · По умолчанию: —

Заголовки, кэш и сжатие

add_header, как и proxy_set_header, наследуется с верхнего уровня только когда на текущем нет ни одного своего. Один add_header в location молча отменяет все заголовки безопасности из server.

  • add_header Strict-Transport-Security "max-age=31536000" always;

    add_header — Добавить заголовок в ответ. Без always — только для кодов 200, 201, 204, 206, 301, 302, 303, 304, 307, 308.

    Синтаксис: add_header имя значение [always]; · Контекст: http, server, location, if · По умолчанию: —

  • expires 30d;

    expires — Выставить Expires и Cache-Control: max-age.

    Синтаксис: expires [modified] время | epoch | max | off; · Контекст: http, server, location, if · По умолчанию: off

  • gzip on;

    gzip — Сжимать ответы gzip.

    Синтаксис: gzip on | off; · Контекст: http, server, location, if · По умолчанию: off

  • gzip_types text/css application/javascript application/json image/svg+xml;

    gzip_types — Какие MIME-типы сжимать, помимо text/html (он сжимается всегда).

    Синтаксис: gzip_types тип …; · Контекст: http, server, location · По умолчанию: text/html

  • gzip_comp_level 5;

    gzip_comp_level — Степень сжатия; выше 5 почти не выигрывает, но тратит процессор.

    Синтаксис: gzip_comp_level 1…9; · Контекст: http, server, location · По умолчанию: 1

  • gzip_min_length 1024;

    gzip_min_length — Не сжимать ответы короче (по Content-Length).

    Синтаксис: gzip_min_length длина; · Контекст: http, server, location · По умолчанию: 20

  • gzip_vary on;

    gzip_vary — Добавлять Vary: Accept-Encoding, чтобы кэши не перепутали версии.

    Синтаксис: gzip_vary on | off; · Контекст: http, server, location · По умолчанию: off

  • sendfile on;

    sendfile — Отдавать файлы системным вызовом sendfile без копирования в память процесса.

    Синтаксис: sendfile on | off; · Контекст: http, server, location, if · По умолчанию: off

  • client_max_body_size 50m;

    client_max_body_size — Максимальный размер тела запроса; больше — 413. 0 — без ограничения.

    Синтаксис: client_max_body_size размер; · Контекст: http, server, location · По умолчанию: 1m

  • keepalive_timeout 65s;

    keepalive_timeout — Сколько держать открытым соединение с клиентом между запросами.

    Синтаксис: keepalive_timeout время [время_в_заголовке]; · Контекст: http, server, location · По умолчанию: 75s

HTTPS

  • ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;

    ssl_certificate — Сертификат вместе с промежуточными (fullchain).

    Синтаксис: ssl_certificate файл; · Контекст: http, server · По умолчанию: —

  • ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    ssl_certificate_key — Закрытый ключ сертификата.

    Синтаксис: ssl_certificate_key файл; · Контекст: http, server · По умолчанию: —

  • ssl_protocols TLSv1.2 TLSv1.3;

    ssl_protocols — Разрешённые версии TLS.

    Синтаксис: ssl_protocols [TLSv1] [TLSv1.1] [TLSv1.2] [TLSv1.3]; · Контекст: http, server · По умолчанию: TLSv1.2 TLSv1.3 (с 1.23.4)

  • ssl_ciphers HIGH:!aNULL:!MD5;

    ssl_ciphers — Набор шифров в формате OpenSSL (на TLS 1.3 не влияет).

    Синтаксис: ssl_ciphers шифры; · Контекст: http, server · По умолчанию: HIGH:!aNULL:!MD5

  • ssl_session_cache shared:SSL:10m;

    ssl_session_cache — Кэш TLS-сессий между процессами: повторное подключение без полного рукопожатия.

    Синтаксис: ssl_session_cache off | none | shared:имя:размер; · Контекст: http, server · По умолчанию: none

  • ssl_session_timeout 1d;

    ssl_session_timeout — Сколько живёт сессия в кэше.

    Синтаксис: ssl_session_timeout время; · Контекст: http, server · По умолчанию: 5m

  • http2 on;

    http2 — Включить HTTP/2 (директива с 1.25.1; раньше — параметр http2 у listen).

    Синтаксис: http2 on | off; · Контекст: http, server · По умолчанию: off

Доступ, лимиты и журналы

  • allow 10.0.0.0/8; deny all;

    allow / deny — Разрешить или запретить по IP. Правила проверяются по порядку до первого совпадения.

    Синтаксис: allow адрес | CIDR | all; · Контекст: http, server, location · По умолчанию: —

  • auth_basic "Закрытая зона"; auth_basic_user_file /etc/nginx/.htpasswd;

    auth_basic — Запросить логин и пароль (Basic).

    Синтаксис: auth_basic строка | off; · Контекст: http, server, location · По умолчанию: off

  • limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

    limit_req_zone — Зона ограничения частоты запросов.

    Синтаксис: limit_req_zone ключ zone=имя:размер rate=скорость; · Контекст: http · По умолчанию: —

  • limit_req zone=api burst=20 nodelay;

    limit_req — Применить ограничение частоты; burst — очередь сверх скорости.

    Синтаксис: limit_req zone=имя [burst=n] [nodelay]; · Контекст: http, server, location · По умолчанию: —

  • limit_req_status 429;

    limit_req_status — Код ответа тем, кто превысил лимит; обычно ставят 429.

    Синтаксис: limit_req_status код; · Контекст: http, server, location · По умолчанию: 503

  • limit_conn_zone $binary_remote_addr zone=perip:10m; limit_conn perip 20;

    limit_conn — Ограничить число одновременных соединений (зона — limit_conn_zone).

    Синтаксис: limit_conn зона число; · Контекст: http, server, location · По умолчанию: —

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

    access_log — Журнал запросов.

    Синтаксис: access_log путь [формат] | off; · Контекст: http, server, location, if · По умолчанию: logs/access.log combined

  • log_format timed '$remote_addr [$time_local] "$request" $status $request_time';

    log_format — Формат строки журнала.

    Синтаксис: log_format имя строка …; · Контекст: http · По умолчанию: combined

  • set_real_ip_from 10.0.0.0/8; real_ip_header X-Forwarded-For;

    set_real_ip_from — Каким прокси доверять при подмене адреса клиента (вместе с real_ip_header).

    Синтаксис: set_real_ip_from адрес | CIDR; · Контекст: http, server, location · По умолчанию: —

  • location = /nginx_status { stub_status; allow 127.0.0.1; deny all; }

    stub_status — Страница с числом соединений и запросов — для мониторинга.

    Синтаксис: stub_status; · Контекст: server, location · По умолчанию: —