Персональный
сайт
Игоря
Сысоева

18.08.2008

Модуль ngx_http_proxy_module позволяет передавать запросы другому серверу.

Содержание

proxy_buffer_size

proxy_buffering

proxy_buffers

proxy_connect_timeout

proxy_hide_header

proxy_ignore_client_abort

proxy_intercept_errors

proxy_next_upstream

proxy_pass

proxy_pass_header

proxy_redirect

proxy_read_timeout

proxy_redirect_errors

proxy_send_timeout

proxy_set_header

proxy_ssl_session_reuse

proxy_store

proxy_store_access

proxy_temp_path

location / {
    proxy_pass        http://localhost:8000/;
    proxy_set_header  X-Real-IP  $remote_addr;
}

Директива задаёт размер буфера, в который будет читаться первая часть ответа, получаемого от проксируемого сервера. В этой части ответа находится, как правило, небольшой заголовок ответа. По умолчанию размер буфера равен размеру одного буфера в директиве proxy_buffers, однако его можно сделать меньше.

Директива разрешает использовать буферизацию ответа проксируемого сервера. Если буферизация включена, то nginx принимает ответ проксируемого сервера как можно быстрее, сохраняя его в буфера, заданные директивами proxy_buffer_size и proxy_buffers. Если ответ не помещается полностью в память, то его часть записывается на диск.

Если буферизация выключена, то ответ синхронно передаётся клиенту сразу же по мере его поступления. nginx не пытается считать весь ответ проксируемого сервера, максимальный размер данных, который nginx может принять от сервера задаётся директивой proxy_buffer_size.

Директива задаёт число и размер буферов для одного соединения, в которые будет читаться ответ, получаемый от проксируемого сервера. По умолчанию размер одного буфера равен размеру страницы, в зависимости от платформы это или 4K, или 8K.

Директива задаёт таймаут для соединения с проксированным сервером. Необходимо иметь в виду, что этот таймаут не может быть больше 75 секунд.

nginx не передаёт клиенту строки заголовка "Date", "Server", "X-Pad" и "X-Accel-..." из ответа проксированного сервера. Директива proxy_hide_header задаёт дополнительные строки. Если же строки нужно наоброт разрешить, то нужно воспользоваться директивой proxy_pass_header.

Директива определяет, закрывать ли соединение с проксированным сервером в случае, если клиент закрыл соединение, не дождавшись ответа.

Директива определяет, передавать ли клиенту проксированные ответы с кодом больше или равные 400 или же перенаправлять их на обработку nginx'у с помощью директивы error_page.

Директива определяет, в каких случаях запрос будет передан следующему серверу:

• error — произшла ошибка соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;
• timeout — произошёл таймаут во время соединения с сервером, передачи ему запроса или чтения заголовка ответа сервера;
• invalid_header — сервер вернул пустой или неверный ответ;
• http_500 — сервер вернул ответ с кодом 500;
• http_503 — сервер вернул ответ с кодом 503;
• http_404 — сервер вернул ответ с кодом 404;
• off — запрещает передачу запроса следующему серверу;

Необходимо понимать, что передача запроса следующему серверу возможна только при условии, что клиенту ещё ничего не передавалось. То есть, если ошибка или таймаут возникли в середине передачи ответа, то исправить это уже невозможно.

Директива задаёт адрес проксируемоего сервера и URI, на который будет отображаться location. Адрес может быть указан в виде доменного имени или адреса и порта, например,

    proxy_pass   http://localhost:8000/uri/;

    proxy_pass   http://unix:/tmp/backend.socket:/uri/;

Если доменное имя резолвится в несколько адресов, то все они будут использоваться в режиме round-robin. И кроме того, адрес можно задать группой серверов.

При передаче запроса серверу часть URI, соответствующая location, заменяется на URI, указанный в директиве proxy_pass. Но из этого правила есть два исключения, в которых нельзя определить заменяемый location:

• если location задан регулярным выражением;
• если внутри проксируемого location с помощью директивы rewrite изменяется URI и именно с этой конфигурацией будет обрабатываться запрос (break):

  location  /name/ {
      rewrite      /name/([^/]+)  /users?name=$1  break;
      proxy_pass   http://127.0.0.1;
  }
  

  Для этих случаев URI передаётся без отображения.

Кроме того, можно указать, чтобы URI запроса передавалось в том же виде, как его прислал клиент, а не в в обработанном виде. Во время обработки

• два и более слэшей преобразуются в один слэш: "//" — "/";
• убираются ссылки на текущий каталог: "/./" — "/";
• убираются ссылки на предыдущий каталог: "/dir/../" — "/".

Если на сервер нужно передать URI в необработанном виде, то для этого в директиве proxy_pass нужно указать URL сервера без URI:

location  /some/path/ {
    proxy_pass   http://127.0.0.1;
}

Имя сервера, его порт и передваемый URI можно также полностью задать в помощью переменных:

    proxy_pass   http://$host$uri;

    proxy_pass   $request;

В этом случае имя сервера ищется среди описанных групп серверов и если не найдено, то определяется с помощью resolver'а.

Директива разрешает передавать от проксируемого сервера клиенту запрещённые для передачи строки.

Директива задаёт текст, который нужно изменить в строках заголовка "Location" и "Refresh" в ответе проксируемого сервера. Предположим, проксируемый сервер вернул строку "Location: http://localhost:8000/two/some/uri/". Директива

    proxy_redirect   http://localhost:8000/two/   http://frontend/one/;

В заменяемой строке можно не указывать имя сервера:

    proxy_redirect   http://localhost:8000/two/   /;

Изменение по умолчанию, задаваемое параметром "default", использует параметры директив location и proxy_pass. Поэтому две нижеприведённые конфигурации одинаковы:

location /one/ {
    proxy_pass       http://upstream:port/two/;
    proxy_redirect   default;

location /one/ {
    proxy_pass       http://upstream:port/two/;
    proxy_redirect   http://upstream:port/two/   /one/;

В заменяемой строке можно использовать переменные:

    proxy_redirect   http://localhost:8000/    http://$host:$server_port/;

Директив может быть несколько:

    proxy_redirect   default;
    proxy_redirect   http://localhost:8000/    /;
    proxy_redirect   http://www.example.com/   /;

Параметр "off" запрещает все директивы proxy_redirect на данном уровне:

    proxy_redirect   off;
    proxy_redirect   default;
    proxy_redirect   http://localhost:8000/    /;
    proxy_redirect   http://www.example.com/   /;

С помощью этой директивы можно также добавлять имя хоста к относительным редиректам, выдаваемым проксируемым сервером:

    proxy_redirect   /   /;

Директива задаёт таймаут при чтении ответа проксированного сервера. Таймаут устанавливается не на всю передачу ответа, а только между двумя операциями чтения. Если по истечении этого времени проксируемый сервер ничего не передаст, то nginx закрывает соединение.

Директива переименована в proxy_intercept_errors.

Директива задаёт таймаут при передаче запроса проксированному серверу. Таймаут устанавливается не на всю передачу запроса, а только между двумя операциями записи. Если по истечении этого времени проксируемый сервер не примет новых данных, то nginx закрывает соединение.

Директива позволяет переопределять или добавлять строки заголовка запроса, передаваемые проксируемому серверу. В качестве значения можно использовать текст, переменные и их комбинации. Директивы наследуются с предыдущего уровня при условии, что на данном уровне не описаны свои директивы proxy_set_header. По умолчанию переопределяются только две строки:

proxy_set_header  Host        $proxy_host;
proxy_set_header  Connection  close;

Неизменённую строку заголовка запроса "Host" можно передать так:

proxy_set_header  Host        $http_host;

Однако, если эта строка отсутствует в запросе клиента, то ничего передаваться не будет. В этом случае лучше воспользоваться переменной $host, её значение равно имени сервера в строке заголовка запроса "Host" или же основному имени сервера, если строки нет:

proxy_set_header  Host        $host;

Кроме того, можно передать имя сервера вместе с портом проксируемого сервера:

proxy_set_header  Host        $host:$proxy_port;

Если значение строки заголовка — пустая строка, то строка вообще не будет передаваться проксируемому серверу:

proxy_set_header  Accept-Encoding  "";

Директива определяет, использовать ли повторно SSL-сессии при работе с проксированным сервером. Если в логах появляются ошибки "SSL3_GET_FINISHED:digest check failed", то можно попробовать выключить повторное использование сессий.

Директива разрешает сохранение на диск файлов. Параметр "on" сохраняет файлы в соответствии с путями, указаными в директивах alias или root. Параметр "off" запрещает сохранение файлов. Кроме того, имя файла можно явно задать с помощью строки с переменными:

proxy_store   /data/www$original_uri;

Время модификации файлов выставляется согласно полученной строке "Last-Modified" в заголовке ответа. Для сохранения файлов необходимо, чтобы они находился на том же разделе, что и каталог с временными файлами, задаваемый директивой proxy_temp_path для данного location.

Директиву можно использовать для создания локальных копий статических неизменяемых файлов, например, так:

location /images/ {
    root                    /data/www;
    open_file_cache_errors  off;
    error_page              404 = /fetch$uri;
}

location /fetch/ {
    internal;

    proxy_pass              http://backend/;
    proxy_store             on;
    proxy_store_access      user:rw  group:rw  all:r;
    proxy_temp_path         /data/temp;

    alias                   /data/www/;
}

или так:

location /images/ {
    root                 /data/www;
    error_page           404 = @fetch;
}

location @fetch {
    internal;

    proxy_pass           http://backend;
    proxy_store          on;
    proxy_store_access   user:rw  group:rw  all:r;
    proxy_temp_path      /data/temp;

    root                 /data/www;
}

Директива задаёт права доступа для создаваемых файлов и каталогов, например,

proxy_store_access  user:rw  group:rw  all:r;

Если заданы какие-либо права для groups или all, то права для user указывать необязательно:

proxy_store_access  group:rw  all:r;

Директива задаёт имя каталога для хранения временных файлов полученных от другого сервера. В каталоге может использоваться иерархия подкаталогов до трёх уровней. Например, при такой конфигурации

proxy_temp_path  /spool/nginx/proxy_temp 1 2;

 
/spool/nginx/proxy_temp/7/45/00000123457

В модуле ngx_http_proxy_module есть встроенные переменные, которые можно использовать для формирования заголовков с помощью директивы proxy_set_header:

• $proxy_host, эта переменная равна имени проксируемого хоста и порта;
• $proxy_port, эта переменная равна порту проксируемого хоста;
• $proxy_add_x_forwarded_for, эта переменная равна строке заголовка запроса клиента "X-Forwarded-For" и добавленной к ней через запятую переменной $remote_addr. Если же строки "X-Forwarded-For" в запросе клиента нет, то переменная $proxy_add_x_forwarded_for равна переменной $remote_addr.

(C) Игорь Сысоев
http://sysoev.ru