Mercurial > hg > nginx-site
changeset 76:4a4caa566120
Russian documentation import.
Changes in module.dtd: <example> now allowed to contain <value> and
<emphasis> elements (we need this to show important parts in examples),
less strict checking of <directive> syntax (we don't want to fully
document some directives, notably deprecated ones).
Known issues:
1. <syntax> elements are preserved as is, they will require manual conversion
(likely to some not-yet-existed format a la DocBook cmdsynopsis, as
currently used one seems to be incomplete);
2. <value> no longer corresponds to replaceable content, and it's use in
examples isn't correct;
3. <link doc="document#fragment"> doesn't work with current xslt, either
should be supported or changed to <link doc="document" id="fragment">.
The following files are intentionally omitted: maillists.xml (support.xml
should be used instead), experimental.xml (obsolete), faq.xml (conflicts
with existing one, needs discussion).
Not yet linked to site.
line wrap: on
line diff
--- a/dtd/content.dtd Mon Oct 10 14:47:09 2011 +0000 +++ b/dtd/content.dtd Tue Oct 11 12:57:50 2011 +0000 @@ -3,45 +3,60 @@ <!ATTLIST section name CDATA #IMPLIED title CDATA #IMPLIED + id ID #IMPLIED > -<!ELEMENT para (#PCDATA | a | br | list | orderedlist | note | i | b | - nobr | table | url | code | dirname | path | header | - programlisting | initial | development_version | - stable_version )* > +<!ELEMENT para (#PCDATA | a | link | br | list | orderedlist | note | + i | b | nobr | table | url | code | command | + dirname | path | header | value | programlisting | + initial | development_version | stable_version )* > <!ELEMENT a (#PCDATA) > <!ATTLIST a href CDATA #REQUIRED > +<!ELEMENT link (#PCDATA) > +<!ATTLIST link + doc CDATA #IMPLIED + id CDATA #IMPLIED + url CDATA #IMPLIED +> + <!ELEMENT br EMPTY > <!ELEMENT i (#PCDATA) > <!ELEMENT b (#PCDATA) > +<!ELEMENT command (#PCDATA | value)* > <!ELEMENT dirname (#PCDATA | i)* > <!ELEMENT path (#PCDATA | development_version | stable_version)* > <!ELEMENT code (#PCDATA | i)* > <!ELEMENT header (#PCDATA) > <!ELEMENT initial (#PCDATA) > <!ELEMENT url (#PCDATA) > +<!ELEMENT value (#PCDATA) > <!ELEMENT programlisting (#PCDATA | i | b | dirname | path | development_version | stable_version)* > -<!ELEMENT nobr (#PCDATA | i | b | dirname | path)* > +<!ELEMENT nobr (#PCDATA | i | b | command | dirname | path)* > -<!ELEMENT list (item+) > +<!ELEMENT list (item+ | listitem+) > <!ELEMENT orderedlist (item+) > <!ELEMENT item (#PCDATA | para | a | br | nobr | list | i | b | url | - dirname | path)* > + dirname | path | command | value | programlisting)* > +<!ELEMENT listitem (#PCDATA | para | a | br | nobr | list | i | b | url | + dirname | path | command | value | programlisting)* > -<!ELEMENT note (#PCDATA | para | a | br | nobr | list | i | b | url | - dirname | path | programlisting | paypal)* > +<!ELEMENT note (#PCDATA | para | a | br | list | orderedlist | i | b | + nobr | table | url | code | command | dirname | path | + header | programlisting | initial | paypal | + development_version | stable_version )* > <!ELEMENT table (tr+) > <!ATTLIST table note CDATA #IMPLIED + width CDATA #IMPLIED > <!ELEMENT tr (td+) > <!ELEMENT td (#PCDATA | code | i)* >
--- a/dtd/module.dtd Mon Oct 10 14:47:09 2011 +0000 +++ b/dtd/module.dtd Tue Oct 11 12:57:50 2011 +0000 @@ -12,7 +12,7 @@ id ID #IMPLIED > -<!ELEMENT directive (syntax+, default, context+, para+) > +<!ELEMENT directive (syntax+, default?, context*, para+) > <!ATTLIST directive name ID #REQUIRED appeared-in CDATA #IMPLIED @@ -40,9 +40,9 @@ <!ELEMENT dq ANY > -<!ELEMENT emphasis (#PCDATA)* > +<!ELEMENT emphasis (#PCDATA | value)* > -<!ELEMENT example (#PCDATA)* > +<!ELEMENT example (#PCDATA | value | emphasis)* > <!ELEMENT header (#PCDATA | argument)* >
--- a/xml/ru/GNUmakefile Mon Oct 10 14:47:09 2011 +0000 +++ b/xml/ru/GNUmakefile Tue Oct 11 12:57:50 2011 +0000 @@ -1,5 +1,52 @@ DOCS_RU = ru/docs/faq \ + ru/docs/control \ + ru/docs/events \ + ru/docs/example \ + ru/docs/hash \ + ru/docs/install \ + ru/docs/ngx_core_module \ + ru/docs/switches \ + ru/docs/syntax \ + ru/docs/virtual_hosts \ + ru/docs/windows \ + ru/docs/http/ngx_http_access_module \ + ru/docs/http/ngx_http_addition_module \ + ru/docs/http/ngx_http_auth_basic_module \ + ru/docs/http/ngx_http_autoindex_module \ + ru/docs/http/ngx_http_browser_module \ + ru/docs/http/ngx_http_charset_module \ + ru/docs/http/ngx_http_core_module \ + ru/docs/http/ngx_http_dav_module \ + ru/docs/http/ngx_http_empty_gif_module \ + ru/docs/http/ngx_http_fastcgi_module \ + ru/docs/http/ngx_http_flv_module \ + ru/docs/http/ngx_http_geo_module \ + ru/docs/http/ngx_http_geoip_module \ + ru/docs/http/ngx_http_gzip_module \ + ru/docs/http/ngx_http_gzip_static_module \ + ru/docs/http/ngx_http_headers_module \ + ru/docs/http/ngx_http_image_filter_module \ + ru/docs/http/ngx_http_index_module \ + ru/docs/http/ngx_http_limit_req_module \ + ru/docs/http/ngx_http_limit_zone_module \ + ru/docs/http/ngx_http_log_module \ + ru/docs/http/ngx_http_map_module \ + ru/docs/http/ngx_http_memcached_module \ + ru/docs/http/ngx_http_perl_module \ + ru/docs/http/ngx_http_proxy_module \ + ru/docs/http/ngx_http_random_index_module \ + ru/docs/http/ngx_http_realip_module \ + ru/docs/http/ngx_http_referer_module \ + ru/docs/http/ngx_http_rewrite_module \ + ru/docs/http/ngx_http_secure_link_module \ + ru/docs/http/ngx_http_split_clients_module \ + ru/docs/http/ngx_http_ssi_module \ + ru/docs/http/ngx_http_ssl_module \ + ru/docs/http/ngx_http_sub_module \ + ru/docs/http/ngx_http_upstream \ + ru/docs/http/ngx_http_userid_module \ + ru/docs/http/ngx_http_xslt_module \ DOCS_RU_XML = $(foreach name, $(DOCS_RU), xml/$(name).xml) DOCS_RU_HTML = $(foreach name, $(DOCS_RU), $(OUT)/$(name).html)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/control.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,257 @@ +<!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> + +<article title="Управление nginx" + link="/ru/docs/control.html" + lang="ru"> + +<section> + +<para> +Управлять nginx можно с помощью сигналов. Номер главного процесса по умолчанию +записывается в файл <command>/usr/local/nginx/logs/nginx.pid</command>. +Изменить имя этого файла можно при конфигурации сборки или же в +<command>nginx.conf</command> директивой +<link doc="ngx_core_module.xml#pid">pid</link>. +Главный процесс поддерживает следующие сигналы: +<note> +<table> + +<tr><td width="20%">TERM, INT</td><td>быстрое завершение</td></tr> +<tr><td width="20%">QUIT</td><td>плавное завершение</td></tr> +<tr><td width="20%">HUP</td><td>изменение конфигурации, +обновление изменившейся временной зоны (только для FreeBSD и Linux), +запуск новых рабочих процессов с новой конфигурацией, +плавное завершение старых рабочих процессов</td></tr> +<tr><td width="20%">USR1</td><td>переоткрытие лог-файлов</td></tr> +<tr><td width="20%">USR2</td><td>обновление исполняемого файла</td></tr> +<tr><td width="20%">WINCH</td><td>плавное завершение рабочих процессов</td></tr> + +</table> +</note> +</para> + +<para> +Управлять рабочими процессами по отдельности не нужно. +Тем не менее, они тоже поддерживают некоторые сигналы: +<note> +<table> + +<tr><td width="20%">TERM, INT</td><td>быстрое завершение</td></tr> +<tr><td width="20%">QUIT</td><td>плавное завершение</td></tr> +<tr><td width="20%">USR1</td><td>переоткрытие лог-файлов</td></tr> + +</table> +</note> +</para> + +</section> + + +<section name="Изменение конфигурации" id="reconfiguration"> + +<para> +Для того, чтобы nginx перечитал файл конфигурации, нужно послать +главному процессу сигнал HUP. Главный процесс сначала проверяет +синтаксическую правильность конфигурации, а затем пытается применить +новую конфигурацию, то есть, открыть лог-файлы и новые listen сокеты. +Если ему это не удаётся, то он откатывает изменения и продолжает работать +со старой конфигурацией. +Если же удаётся, то он запускает новые рабочие процессы, а старым +шлёт сообщение о плавном выходе. Старые рабочие процессы закрывают listen +сокеты и продолжают обслуживать старых клиентов. После обслуживания всех +клиентов старые рабочие процессы завершаются. +</para> + +<para> +Предположим, на FreeBSD 4.x команда +<programlisting> +ps ax -o pid,ppid,user,%cpu,vsz,wchan,command | egrep '(nginx|PID)' +</programlisting> +показывает примерно такую картину: +<programlisting> + PID PPID USER %CPU VSZ WCHAN COMMAND +33126 1 root 0.0 1148 pause nginx: master process /usr/local/nginx/sb +33127 33126 nobody 0.0 1380 kqread nginx: worker process (nginx) +33128 33126 nobody 0.0 1364 kqread nginx: worker process (nginx) +33129 33126 nobody 0.0 1364 kqread nginx: worker process (nginx) +</programlisting> +</para> + +<para> +Если послать сигнал HUP главному процессу, то картина может быть такой: +<programlisting> + PID PPID USER %CPU VSZ WCHAN COMMAND +33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sb +33129 33126 nobody 0.0 1380 kqread nginx: worker process is shutting down (n +33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) +33135 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) +33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) +</programlisting> +</para> + +<para> +Один старый рабочий процесс 33129 всё ещё продолжает работать. По истечении +некоторого времени он завершается: +<programlisting> + PID PPID USER %CPU VSZ WCHAN COMMAND +33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sb +33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) +33135 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) +33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) +</programlisting> +</para> + +</section> + + +<section name="Ротация лог-файлов" id="logs"> + +<para> +Лог-файлы нужно переименовать, а затем послать сигнал USR1 главному процессу. +Он откроет заново все текущие открытые файлы и назначит им +в качестве владельца непривилегированного пользователя, под которым +работают рабочие процессы. После успешного открытия главный процесс +закрывает все открытые файлы и посылает сообщение о переоткрытии файлов +рабочим процессам. +Они также открывают новые файлы и сразу же закрывают старые. +В результате старые файлы практически сразу же готовы для дальнейшей +обработки, например, их можно сжимать. +</para> + +</section> + + +<section name="Обновление сервера на лету" id="upgrade"> + +<para> +Для обновления сервера нужно записать на место старого исполняемого файла новый. +Затем нужно послать сигнал USR2 главному процессу—он +переименует свой файл с номером процесса в файл +с суффиксом <command>.oldbin</command>, например, +<command>/usr/local/nginx/logs/nginx.pid.oldbin</command>, +после чего запустит новый исполняемый файл, а тот в свою +очередь—свои рабочие процессы: +<programlisting> + PID PPID USER %CPU VSZ WCHAN COMMAND +33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sb +33134 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) +33135 33126 nobody 0.0 1380 kqread nginx: worker process (nginx) +33136 33126 nobody 0.0 1368 kqread nginx: worker process (nginx) +36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sb +36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +</programlisting> +</para> + +<!-- + +<para> +Процесс с новым исполняемым файлом 36264 создаёт свой файл с номером процесса +с суффиксом <command>.newbin</command>, например, +<command>/usr/local/nginx/logs/nginx.pid.newbin</command>. +</para> + +--> + +<para> +Теперь все рабочие процессы наравне принимают запросы. +Если послать сигнал WINCH первому главному процессу, то он пошлёт своим +рабочим процессам сообщение о плавном выходе, и они будут постепенно выходить: +<programlisting> + PID PPID USER %CPU VSZ WCHAN COMMAND +33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sb +33135 33126 nobody 0.0 1380 kqread nginx: worker process is shutting down (n +36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sb +36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +</programlisting> +</para> + +<para> +<note> +При использовании метода rtsig новые процессы могут не принимать соединения +даже после того, как старому главному процессу послан сигнал WINCH. +В этом случае новому главному процессу нужно посылать сигнал USR1 до тех пор, +пока новые процессы не начнут принимать соединения. +</note> +</para> + +<para> +По истечении времени запросы будут обрабатывать только новые рабочие процессы: +<programlisting> + PID PPID USER %CPU VSZ WCHAN COMMAND +33126 1 root 0.0 1164 pause nginx: master process /usr/local/nginx/sb +36264 33126 root 0.0 1148 pause nginx: master process /usr/local/nginx/sb +36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +</programlisting> +</para> + +<para> +Нужно заметить, что старый процесс не закрывает свои listen сокеты и при +необходимости ему можно сказать, чтобы он снова запустил свои рабочие процессы. +Если работа нового исполняемого файла по каким-то причинам не устраивает, +то можно сделать следующее: +<list> + +<listitem> +<para> +Послать старому главному процессу сигнал HUP. Старый процесс, не перечитывая +конфигурации, запустит новые рабочие процессы. После этого можно +плавно завершить новые процессы, послав их главному процессу QUIT. +</para> +</listitem> + +<listitem> +<para> +Послать новому главному процессу сигнал TERM, он пошлёт сообщение о +немедленном выходе рабочим процессам и все они практически сразу же завершатся. +По выходу нового главного процесса старый запустит новые рабочие процессы. +</para> +</listitem> + +<listitem> +<para> +Если же новые процессы не завершаются, то нужно послать им сигнал KILL. +По выходу нового главного процесса старый запустит свои рабочие процессы. +</para> +</listitem> + +</list> + +</para> + +<para> +Если новый главный процесс выходит, то старый процесс убирает +суффикс <command>.oldbin</command> из имени файла с номером процесса. +</para> + +<para> +Если же обновление прошло удачно, то старому процессу нужно послать сигнал +QUIT, и у нас остаются только новые процессы: +<programlisting> + PID PPID USER %CPU VSZ WCHAN COMMAND +36264 1 root 0.0 1148 pause nginx: master process /usr/local/nginx/sb +36265 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +36266 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +36267 36264 nobody 0.0 1364 kqread nginx: worker process (nginx) +</programlisting> +</para> + +<!-- + +<para> +После этого остаётся только переименовать +<command>/usr/local/nginx/logs/nginx.pid.newbin</command> в +<command>/usr/local/nginx/logs/nginx.pid</command> и обновление можно считать +завершённым. +</para> + +--> + +</section> + +</article>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/events.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,93 @@ +<!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> + +<article title="Методы обработки соединений" + link="/ru/docs/events.html" + lang="ru"> + +<section> + +<para> +nginx поддерживает следующие методы обработки соединений, которые +можно задать директивой <dirname>use</dirname>: +<list> + +<listitem> +<para> +<command>select</command>—стандартный метод. +Модуль для поддержки этого метода собирается автоматически, +если на платформе не обнаружено более эффективного метода. +Можно принудительно разрешить или запретить сборку этого модуля +с помощью параметров <command>--with-select_module</command> или +<command>--without-select_module</command>. +</para> +</listitem> + +<listitem> +<para> +<command>poll</command>—стандартный метод. +Модуль для поддержки этого метода собирается автоматически, +если на платформе не обнаружено более эффективного метода. +Можно принудительно разрешить или запретить сборку этого модуля +с помощью параметров <command>--with-poll_module</command> или +<command>--without-poll_module</command>. +</para> +</listitem> + +<listitem> +<para> +<command>kqueue</command>—эффективный метод, используемый +во FreeBSD 4.1+, OpenBSD 2.9+, NetBSD 2.0 и MacOS X. +На двух-процессорных машинах под управлением MacOS X использование +kqueue может привести к kernel panic. +</para> +</listitem> + +<listitem> +<para> +<command>epoll</command>—эффективный метод, используемый +в Linux 2.6+. В некоторых дистрибутивах, например <nobr>SuSE 8.2,</nobr> +есть патчи для поддержки epoll ядром 2.4. +</para> +</listitem> + +<listitem> +<para> +<command>rtsig</command>—real time signals, эффективный метод, +используемый в Linux 2.2.19+. +По умолчанию в очереди может находиться не более 1024 сигналов для всей +системы. Этого недостаточно для нагруженных серверов, поэтому нужно увеличить +размер очереди с помощью параметра ядра +<command>/proc/sys/kernel/rtsig-max</command>. +Однако, начиная с Linux 2.6.6-mm2, этого параметра уже нет и для каждого +процесса существует отдельная очередь сигналов, размер которой +задаётся с помощью RLIMIT_SIGPENDING. +</para> + +<para> +При переполнении очереди nginx сбрасывает её и начинает обрабатывать +соединения с помощью метода poll до тех пор, пока ситуация не нормализуется. +</para> +</listitem> + +<listitem> +<para> +<command>/dev/poll</command>—эффективный метод, используемый +в Solaris 7 11/99+, HP/UX 11.22+ (eventport), IRIX 6.5.15+ +и Tru64 UNIX 5.1A+. +</para> +</listitem> + +<listitem> +<para> +<command>eventport</command>—event ports, эффективный метод, +используемый в Solaris 10. Во избежания kernel panic, нужно установить <link +url="http://sunsolve.sun.com/search/document.do?assetkey=1-26-102485-1">патч</link>. +</para> +</listitem> + +</list> +</para> + +</section> + +</article>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/example.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,159 @@ +<!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> + +<article title="Пример конфигурации nginx" + link="/ru/docs/example.html" + lang="ru"> + +<section> + +<para> +Пример конфигурации сайта, который передаёт все запросы бэкенду, кроме +картинок и запросов, начинающихся с "/download/". +<!-- +Директивы, выделенные цветом, скорее всего, будут меняться в будущих версиях. +--> +<programlisting> +user www www; + +worker_processes 2; + +pid /var/run/nginx.pid; + +# [ debug | info | notice | warn | error | crit ] + +error_log /var/log/nginx.error_log info; + +events { + connections 2000; + + # use [ kqueue | rtsig | epoll | /dev/poll | select | poll ]; + use kqueue; +} + +http { + + include conf/mime.types; + default_type application/octet-stream; + + + log_format main '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $bytes_sent ' + '"$http_referer" "$http_user_agent" ' + '"$gzip_ratio"'; + + log_format download '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $bytes_sent ' + '"$http_referer" "$http_user_agent" ' + '"$http_range" "$sent_http_content_range"'; + + client_header_timeout 3m; + client_body_timeout 3m; + send_timeout 3m; +<!-- + connection_pool_size 256; +--> + client_header_buffer_size 1k; + large_client_header_buffers 4 4k; +<!-- + request_pool_size 4k; +--> + gzip on; + gzip_min_length 1100; + gzip_buffers 4 8k; + gzip_types text/plain; + + output_buffers 1 32k; + postpone_output 1460; + + sendfile on; + tcp_nopush on; + tcp_nodelay on; + send_lowat 12000; + + keepalive_timeout 75 20; + + #lingering_time 30; + #lingering_timeout 10; + #reset_timedout_connection on; + + + server { + listen one.example.com; + server_name one.example.com www.one.example.com; + + access_log /var/log/nginx.access_log main; + + location / { + proxy_pass http://127.0.0.1/; + proxy_redirect off; + + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + #proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + + client_max_body_size 10m; + client_body_buffer_size 128k; + + client_body_temp_path /var/nginx/client_body_temp; + + proxy_connect_timeout 70; + proxy_send_timeout 90; + proxy_read_timeout 90; + proxy_send_lowat 12000; + + proxy_buffer_size 4k; + proxy_buffers 4 32k; + proxy_busy_buffers_size 64k; + proxy_temp_file_write_size 64k; + + proxy_temp_path /var/nginx/proxy_temp; + + charset koi8-r; + } + + error_page 404 /404.html; + + location /404.html { + root /spool/www; + + charset on; + source_charset koi8-r; + } + + location /old_stuff/ { + rewrite ^/old_stuff/(.*)$ /new_stuff/$1 permanent; + } + + location /download/ { + + valid_referers none blocked server_names *.example.com; + + if ($invalid_referer) { + #rewrite ^/ http://www.example.com/; + return 403; + } + + #rewrite_log on; + + # rewrite /download/*/mp3/*.any_ext to /download/*/mp3/*.mp3 + rewrite ^/(download/.*)/mp3/(.*)\..*$ + /$1/mp3/$2.mp3 break; + + root /spool/www; + #autoindex on; + access_log /var/log/nginx-download.access_log download; + } + + location ~* \.(jpg|jpeg|gif)$ { + root /spool/www; + access_log off; + expires 30d; + } + } +} +</programlisting> +</para> + +</section> + +</article>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/hash.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,41 @@ +<!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> + +<article title="Настройка хэшей" + link="/ru/docs/hash.html" + lang="ru"> + +<section> + +<para> +Для быстрой обработки статических наборов данных, таких как имена серверов, +значения директивы map, mime-types, имена строк заголовков запроса, +nginx использует хэш-таблицы. +Во время старта и при каждой переконфигурации nginx подбирает минимально +возможный размер хэш-таблиц с учётом того, чтобы размер корзины, +куда попадают ключи с совпадающими хэш-значениями, +не превышал заданного параметра (hash bucket size). +Размер таблицы считается в корзинах. +Подбор ведётся до тех пор, пока размер таблицы не превысит параметр +hash max size. +Для большинства хэшей есть директивы, которые позволяют менять эти параметры, +например, для хэшей имён серверов директивы называются +<link doc="http/ngx_http_core_module.xml#server_names_hash_max_size">server_names_hash_max_size</link> +и <link doc="http/ngx_http_core_module.xml#server_names_hash_bucket_size">server_names_hash_bucket_size</link>. +</para> + +<para> +Параметр hash bucket size всегда выравнивается до размера, кратного +размеру строки кэша процессора. Это позволяет ускорить поиск ключа +в хэше на современных процессорах, уменьшив число обращений к памяти. +Если hash bucket size равен размеру одной строки кэша процессора, +то во время поиска ключа число обращений к памяти в худшем случае +будет равно двум—первый раз для определения адреса корзины, +а второй—при поиске ключа внутри корзины. +Соответственно, если nginx выдал сообщение о необходимости увеличить +hash max size или hash bucket size, то сначала нужно увеличивать первый +параметр. +</para> + +</section> + +</article>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_access_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,71 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_access_module" + link="/ru/docs/http/ngx_http_access_module.html" + lang="ru"> + + +<section name="" id="summary"> + +<para> +Модуль ngx_http_access_module позволяет закрыть доступ для определённых +IP-адресов клиентов. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + location / { + deny 192.168.1.1; + allow 192.168.1.0/24; + allow 10.1.1.0/16; + deny all; + } +</example> +</para> + +<para> +Правила проверяются в порядке их записи до первого соответствия. +В данном примере доступ разрешён только для сетей 10.1.1.0/16 +и 192.168.1.0/24, кроме адреса 192.168.1.1. +Если правил много, то лучше воспользоваться переменными модуля +<link doc="ngx_http_geo_module.xml">ngx_http_geo_module</link>. +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="allow"> +<syntax>allow <value>[адрес|CIDR|all]</value></syntax> +<default>нет</default> +<context>http, server, location, limit_except</context> + +<para> +Директива разрешает доступ для указанной сети или адреса. +</para> + +</directive> + + +<directive name="deny"> +<syntax>deny <value>[адрес|CIDR|all]</value></syntax> +<default>нет</default> +<context>http, server, location, limit_except</context> + +<para> +Директива запрещает доступ для указанной сети или адреса. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_addition_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,77 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_addition_module" + link="/ru/docs/http/ngx_http_addition_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_addition_module — это фильтр, +добавляющий текст до и после ответа. +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром <command>--with-http_addition_module</command>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + location / { + add_before_body /before_action; + add_after_body /after_action; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="add_before_body"> +<syntax>add_before_body <value>uri</value></syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива добавляет перед телом ответа текст, выдаваемый в результате +работы заданного подзапроса. +</para> + +</directive> + + +<directive name="add_after_body"> +<syntax>add_after_body <value>uri</value></syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива добавляет после тела ответа текст, выдаваемый в результате +работы заданного подзапроса. +</para> + +</directive> + + +<directive name="addition_types"> +<syntax>addition_types <value>mime-тип [mime-тип ...]</value></syntax> +<default>addition_types text/html</default> +<context>http, server, location</context> + +<para> +Директива (0.7.9) разрешает добавлять текст в ответах +с указанными MIME-типами в дополнение к "text/html". +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_auth_basic_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,77 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_auth_basic_module" + link="/ru/docs/http/ngx_http_auth_basic_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_auth_basic_module позволяет закрыть доступ с проверкой +имени и пароля по протоколу HTTP Basic Authentication. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + location / { + auth_basic "closed site"; + auth_basic_user_file conf/htpasswd; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="auth_basic"> +<syntax>auth_basic <value>[строка|off]</value></syntax> +<default>auth_basic off</default> +<context>http, server, location, limit_except</context> + +<para> +Директива включает проверку имени и пароля по протоколу +HTTP Basic Authentication. +Заданный параметр используется в качестве realm. +Параметр "off" позволяет отменить действие унаследованной с нижележащего +уровня директивы. +</para> + +</directive> + + +<directive name="auth_basic_user_file"> +<syntax>auth_basic_user_file <value>файл</value></syntax> +<default>нет</default> +<context>http, server, location, limit_except</context> + +<para> +Директива задаёт файл, в котором хранятся имена и пароли +пользователей. Формат файла следующий: +<example> +# комментарий +имя1:пароль1 +имя2:пароль2:комментарий +имя3:пароль3 +</example> +</para> + +<para> +Пароли должны быть зашифрованы функцией crypt(3). +Для создания файла с паролями можно воспользоваться программой +<command>htpasswd</command> из дистрибутива Apache. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_autoindex_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,76 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_autoindex_module" + link="/ru/docs/http/ngx_http_autoindex_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_autoindex_module выдаёт листинг каталога. +Обычно запрос попадает к модулю ngx_http_autoindex_module, +когда модуль <link doc="ngx_http_index_module.xml">ngx_http_index_module</link> не нашёл индексный файл. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + location / { + autoindex on; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="autoindex"> +<syntax>autoindex <value>[on|off]</value></syntax> +<default>autoindex off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает вывод листинга каталога. +</para> + +</directive> + + +<directive name="autoindex_exact_size"> +<syntax>autoindex_exact_size <value>[on|off]</value></syntax> +<default>autoindex_exact_size on</default> +<context>http, server, location</context> + +<para> +Директива определяет, как выводить размеры файлов в листинге +каталога — точно, или округляя до килобайт, мегабайт и гигабайт. +</para> + + + +</directive> + + +<directive name="autoindex_localtime"> +<syntax>autoindex_localtime <value>[on|off]</value></syntax> +<default>autoindex_localtime off</default> +<context>http, server, location</context> + +<para> +Директива определяет, в какой временной зоне выводить время в листинге +каталога — в локальной или в GMT. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_browser_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,144 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_browser_module" + link="/ru/docs/http/ngx_http_browser_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_browser_module создаёт переменные, значение которых +зависят от строки "User-Agent" в заголовке запроса: +<list type="bullet"> + +<listitem> +$modern_browser — равна значению, заданному директивой +<link id="modern_browser_value"/>, если браузер опознан как современный; +</listitem> + +<listitem> +$ancient_browser — равна значению, заданному директивой +<link id="ancient_browser_value"/>, если браузер опознан как устаревший; +</listitem> + +<listitem> +$msie — равна "1", если браузер опознан как MSIE любой версии; +</listitem> + +</list> +</para> + +</section> + + +<section name="Примеры конфигурации" id="example"> + +<para> +Выбор индексного файла: +<example> + modern_browser_value "modern."; + + modern_browser msie 5.5; + modern_browser gecko 1.0.0; + modern_browser opera 9.0; + modern_browser safari 413; + modern_browser konqueror 3.0; + + index index.${modern_browser}html index.html; +</example> +</para> + +<para> +Редирект для старых браузеров: +<example> + modern_browser msie 5.0; + modern_browser gecko 0.9.1; + modern_browser opera 8.0; + modern_browser safari 413; + modern_browser konqueror 3.0; + + modern_browser unlisted; + + ancient_browser Links Lynx netscape4; + + if ($ancient_browser) { + rewrite ^ /ancient.html; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="ancient_browser"> +<syntax>ancient_browser <value>строка [строка ...]</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт подстроки, при нахождении которых в строке "User-Agent", +браузер считается устаревшим. +Специальная строка "netscape4" соответствует регулярному +выражению "^Mozilla/[1-4]". +</para> + +</directive> + + +<directive name="ancient_browser_value"> +<syntax>ancient_browser_value <value>строка</value></syntax> +<default>ancient_browser_value 1</default> +<context>http, server, location</context> + +<para> +Директива задаёт значение для переменных $ancient_browser. +</para> + +</directive> + + +<directive name="modern_browser"> +<syntax>modern_browser <value>браузер версия|unlisted</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт версию браузера, начиная с которой он считается современным. +В качестве браузера можно задать msie, gecko (браузеры, созданные +на основе Mozilla) opera, safari, konqueror. +</para> + +<para> +Версии можно задать в формате X, X.X, X.X.X, или X.X.X.X. +Максимальные значения для каждого их форматов соответственно — 4000, +4000.99, 4000.99.99, и 4000.99.99.99. +</para> + +<para> +Специальное значение "unlisted" указывает считать современным браузер, +не описанный директивами modern_browser и <link id="ancient_browser"/>. +В противном случае неперечисленный браузер будет считаться устаревшим. +Если в запросе нет строки "User-Agent", то браузер считается неперечисленным. +</para> + +</directive> + + +<directive name="modern_browser_value"> +<syntax>modern_browser_value <value>строка</value></syntax> +<default>modern_browser_value 1</default> +<context>http, server, location</context> + +<para> +Директива задаёт значение для переменных $modern_browser. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_charset_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,204 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_charset_module" + link="/ru/docs/http/ngx_http_charset_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_charset_module добавляет указанную кодировку +в строку "Content-Type" в заголовок ответа. +Кроме того, модуль может перекодировать данные из одной кодировки в другую +с некоторыми ограничениями: +<list type="bullet"> + +<listitem> +перекодирование осуществляется только в одну сторону — от сервера к клиенту, +</listitem> + +<listitem> +перекодироваться могут только однобайтные кодировки +</listitem> + +<listitem> +или однобайтные кодировки в UTF-8 и обратно. +</listitem> + +</list> +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + include conf/koi-win; + + charset windows-1251; + source_charset koi8-r; +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="charset"> +<syntax>charset <value>кодировка|off</value></syntax> +<default>charset off</default> +<context>http, server, location, if в location</context> + +<para> +Директива charset добавляет в строку "Content-Type" +в заголовке ответа указанную кодировку. +Если эта кодировка отличается от указанной в директиве +<link id="source_charset"/>, то выполняется перекодирование. +</para> + +<para> +Параметр "off" отменяет добавление кодировки в строку "Content-Type" +в заголовке ответа. +</para> + +<para> +Кодировка может быть задана переменной: +<example> +charset $charset; +</example> +</para> + +<para> +В этом случае необходимо, чтобы все возможные значения переменной +присутствовали хотя бы один раз в любом месте конфигурации в виде +директив charset_map, charset, или source_charset. +Для кодировок utf-8, windows-1251 и koi8-r для этого достаточно +включить в конфигурацию файлы conf/koi-win, conf/koi-utf и conf/win-utf. +Для других кодировок можно просто сделать фиктивную таблцу перекодировки, +например: +<example> +charset_map iso-8859-5 _ { } +</example> +</para> + +</directive> + + +<directive name="charset_map"> +<syntax>charset_map <value>кодировка1 кодировка2 { ... }</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива charset_map описывает таблицу перекодирования из одной +кодировки в другую. +Таблица для обратного перекодирования строится на основании тех же данных. +Коды символов задаются в шестнадцатеричном виде. +Неописанные символы в переделах 80-FF заменяются на "?". +При перекодировании из UTF-8 символы, отсутствующие в однобайтной кодировке, +заменяются на "&#XXXX;". +</para> + +<para> +Пример использования: +<example> +charset_map koi8-r windows-1251 { + C0 FE ; # small yu + C1 E0 ; # small a + C2 E1 ; # small b + C3 F6 ; # small ts + ... +} +</example> +</para> + +<para> +При описании таблицы перекодирования в UTF-8, значения этой кодировки должны +описываться во второй колонке, например: +<example> +charset_map koi8-r utf-8 { + C0 D18E ; # small yu + C1 D0B0 ; # small a + C2 D0B1 ; # small b + C3 D186 ; # small ts + ... +} +</example> +</para> + +<para> +Полные таблицы преобразования из koi8-r в windows-1251 +и из koi8-r и windows-1251 в utf-8 +входят в дистрибутив и находятся в файлах conf/koi-win, conf/koi-utf +и conf/win-utf. +</para> + +</directive> + + +<directive name="charset_types"> +<syntax>charset_types <value>mime-тип [mime-тип ...]</value></syntax> +<default>charset_types text/html text/xml text/plain text/vnd.wap.wml +application/x-javascript application/rss+xml. +</default> +<context>http, server, location</context> + +<para> +Директива (0.7.9) разрешает работу модуля в ответах с указанными MIME-типами +в дополнение к "text/html". По умолчанию используются +<list type="bullet"> +<listitem>text/html</listitem> +<listitem>text/xml</listitem> +<listitem>text/plain</listitem> +<listitem>text/vnd.wap.wml</listitem> +<listitem>application/x-javascript</listitem> +<listitem>application/rss+xml</listitem> +</list> +</para> + +</directive> + + +<directive name="override_charset"> +<syntax>override_charset <value>on|off</value></syntax> +<default>override_charset off</default> +<context>http, server, location, if в location</context> + +<para> +Директива определяет, выполнять ли перекодирование для ответов, +полученных от проксированного сервера или от FastCGI-сервера, +если в них уже есть charset в строке "Content-Type" в заголовке ответа. +Если перекодирование разрешено, то в качестве исходной кодировки +используется кодировка, указанная в полученном ответе. +</para> + +<para> +Необходимо отметить, что если ответ был получен в подзапросе, +то, независимо от директивы override_charset, всегда выполняется +перекодирование из кодировки ответа в кодировку основного запроса. +</para> + +</directive> + + +<directive name="source_charset"> +<syntax>source_charset <value>кодировка</value></syntax> +<default>нет</default> +<context>http, server, location, if в location</context> + +<para> +Директива source_charset задают исходную кодировку ответа. +Если эта кодировка отличается от указанной в директиве +<link id="charset"/>, то выполняется перекодирование. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_core_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,1819 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_core_module" + link="/ru/docs/http/ngx_http_core_module.html" + lang="ru"> + +<section name="Директивы" id="directives"> + +<directive name="aio"> +<syntax>aio <value>[on|off|sendfile]</value></syntax> +<default>aio off</default> +<context>http, server, location</context> + +<para> +Директива (0.8.11) разрешает или запрещает использовать файловый AIO +во FreeBSD и Linux. +</para> + +<para> +Во FreeBSD AIO можно использовать, начиная с FreeBSD 4.3 версии. +AIO можно собрать в ядре статически +<example> +options VFS_AIO +</example> +или же подгрузить динамически +<example> +kldload aio +</example> +</para> + +<para> +Во FreeBSD 5 и 6 при включении AIO статически или динамически на стадии +загрузки ядра вся сетевая подсистема будет использовать GiantLock, +что может негативно сказаться на производительности системы в целом. +Эта зависимость устранена во FreeBSD-6.4 STABLE от 2009 года и во FreeBSD 7. +Однако, начиная с FreeBSD 5.3, есть возможность включать AIO, +не связывая сетевую подсистему GiantLock'ом — для этого модуль AIO +нужно подгружать уже после загрузки ядра. +В этом случае в /var/log/messages появится сообщение +<example> +WARNING: Network stack Giant-free, but aio requires Giant. +Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0 +</example> +которое можно смело проигнорировать. +<note> +Требование использовать GiantLock в AIO связано с тем, что FreeBSD +поддерживает асинхронные вызовы aio_read()/aio_write() для работы с сокетами. +Но поскольку nginx использует AIO только для работы с диском, то проблем +не возникает. +</note> +</para> + +<para> +Для работы AIO нужно выключить sendfile: +<example> +location /video/ { + sendfile off; + aio on; + output_buffers 1 64k; +} +</example> +</para> + +<para> +Кроме того, начиная с FreeBSD 5.2.1 и nginx-0.8.12, AIO также можно +использовать для подгрузки данных для sendfile(): +<example> +location /video/ { + sendfile on; + tcp_nopush on; + aio sendfile; +} +</example> +В такой конфигурации используется флаг SF_NODISKIO и sendfile() +не блокируется на диске, а сообщает об отсутствии данных в памяти, +после чего nginx инициирует асинхронную подгрузку данных, +читая только один байт. При этом ядро FreeBSD подгружает в память +первые 128K файла, однако при последующих чтениях файл подгружается +частями только по 16K. Изменить это можно с помощью директивы +<link id="read_ahead">read_ahead</link>. +</para> + +<para> +В Linux AIO можно использовать, только начиная с версии ядра 2.6.22, +и, кроме того, ещё необходимо дополнительно включать +<link id="directio">directio</link>, иначе чтение будет блокирующимся: +<example> +location /video/ { + aio on; + directio 512; + output_buffers 1 128k; +} +</example> +</para> + +<para> +Поскольку directio в Linux можно использовать только для чтения блоков, +выравненных по 512 байт (или 4К для XFS), то невыравненный конец файла +будет читаться блокировано. То же относится к запросам части ответа +byte-ranges и к запросам FLV не с начала файла: чтение невыровненных начала +и конца ответа будет блокирующимся. sendfile выключать не нужно, так +как при использовании directio он выключается сам. +</para> + +</directive> + + +<directive name="alias"> +<syntax>alias <value>путь</value></syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива задаёт замену для указанного location'а. +Например, при такой конфигурации +<example> +location /i/ { + alias /data/w3/images/; +} +</example> +на запрос "/i/top.gif" будет отдан файл "/data/w3/images/top.gif". +</para> + +<para> +В значении пути можно использовать переменные. +</para> + +<para> +Если директива alias используется внутри location'а, заданного +регулярным выражением, то регулярное выражение должно содержать выделения, +а директива alias — ссылки на эти выделения (0.7.40), например: +<example> +location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ { + alias /data/w3/images/$1; +} +</example> +</para> + +<para> +Если location и последняя часть значения директивы совпадают: +<example> +location /images/ { + alias /data/w3/images/; +} +</example> +то лучше воспользоваться директивой <link id="root"/>: +<example> +location /images/ { + root /data/w3; +} +</example> +</para> + +</directive> + + +<directive name="client_body_in_file_only"> +<syntax>client_body_in_file_only <value>on|clean|off</value></syntax> +<default>client_body_in_file_only off</default> +<context>http, server, location</context> + +<para> +Директива определяет, сохранять ли всё тело запроса клиента в файл. +Директиву можно использовать для отладки и при использовании +переменной $request_body_file или метода <link doc="ngx_http_perl_module.xml#methods">$r->request_body_file</link> +модуля ngx_http_perl_module. +</para> + +<para> +При использовании параметра "on" временные файлы по окончании +обработки запроса не удаляется. +</para> + +<para> +Параметр "clean" разрешает удалять временные файлы, оставшиеся по окончании +обработки запроса. +</para> + +</directive> + + +<directive name="client_body_in_single_buffer"> +<syntax>client_body_in_single_buffer <value>on|off</value></syntax> +<default>client_body_in_single_buffer off</default> +<context>http, server, location</context> + +<para> +Директива определяет, хранить ли всё тело запроса клиента в одном буфере. +Директива рекомендуется при использовании переменной $request_body +для уменьшения операций копирования. +</para> + +</directive> + + +<directive name="client_body_buffer_size"> +<syntax>client_body_buffer_size <value>размер</value></syntax> +<default>client_body_buffer_size 8k/16k</default> +<context>http, server, location</context> + +<para> +Директива задаёт размер буфера для чтения тела запроса клиента. +Если тело запроса больше заданного буфера, то всё тело запроса или только +его часть записывается во временный файл. +По умолчанию размер одного буфера равен двум размерам страницы, в зависимости +от платформы это или 8K, или 16K. +</para> + +</directive> + + +<directive name="client_body_temp_path"> +<syntax>client_body_temp_path <value>путь [ уровень1 [ уровень2 [ уровень3 ] ] ] +</value></syntax> +<default>client_body_temp_path client_body_temp</default> +<context>http, server, location</context> + +<para> +Директива задаёт имя каталога для хранения временных файлов с телом запроса +клиента. +В каталоге может использоваться иерархия подкаталогов до трёх уровней. +Например, при такой конфигурации +<example> +client_body_temp_path /spool/nginx/client_temp 1 2; +</example> +имя временного будет такого вида: +<example> +/spool/nginx/client_temp/7/45/00000123457 +</example> +</para> + +</directive> + + +<directive name="client_body_timeout"> +<syntax>client_body_timeout <value>время</value></syntax> +<default>client_body_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут при чтении тела запроса клиента. +Таймаут устанавливается не на всю передачу тела запроса, +а только между двумя операциями чтения. +Если по истечении этого времени клиент ничего не передаст, +то ему возвращается ошибка "Request time out" (408). +</para> + +</directive> + + +<directive name="client_header_buffer_size"> +<syntax>client_header_buffer_size <value>размер</value></syntax> +<default>client_header_buffer_size 1k</default> +<context>http, server</context> + +<para> +Директива задаёт размер буфера для чтения заголовка запроса клиента. +Для подавляющего большинства запросов вполне достаточно буфера размером в 1K. +Однако если в запросе есть большие cookies или же запрос пришёл +от wap-клиента, то он может не поместиться в 1K. +Поэтому, если строка запроса или строка заголовка запроса не помещается +полностью в этот буфер, то выделяются большие буферы, задаваемые директивой +<link id="large_client_header_buffers"/>. +</para> + +</directive> + + +<directive name="client_header_timeout"> +<syntax>client_header_timeout <value>время</value></syntax> +<default>client_header_timeout 60</default> +<context>http, server</context> + +<para> +Директива задаёт таймаут при чтении заголовка запроса клиента. +Если по истечении этого времени клиент не передаст полностью заголовок +запроса, то ему возвращается ошибка "Request time out" (408). +</para> + +</directive> + + +<directive name="client_max_body_size"> +<syntax>client_max_body_size <value>размер</value></syntax> +<default>client_max_body_size 1m</default> +<context>http, server, location</context> + +<para> +Директива задаёт максимально допустимый размер тела запроса клиента, +указываемый в строке "Content-Length" в заголовке запроса. +Если размер больше заданного, то клиенту возвращается ошибка +"Request Entity Too Large" (413). Следует иметь в виду, что +<link url="http://sysoev.ru/web/upload.html">браузеры не умеют +корректно показывать эту ошибку</link>. +</para> + +</directive> + + +<directive name="default_type"> +<syntax>default_type <value>MIME-тип</value></syntax> +<default>default_type text/plain</default> +<context>http, server, location</context> + +<para> +Директива задаёт MIME-тип ответов по умолчанию. +</para> + +</directive> + + +<directive name="directio"> +<syntax>directio <value>[размер|off]</value></syntax> +<default>directio off</default> +<context>http, server, location</context> + +<para> +Директива (0.7.7) разрешает использовать флаги +O_DIRECT (FreeBSD, Linux), F_NOCACHE (Mac OS X) или функцию directio() (Solaris) +при чтении файлов, размер которых больше либо равен указанному. +Директива автоматически запрещает (0.7.15) использование +<link id="sendfile">sendfile'а</link> для данного запроса. +Рекомендуется использовать для больших файлов: +<example> +directio 4m; +</example> +или при использовании <link id="aio">aio</link> в Linux. +</para> + +</directive> + + +<directive name="directio_alignment"> +<syntax>directio_alignment <value>размер</value></syntax> +<default>directio_alignment 512</default> +<context>http, server, location</context> + +<para> +Директива (0.8.11) устанавливает выравнивание для +<link id="directio">directio</link>. +В большинстве случае достаточно выравнивания 512 байт, однако +при использовании XFS под Linux его нужно увеличить до 4K. +</para> + +</directive> + + +<directive name="error_page"> +<syntax>error_page <value>код [код ...] [=|=ответ] uri</value> +</syntax> +<default>нет</default> +<context>http, server, location, if в location</context> + +<para> +Директива задаёт URI, который будет показываться для указанных ошибок. +Директивы наследуются с предыдущего уровня при условии, что на данном +уровне не описаны свои директивы error_page. +В URI можно использовать переменные. +</para> + +<para> +Пример использования: +<example> +error_page 404 /404.html; +error_page 502 503 504 /50x.html; +error_page 403 http://example.com/forbidden.html; +</example> +</para> + +<para> +Кроме того, можно поменять код ответа на другой, например: +<example> +error_page 404 =200 /empty.gif; +</example> +</para> + +<para> +Если ошибочный ответ обрабатывается проксированным сервером или +FastCGI-сервером и этот сервер может вернуть разные коды ответов, +например, 200, 302, 401 или 404, то можно выдавать возвращаемый код: +<example> +error_page 404 = /404.php; +</example> +</para> + +<para> +Если при перенаправлении не нужно менять URI, то можно перенаправить +обработку ошибки в именованный location: +<example> +location / { + error_page 404 = @fallback; +} + +location @fallback { + proxy_pass http://backend; +} +</example> +</para> + +</directive> + + +<directive name="if_modified_since"> +<syntax>if_modified_since <value>[off|exact|before]</value></syntax> +<default>if_modified_since exact</default> +<context>http, server, location</context> + +<para> +Директива (0.7.24) определяет, как сравнивать время модификации ответа и +время в заголовке запроса "If-Modified-Since": +<list type="bullet"> + +<listitem> +off — не проверять заголовок запроса +"If-Modified-Since" (0.7.34); +</listitem> + +<listitem> +exact — точно совпадение; +</listitem> + +<listitem> +before — время модификации ответа меньше или равно времени, заданному +в заголовке запроса "If-Modified-Since". +</listitem> + +</list> +</para> + +</directive> + + +<directive name="internal"> +<syntax>internal</syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива указывает, что данный location может использоваться только +для внутренних запросов. +Для внешних запросов будет возвращаться ошибка "Not found" (404). +Внутренними запросами являются +<list type="bullet"> + +<listitem> +запросы, перенаправленные директивой error_page; +</listitem> + +<listitem> +подзапросы, формируемые командой include virtual модуля ngx_http_ssi_module; +</listitem> + +<listitem> +запросы, изменённые директивой rewrite модуля ngx_http_rewrite_module. +</listitem> + +</list> +</para> + +<para> +Пример использования: +<example> +error_page 404 /404.html; + +location /404.html { + internal; +} +</example> +</para> + +</directive> + + +<directive name="keepalive_requests"> +<syntax>keepalive_requests <value>число</value></syntax> +<default>keepalive_requests 100</default> +<context>http, server, location</context> + +<para> +Директива (0.8.0) задаёт максимальное число запросов, которые можно +сделать по одному keep-alive соединению. +</para> + +</directive> + + +<directive name="keepalive_timeout"> +<syntax>keepalive_timeout <value>время [время]</value></syntax> +<default>keepalive_timeout 75</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут, в течение которого keep-alive соединение +с клиентом не будет закрыто со стороны сервера. +Второй параметр задаёт значение в строке "Keep-Alive: timeout=время" +в заголовке ответа. Параметры могут отличаться друг от друга. +Строку "Keep-Alive: timeout=время" понимают Mozilla и Konqueror. +MSIE сам закрывает keep-alive соединение примерно через 60 секунд. +</para> + +</directive> + + +<directive name="large_client_header_buffers"> +<syntax>large_client_header_buffers <value>число размер</value> +</syntax> +<default>large_client_header_buffers 4 4k/8k</default> +<context>http, server</context> + +<para> +Директива задаёт максимальное число и размер буферов для чтения +большого заголовка запроса клиента. +Строка запроса должна быть не больше размера одного буфера, иначе клиенту +возвращается ошибка "Request URI too large" (414). +Длинная строка заголовка запроса также должна быть не больше размера одного +буфера, иначе клиенту возвращается ошибка "Bad request" (400). +Буферы выделяются только по мере необходимости. +По умолчанию размер одного буфера равен размеру страницы, в зависимости +от платформы это или 4K, или 8K. +Если по окончании обработки запроса соединение переходит в состояние +keep-alive, то эти буферы освобождаются. +</para> + +</directive> + + +<directive name="limit_except"> +<syntax>limit_except <value>методы</value> { ... }</syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива ограничивает HTTP-методы, доступные внутри location. +Метод GET также включает в себя метод HEAD. +Для ограничения могут использоваться директивы модулей <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> +и <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>: +<example> +limit_except GET { + allow 192.168.1.0/32; + deny all; +} +</example> +Обратите внимание, что данное ограничение будет выполняться для всех методов, +<value>кроме</value> методов GET и HEAD. +</para> + +</directive> + + +<directive name="limit_rate"> + +<syntax>limit_rate <value>скорость</value></syntax> +<default>нет</default> +<context>http, server, location, if в location</context> + +<para> +Директива задаёт скорость передачи ответа клиенту. +Скорость задаётся в байтах в секунду. + +Ограничение работает только для одного соединения, то есть, +если клиент откроет 2 соединения, то суммарная скорость будет в 2 раза +выше ограниченной. +</para> + +<para> +Если необходимо ограничить скорость для части клиентов на уровне сервера, +то директива limit_rate для этого не подходит. Вместо этого следует +задать нужную скорость переменной $limit_rate: +<example> +server { + + if ($slow) { + set $limit_rate 4k; + } + + ... +} +</example> +</para> + +</directive> + + +<directive name="limit_rate_after"> +<syntax>limit_rate_after <value>размер</value></syntax> +<default>нет</default> +<context>http, server, location, if в location</context> + +<para> +Директива (0.8.0) задаёт объём данных, после передачи которого +начинает ограничиваться скорость передачи ответа клиенту, например: +<example> +location /flv/ { + flv; + limit_rate_after 500k; + limit_rate 50k; +} +</example> +</para> + +</directive> + + +<directive name="listen"> +<syntax>listen <value>адрес:порт + [default|default_server| + [backlog=число | + rcvbuf=размер | + sndbuf=размер | + accept_filter=фильтр | + deferred | + bind | + ipv6only=[on|off] | + ssl]] +</value></syntax> +<default>listen *:80 | *:8000</default> +<context>server</context> + +<para> +Директива задаёт адрес и порт, на которых сервер принимает запросы. +Можно указать только адрес или только порт, кроме того, адрес может +быть именем сервера, например: +<example> +listen 127.0.0.1:8000; +listen 127.0.0.1; +listen 8000; +listen *:8000; +listen localhost:8000; +</example> +адреса IPv6 (0.7.36) задаются в квадратных скобках: +<example> +listen [::]:8000; +listen [fe80::1]; +</example> +</para> + +<para> +Если указан только адрес, то используется порт 80. +</para> + +<para> +Если директива не указана, то используется порт *:80, если nginx работает +с правами пользователя root, или порт *:8000. +</para> + +<para> +Если у директивы есть параметр default, то сервер, в котором описана +эта директива, будет сервером по умолчанию для указанной пары адрес:порт. +Если же директив с параметром default нет, то сервером по умолчанию +будет первый сервер, в котором описана пара адрес:порт. +Начиная с версии 0.8.21, можно использовать параметр default_server. +</para> + +<para> +В директиве listen с параметром default можно также указать несколько +параметров, специфичных для системных вызовов listen(2) и bind(2). +Начиная с версии 0.8.21, эти параметры можно задать в любой директиве +listen, но только один раз для указанной пары адрес:порт. +<list type="bullet"> + +<listitem> +backlog=число — задаёт параметр backlog в вызове listen(2). +По умолчанию backlog равен -1 для FreeBSD и 511 для всех остальных +платформ. +</listitem> + +<listitem> +rcvbuf=размер — задаёт параметр SO_RCVBUF для слушающего сокета. +</listitem> + +<listitem> +sndbuf=размер — задаёт параметр SO_SNDBUF для слушающего сокета. +</listitem> + +<listitem> +accept_filter=фильтр — задаёт название accept-фильтра. +Работает только на FreeBSD, можно использовать два фильтра — dataready +и httpready. +По сигналу -HUP accept-фильтр можно менять только в последних +версиях FreeBSD, начиная с 6.0, 5.4-STABLE и 4.11-STABLE. +</listitem> + +<listitem> +deferred — указывает использовать отложенный accept(2) на Linux +с помощью опции TCP_DEFER_ACCEPT. +</listitem> + +<listitem> +bind — указывает, что для данной пары адрес:порт нужно делать bind(2) +отдельно. +Дело в том, что если описаны несколько директив listen с одинаковым портом, +но разными адресами и одна из директив listen слушает на всех адресах +для данного порта (*:порт), то nginx сделает bind(2) только на *:порт. +Необходимо учитывать, что в этом случае для определения адреса, на которой +пришло соединение, делается системный вызов getsockname(). +Если же используются параметры backlog, rcvbuf, sndbuf, accept_filter +или deferred, то для данной пары адрес:порт bind(2) всегда делается отдельно. +</listitem> + +<listitem> +ipv6only — параметр (0.7.42) задаёт значение параметра IPV6_V6ONLY +для слушающего сокета. +Установить этот параметр можно только один раз на старте. +</listitem> + +<listitem> +ssl — параметр (0.7.14) не имеет отношения к системным вызовам +listen(2) и bind(2), а позволяет указать, что все соединения, +принимаемые на этом порту, должны работать в режиме SSL. +Это позволяет задать компактную конфигурацию для сервера, +работающего сразу в двух режимах — HTTP и HTTPS. +<example> +listen 80; +listen 443 default ssl; +</example> +</listitem> + +</list> +</para> + +<para> +Пример использования параметров: +<example> +listen 127.0.0.1 default accept_filter=dataready backlog=1024; +</example> +</para> + +</directive> + + +<directive name="location"> +<syntax>location [<value>=|~|~*|^~|@</value>] <value>/uri/</value> +{ ... }</syntax> +<default>нет</default> +<context>server</context> + +<para> +Директива устанавливает конфигурацию в зависимости от URI запроса. +location можно задать обычной строкой или регулярным выражением. +Регулярные выражения задаются префиксом "~*" — без учёта регистра +символов, и "~" — с учётом. +Для определения соответствия location'а и запроса +сначала проверяются location'ы, заданные обычными строками. +Среди них ищется максимальное совпадение. +Затем проверяются регулярные выражения. +В отличие от обычных строк, они не сортируются, а проверяются в порядке +их следования в конфигурационном файле. +Проверка регулярных выражений прекращается после первого же совпадения. +Если совпадение с регулярным выражением не найдено, то используется +конфигурация максимально совпавшего location'а. +</para> + +<para> +Для операционных систем, не чувствительных к регистру символов, таких +как Mac OS X и Cygwin, проверка обычных строк делается без учёта +регистра (0.7.7). +Однако, сравнение ограничено только однобайтными locale'ями. +</para> + +<para> +Регулярное выражение может содержать выделения (0.7.40), которые +могут затем использоваться в других директивах. +</para> + +<para> +Если нужно запретить проверку регулярных выражений после проверки +обычных строк, то это можно сделать с помощью префикса "^~". +Если у максимально совпавшего location'а есть этот префикс, то +регулярные выражения не проверяются. +</para> + +<para> +Кроме того, с помощью префикса "=" можно задать точное совпадение +URI и location. При совпадении поиск сразу же прекращается, так как +дальше искать не имеет смысла. Например, если запрос "/" очень частый, +то указав "location = /", можно ускорить обработку этого запроса, +так как поиск location прекратится после первого же сравнения. +</para> + +<para> +В версиях с 0.7.1 по 0.8.41, если запрос точно совпал с обычным location'ом +без префиксов "=" и "^~", то поиск тоже сразу же прекращается и +регулярные выражения также не проверяются. +</para> + +<para> +Проиллюстрируем вышесказанное примером: +<example> +location = / { + [ конфигурация A ] +} + +location / { + [ конфигурация B ] +} + +location ^~ /images/ { + [ конфигурация C ] +} + +location ~* \.(gif|jpg|jpeg)$ { + [ конфигурация D ] +} +</example> +Для запроса "/" будет выбрана конфигурация A, +для запроса "/documents/document.html" — конфигурация B, +для запроса "/images/1.gif" — конфигурация C, +для запроса "/documents/1.jpg" — конфигурация D. +</para> + +<para> +Префикс "@" задаёт именованный location. Такой location не используется +при обычной обработке запросов, а предназначен только для перенаправления +в него запросов. +</para> + +</directive> + + +<directive name="log_not_found"> +<syntax>log_not_found <value>[on|off]</value></syntax> +<default>log_not_found on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает записывать в error_log +ошибки о том, что файл не найден. +</para> + +</directive> + + +<directive name="log_subrequest"> +<syntax>log_subrequest <value>[on|off]</value></syntax> +<default>log_subrequest off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает записывать в <link doc="ngx_http_log_module.xml#access_log">access_log</link> +подзапросы. +</para> + +</directive> + + +<directive name="merge_slashes"> +<syntax>merge_slashes <value>[on|off]</value></syntax> +<default>merge_slashes on</default> +<context>http, server</context> + +<para> +Директива разрешает или запрещает объединять в URI два и более слэшей в один. +</para> + +<para> +Необходимо иметь ввиду, что это объединение необходимо для корректной +проверки location'ов и регулярных выражений. +Например, запрос "//scripts/one.php" не попадает в +<example> +location /scripts/ { + ... +} +</example> +и может быть обслужен как статический файл, +поэтому он приводится в "/scripts/one.php". +</para> + +<para> +Выключение объединения может понадобиться, если в URI используются имена, +закодированные методом base64, который использует символ "/". +Но по соображениям безопасности лучше избегать выключения объединения. +</para> + +<para> +Если директива указана на уровне server в сервере по умолчанию, +то её значение распространяется на все виртуальные сервера, слушающие +на том же адресе и порту. +</para> + +</directive> + + +<directive name="msie_padding"> +<syntax>msie_padding <value>[on|off]</value></syntax> +<default>msie_padding on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает добавлять в ответы для MSIE +со статусом больше 400 +комментарий для увеличения размера ответа до 512 байт. +</para> + +</directive> + + +<directive name="msie_refresh"> +<syntax>msie_refresh <value>[on|off]</value></syntax> +<default>msie_refresh off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает выдавать для MSIE refresh'ы вместо +редиректов. +</para> + +</directive> + + +<directive name="open_file_cache"> +<syntax>open_file_cache <value>max=N [inactive=время]|off</value> +</syntax> +<default>open_file_cache off</default> +<context>http, server, location</context> + +<para> +Директива задаёт кэш, в котором могут хранится +<list type="bullet"> + +<listitem> +дескрипторы открытых файлов, информация об их размерах и времени модификации; +</listitem> + +<listitem> +информация о существовании каталогов; +</listitem> + +<listitem> +информация об ошибках поиска файла — нет файла, нет прав на чтение +и тому подобное. Кэширование ошибок нужно разрешить директивой +<link id="open_file_cache_errors"/>. +</listitem> + +</list> +</para> + +<para> +Параметры директивы: +<list type="bullet"> + +<listitem> +max — задаёт максимальное число элементов в кэше; +при переполнении кэша удаляются наиболее давно не используемые элементы (LRU); +</listitem> + +<listitem> +inactive — задаёт время, после которого элемент кэша удаляется, +если к нему не было обращений в течение этого времени; +по умолчанию 60 секунд; +</listitem> + +<listitem> +off — запрещает кэш. +</listitem> + +</list> +</para> + +<para> +Пример использования: +<example> +open_file_cache max=1000 inactive=20s; +open_file_cache_valid 30s; +open_file_cache_min_uses 2; +open_file_cache_errors on; +</example> +</para> + +</directive> + + +<directive name="open_file_cache_errors"> +<syntax>open_file_cache_errors <value>on|off</value></syntax> +<default>open_file_cache_errors off</default> +<context>http, server, location</context> + +<para> +Директива определяет, кэшировать или нет ошибки поиска файлов в +<link id="open_file_cache"/>. +</para> + +</directive> + + +<directive name="open_file_cache_min_uses"> +<syntax>open_file_cache_min_uses <value>число</value></syntax> +<default>open_file_cache_min_uses 1</default> +<context>http, server, location</context> + +<para> +Директива определяет минимальное число использований файла в течение +времени, заданного параметром inactive в директиве +<link id="open_file_cache"/>, после которого дескриптор файла +будет оставаться открытым в кэше. +</para> + +</directive> + + +<directive name="open_file_cache_valid"> +<syntax>open_file_cache_valid <value>время</value></syntax> +<default>open_file_cache_valid 60</default> +<context>http, server, location</context> + +<para> +Директива определяет, через какое время нужно проверять актуальность +информации об элементе в <link id="open_file_cache"/>. + +</para> + +</directive> + + +<directive name="optimize_server_names"> +<syntax>optimize_server_names <value>[on|off]</value></syntax> +<default>optimize_server_names on</default> +<context>http, server</context> + +<para> +Устаревшая директива. +</para> + +<para> +Директива разрешает или запрещает оптимизировать проверку имени хоста +в name-based виртуальных серверах. +Проверка в частности влияет на имя хоста, используемого в редиректах. +Если оптимизация разрешена и все name-based сервера, слушающие на одной +паре адрес:порт, имеют одинаковую конфигурацию, то во время исполнения +запроса имена не проверяются и в редиректах используется первое имя сервера. +Если в редиректе нужно использовать имя хоста, переданное клиентом, +то оптимизацию нужно выключить. +</para> + +</directive> + + +<directive name="port_in_redirect"> +<syntax>port_in_redirect <value>[on|off]</value></syntax> +<default>port_in_redirect on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает указывать порт в редиректах, +выдаваемых nginx'ом. +</para> + +</directive> + + +<directive name="read_ahead"> +<syntax>read_ahead <value>размер</value></syntax> +<default>read_ahead 0</default> +<context>http, server, location</context> + +<para> +Директива задаёт ядру размер предчтения при работе с файлами. +Под Линуксом используется системный вызов +<example> +posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL); +</example> +поэтому размер игнорируется. +</para> + +<para> +Под FreeBSD используется fcntl(O_READAHEAD, размер), появившийся +во FreeBSD-9 CURRENT. Для FreeBSD 7 нужно установить +<link url="http://sysoev.ru/freebsd/patch.readahead.txt">патч</link>. +</para> + +</directive> + + +<directive name="recursive_error_pages"> +<syntax>recursive_error_pages <value>[on|off]</value></syntax> +<default>recursive_error_pages off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает делать несколько перенаправлений через +директиву <link id="error_page"/>. +</para> + +</directive> + + +<directive name="reset_timedout_connection"> +<syntax>reset_timedout_connection <value>[on|off]</value></syntax> +<default>reset_timedout_connection off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает сбрасывать соединение по таймауту. +Сброс делается следующим образом — перед закрытием сокета для него +ставится опция SO_LINGER с таймаутом 0. После чего при закрытии сокета +клиенту отсылается пакет RST, а всё память, связанная с этим сокетом, +освобождается. Это позволяет избежать длительного нахождения уже закрытого +сокета в состоянии FIN_WAIT1 с заполненными буферами. +</para> + +<para> +Необходимо отметить, что соединения, находящиеся в состоянии keepalive, +по истечении таймаута закрываются обычным образом. +</para> + +</directive> + + +<directive name="resolver"> +<syntax>resolver <value>адрес</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт адрес name-сервера, например: +<example> + resolver 127.0.0.1; +</example> +</para> + +</directive> + + +<directive name="resolver_timeout"> +<syntax>resolver_timeout <value>время</value></syntax> +<default>resolver_timeout 30s</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут для определения имени, например: +<example> + resolver_timeout 5s; +</example> +</para> + +</directive> + + +<directive name="root"> +<syntax>root <value>путь</value></syntax> +<default>root html</default> +<context>http, server, location, if в location</context> + +<para> +Директива задаёт корневой каталог для запросов. +Например, при такой конфигурации +<example> + location /i/ { + root /data/w3; + } +</example> +на запрос "/i/top.gif" будет отдан файл "/data/w3/i/top.gif". +</para> + +<para> +В значении пути можно использовать переменные. +</para> + +<para> +Путь к файлу формируется как простое добавление URI к значению директивы root. +Если же необходима модификация URI, то нужно воспользоваться директивой +<link id="alias"/>. +</para> + +</directive> + + +<directive name="satisfy"> +<syntax>satisfy <value>all|any</value></syntax> +<default>satisfy all</default> +<context>location</context> + +<para> +Директива разрешает доступ при хотя бы одной успешной проверке, +выполненной модулями <link doc="ngx_http_access_module.xml">ngx_http_access_module</link> +или <link doc="ngx_http_auth_basic_module.xml">ngx_http_auth_basic_module</link>: +<example> +location / { + satisfy any; + + allow 192.168.1.0/32; + deny all; + + auth_basic "closed site"; + auth_basic_user_file conf/htpasswd; +} +</example> +</para> + +</directive> + + +<directive name="satisfy_any"> +<syntax>satisfy_any <value>on|off</value></syntax> +<default>satisfy_any off</default> +<context>location</context> + +<para> +Директива переименована в директиву <link id="satisfy"/>. +</para> + +</directive> + + +<directive name="send_timeout"> +<syntax>send_timeout <value>время</value></syntax> +<default>send_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут при передаче ответа клиенту. +Таймаут устанавливается не на всю передачу ответа, +а только между двумя операциями записями. +Если по истечении этого времени клиент ничего не примет, +то nginx закрывает соединение. +</para> + +</directive> + + +<directive name="sendfile"> +<syntax>sendfile <value>[on|off]</value></syntax> +<default>sendfile off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает использовать sendfile(). +</para> + +</directive> + + +<directive name="server"> +<syntax>server { ... }</syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива задаёт конфигурацию для виртуального сервера. +Чёткого разделения виртуальных серверов ip-based (на основании ip-адреса) +и name-based (на основании имени, передаваемого в строке "Host" +заголовка запроса), нет. +Вместо этого директивами <link id="listen"/> описываются все адреса +и порты, на которых нужно принимать соединения для этого сервера, +и в директиве <link id="server_name"/> указываются все имена серверов. +Пример конфигурации описан в <link doc="../virtual_hosts.xml"> +настройке виртуальных серверов</link>. +</para> + +</directive> + + +<directive name="server_name"> +<syntax>server_name <value>имя [...]</value></syntax> +<default>server_name hostname</default> +<context>server</context> + +<para> +Директива задаёт имена виртуального сервера, например: +<example> +server { + server_name example.com www.example.com; +} +</example> +</para> + +<para> +Первое имя становится основным именем сервера. +По умолчанию используется имя машины (hostname). +В именах серверов можно использовать "*" для замены первой или последней +части имени: +<example> +server { + server_name example.com *.example.com www.example.*; +} +</example> +</para> + +<para> +Два первых вышеприведённых имени можно объединить в одно: +<example> +server { + server_name .example.com; +} +</example> +</para> + +<para> +Кроме того, в качестве имени сервера можно использовать регулярное +выражение, указав перед ним "~": +<example> +server { + server_name www.example.com ~^www\d+\.example\.com$; +} +</example> +</para> + +<para> +Регулярное выражение может содержать выделения (0.7.40), которые +могут затем использоваться в других директивах: +<example> +server { + server_name ~^(www\.)?(.+)$; + + location / { + root /sites/$2; + } +} + +server { + server_name _; + + location / { + root /sites/default; + } +} +</example> +</para> + +<para> +Начиная с 0.8.25, именованные выделения в регулярном выражении создают +переменные, которые могут затем использоваться в других директивах: +<example> +server { + server_name ~^(www\.)?(<emphasis>?<domain></emphasis>.+)$; + + location / { + root /sites/<emphasis>$domain</emphasis>; + } +} + +server { + server_name _; + + location / { + root /sites/default; + } +} +</example> +</para> + +<para> +Начиная с 0.7.11, можно использовать пустое имя "": +<example> +server { + server_name www.example.com ""; +} +</example> +что позволяет обрабатывать запросы без строки "Host" в заголовке запроса +в этом сервере, а не в сервере по умолчанию для данной пары адрес:порт. +</para> + +<para> +Порядок проверки имён следующий: +<list type="bullet"> + +<listitem> +полные имена, +</listitem> + +<listitem> +имена с маской в начале имени — *.example.com, +</listitem> + +<listitem> +имена с маской в конце имени — mail.*, +</listitem> + +<listitem> +регулярные выражения. +</listitem> + +</list> +</para> + +</directive> + + +<directive name="server_name_in_redirect"> +<syntax>server_name_in_redirect <value>[on|off]</value></syntax> +<default>server_name_in_redirect on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает использовать в редиректах, выдаваемых +nginx'ом, основное имя сервера, задаваемое директивой +<link id="server_name"/>. +Если использование основного имени запрещено, то используется имя, +указанного в строке "Host" в заголовке запроса. +Если же этой строки нет, то используется IP-адрес сервера. +</para> + +</directive> + + +<directive name="server_names_hash_max_size"> +<syntax>server_names_hash_max_size <value>число</value></syntax> +<default>server_names_hash_max_size 512</default> +<context>http</context> + +<para> +Директива задаёт максимальный размер хэш-таблиц имён серверов. +Подробнее смотри в <link doc="../hash.xml">описании +настройки хэшей</link>. +</para> + +</directive> + + +<directive name="server_names_hash_bucket_size"> +<syntax>server_names_hash_bucket_size <value>число</value></syntax> +<default>server_names_hash_bucket_size 32/64/128</default> +<context>http</context> + +<para> +Директива задаёт размер корзины в хэш-таблицах имён серверов. +Значение по умолчанию зависит от размера строки кэша процессора. +Подробнее смотри в <link doc="../hash.xml">описании +настройки хэшей</link>. +</para> + +</directive> + + +<directive name="server_tokens"> +<syntax>server_tokens <value>[on|off]</value></syntax> +<default>server_tokens on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает выдавать версию nginx'а +в сообщениях об ошибках и в строке заголовка ответа "Server". +</para> + +</directive> + + +<directive name="tcp_nodelay"> +<syntax>tcp_nodelay <value>[on|off]</value></syntax> +<default>tcp_nodelay on</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает использовать опцию TCP_NODELAY. +Опция включаются только при переходе соединения в состояние keep-alive. +</para> + +</directive> + + +<directive name="tcp_nopush"> +<syntax>tcp_nopush <value>[on|off]</value></syntax> +<default>tcp_nopush off</default> +<context>http, server, location</context> + +<para> +Директива разрешает или запрещает использовать опции +TCP_NOPUSH во FreeBSD или TCP_CORK в Linux. +Опции включаются только при использовании <link id="sendfile"/>. +Включение опции позволяет +<list type="bullet"> + +<listitem> +передавать заголовок ответа и начало файла в одном пакете в Linux +и во FreeBSD 4.x; +</listitem> + +<listitem> +передавать файл в полных пакетах. +</listitem> + +</list> +</para> + +</directive> + + +<directive name="try_files"> +<syntax>try_files <value>файл [файл ...] (uri|=код)</value></syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива проверяет существование файлов в заданном порядке +и использует для обработки запроса первый найденный файл, причём +обработка делается в контексте этого же location'а. +С помощью слэша в конце имени можно задать проверку существования +каталога, например, так — "$uri/". +В случае, если ни один файл не найден, то делается внутренний редирект +на последний параметр. +Последний параметр может быть кодом (0.7.51): +<example> +location / { + try_files $uri $uri/index.html $uri.html =404; +} +</example> +</para> + +<para> +Пример использования при проксировании Mongrel: +<example> +location / { + try_files /system/maintenance.html + $uri $uri/index.html $uri.html + @mongrel; +} + +location @mongrel { + proxy_pass http://mongrel; +} +</example> +</para> + +<para> +Пример использования вместе с Drupal/FastCGI: +<example> +location / { + try_files $uri $uri/ @drupal; +} + +location ~ \.php$ { + try_files $uri @drupal; + + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + fastcgi_param SCRIPT_NAME $fastcgi_script_name; + fastcgi_param QUERY_STRING $args; + + ... прочие fastcgi_param +} + +location @drupal { + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to/index.php; + fastcgi_param SCRIPT_NAME /index.php; + fastcgi_param QUERY_STRING q=$uri&$args; + + ... прочие fastcgi_param +} +</example> +В этом примере директива try_files +<example> +location / { + try_files $uri $uri/ @drupal; +} +</example> +аналогична директивам +<example> +location / { + error_page 404 = @drupal; + log_not_found off; +} +</example> +А здесь +<example> +location ~ \.php$ { + try_files $uri @drupal; + + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + + ... +} +</example> +try_files тестирует существование PHP-файла, +прежде чем передать запрос FastCGI-серверу. +</para> + +<para> +Пример использования вместе с Wordpress и Joomla: +<example> +location / { + try_files $uri $uri/ @wordpress; +} + +location ~ \.php$ { + try_files $uri @wordpress; + + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to$fastcgi_script_name; + ... прочие fastcgi_param +} + +location @wordpress { + fastcgi_pass ...; + + fastcgi_param SCRIPT_FILENAME /path/to/index.php; + ... прочие fastcgi_param +} +</example> +</para> + +</directive> + + +<directive name="types"> +<syntax>types <value>{ ... }</value></syntax> +<default>see below</default> +<context>http, server, location</context> + +<para> +Директива задаёт соответствие расширения и MIME-типов ответов. +Одному MIME-типу может соответствовать несколько расширений. +По умолчанию используется такие соответствия: +<example> +types { + text/html html; + image/gif gif; + image/jpeg jpg; +} +</example> +</para> + +<para> +Достаточно полная таблица соответствий входит в дистрибутив +и находится в файле conf/mime.types. +</para> + +<para> +Для того, чтобы для определённого location'а для всех ответов выдавался +MIME-тип "application/octet-stream", можно использовать следующее: +<example> +location /download/ { + types { } + default_type application/octet-stream; +} +</example> +</para> + +</directive> + + +<directive name="underscores_in_headers"> +<syntax>underscores_in_headers <value>[on|off]</value></syntax> +<default>underscores_in_headers off</default> +<context>http, server</context> + +<para> +Директива разрешает или запрещает использование символов подчёркивания +в строках заголовка запроса клиента. +</para> + +</directive> + +</section> + + +<section name="Встроенные переменные" id="variables"> + +<para> +Модуль ngx_http_core_module поддерживает встроенные переменные, имена +которых совпадают с именами переменных в Apache. +Прежде всего, это переменные, представляющие из себя строки заголовка +запроса клиента, например, $http_user_agent, $http_cookie +и тому подобное. Кроме того, есть и другие переменные: +<list type="bullet"> + +<listitem> +$args, эта переменная равна аргументам в строке запроса; +</listitem> + +<listitem> +$arg_<value>name</value>, эта переменная равна аргументу <value>name</value> +в строке запроса; +</listitem> + +<listitem> +$binary_remote_addr, эта переменная равна адресу клиента в бинарном виде, +длина её значения всегда 4 байта; +</listitem> + +<listitem> +$content_length, эта переменная равна строке "Content-Length" в заголовке +запроса; +</listitem> + +<listitem> +$content_type, эта переменная равна строке "Content-Type" в заголовке запроса; +</listitem> + +<listitem> +$cookie_<value>name</value>, эта переменная равна cookie <value>name</value>; +</listitem> + +<listitem> +$document_root, эта переменная равна значению директивы root для +текущего запроса; +</listitem> + +<listitem> +$document_uri, то же самое, что и $uri; +</listitem> + +<listitem> +$host, эта переменная равна строке "Host" в заголовке запроса +или имени сервера, на который пришёл запрос, если этой строки нет; +</listitem> + +<listitem> +$hostname, эта переменная равна имени хоста; +</listitem> + +<listitem> +$http_<value>name</value>, эта переменная равна строке <value>name</value> +в заголовке запроса; +</listitem> + +<listitem> +$is_args, эта переменная равна "?", если в строке запроса есть аргументы, +и пустой строке, если их нет; +</listitem> + +<listitem> +$limit_rate, эта переменная позволяет установить ограничение +скорости соединения; +</listitem> + +<listitem> +$pid, эта переменная равна номеру рабочего процесса; +</listitem> + +<listitem> +$request_method, эта переменная равна методу запроса, +обычно это "GET" или "POST"; +</listitem> + +<listitem> +$remote_addr, эта переменная равна адресу клиента; +</listitem> + +<listitem> +$remote_port, эта переменная равна порту клиента; +</listitem> + +<listitem> +$remote_user, эта переменная равна имени пользователя, используемого +в Basic аутентификации; +</listitem> + +<listitem> +$realpath_root, эта переменная равна значению директивы root для +текущего запроса, при этом все символические ссылки преобразованы +в реальные путь; +</listitem> + +<listitem> +$request_filename, эта переменная равна пути к файлу для текущего +запроса, формируемому из директив root или alias и URI запроса; +</listitem> + +<listitem> +$request_body, эта переменная содержит тело запроса. +Значение переменной появляется в location'ах, обрабатываемых директивами +<link doc="ngx_http_proxy_module.xml#proxy_pass">proxy_pass</link> +и <link doc="ngx_http_fastcgi_module.xml#fastcgi_pass">fastcgi_pass</link>. +</listitem> + +<listitem> +$request_body_file, эта переменная равна имени временного файла, в котором +хранится тело запроса. +По завершению работы файл необходимо удалить. +Для того, чтобы тело запроса клиента всегда записывалось в файл, нужно +указать <link doc="ngx_http_core_module.xml#client_body_in_file_only">client_body_in_file_only on</link>. +При передаче имени в проксированном запросе или в запросе к FastCGI-серверу +следует запретить передачу самого тела директивами +"proxy_pass_request_body off" или +"fastcgi_pass_request_body off" соответственно. +</listitem> + +<listitem> +$request_uri, эта переменная равна полному первоначальному URI вместе +с аргументами; +</listitem> + +<listitem> +$query_string, то же самое, что и $args; +</listitem> + +<listitem> +$scheme, эта переменная равна схеме запроса — "http" или "https"; +</listitem> + +<listitem> +$server_protocol, эта переменная равна протоколу запроса, +обычно это "HTTP/1.0" или "HTTP/1.1"; +</listitem> + +<listitem> +$server_addr, эта переменная равна адресу сервера, на который пришёл запрос. +Как правило, для получения значения этой переменной делается один системный +вызов. Для того, чтобы избежать системного вызова, нужно указывать +адреса в директивах listen и использовать параметр bind; +</listitem> + +<listitem> +$server_name, эта переменная равна имени сервера, на который пришёл запрос; +</listitem> + +<listitem> +$server_port, эта переменная равна порту сервера, на который пришёл запрос; +</listitem> + +<listitem> +$uri, эта переменная равна текущему URI в запросе, он +может отличаться от первоначального, например, при внутренних редиректах +или при использовании индексных файлов. +</listitem> + +</list> +</para> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_dav_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,144 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_dav_module" + link="/ru/docs/http/ngx_http_dav_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_dav_module обрабатывает HTTP- и WebDAV-методы +PUT, DELETE, MKCOL, COPY и MOVE. +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром <command>--with-http_dav_module</command>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + location / { + root /data/www; + + client_body_temp_path /data/client_temp; + + dav_methods PUT DELETE MKCOL COPY MOVE; + + create_full_put_path on; + dav_access group:rw all:r; + + limit_except GET { + allow 192.168.1.0/32; + deny all; + } + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="dav_access"> +<syntax>dav_access <value>пользователи:права [пользователи:права] ...</value> +</syntax> +<default>dav_access user:rw</default> +<context>http, server, location</context> + +<para> +Директива задаёт права доступа для создаваемых файлов и каталогов, +например, +<example> +dav_access user:rw group:rw all:r; +</example> +Если заданы какие-либо права для groups или all, то права для user +указывать необязательно: +<example> +dav_access group:rw all:r; +</example> +</para> + +</directive> + + +<directive name="dav_methods"> +<syntax>dav_methods <value>[off|put|delete|mkcol|copy|move] ...</value></syntax> +<default>dav_methods off</default> +<context>http, server, location</context> + +<para> +Директива разрешает указанные HTTP- и WebDAV-методы. +Параметр off запрещает все методы, обарабатываемые данным модулем, +игнорируя остальные параметры; +</para> + +<para> +Файл, загружаемый методом PUT, записывается во временный файл, +а потом этот файл переименовывается. +Начиная с версии 0.8.9, временный файл и его постоянное место хранения +могут располагаться на разных файловых системах, но нужно учитывать, +что в этом случае вместо дешёвой операции переименовывания в пределах +одной файловой системы файл копируется с одной файловой системы на другую. +Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой +системе, что и каталог с временными файлами, задаваемый директивой <link doc="ngx_http_core_module.xml#client_body_temp_path">client_body_temp_path</link> +для данного location. +</para> + +<para> +При создании файла с помощью метода PUT можно задать дату модификации, +передав её в строке заголовка "Date". +</para> + +</directive> + + +<directive name="create_full_put_path"> +<syntax>create_full_put_path <value>on|off</value></syntax> +<default>create_full_put_path off</default> +<context>http, server, location</context> + +<para> +По спецификации WebDAV метод PUT может создавать файл только в +уже существующем каталоге. Данная директива разрешает создавать +все необходимые промежуточные каталоги. + +</para> + +</directive> + + +<directive name="min_delete_depth"> +<syntax>min_delete_depth <value>число</value></syntax> +<default>min_delete_depth 0</default> +<context>http, server, location</context> + +<para> +Данная директива разрешает методу DELETE удалять файлы +при условии, что число элементов в пути запроса не меньше заданного. +Например, директива +<example> +min_delete_depth 4; +</example> +разрешает удалять файлы по запросам +<example> +/users/00/00/name +/users/00/00/name/pic.jpg +/users/00/00/page.html +</example> +и запрещает удаление +<example> +/users/00/00 +</example> +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_empty_gif_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,46 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_empty_gif_module" + link="/ru/docs/http/ngx_http_empty_gif_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_empty_gif_module выдаёт одно-пиксельный прозрачный GIF. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + location = /_.gif { + empty_gif; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="empty_gif"> +<syntax>empty_gif</syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива разрешает выдавать одно-пиксельный прозрачный GIF. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_fastcgi_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,719 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_fastcgi_module" + link="/ru/docs/http/ngx_http_fastcgi_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_fastcgi_module позволяет передавать запросы +удалённому FastCGI-серверу. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +location / { + fastcgi_pass localhost:9000; + fastcgi_index index.php; + + fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; + fastcgi_param QUERY_STRING $query_string; + fastcgi_param REQUEST_METHOD $request_method; + fastcgi_param CONTENT_TYPE $content_type; + fastcgi_param CONTENT_LENGTH $content_length; +} +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="fastcgi_buffer_size"> +<syntax>fastcgi_buffer_size <value>размер</value></syntax> +<default>fastcgi_buffer_size 4k/8k</default> +<context>http, server, location</context> + +<para> +Директива задаёт размер буфера, в который будет читаться +первая часть ответа, получаемого от FastCGI-сервера. +В этой части ответа находится, как правило, небольшой заголовок ответа. +По умолчанию размер буфера равен размеру одного буфера в директиве +<link id="fastcgi_buffers"/>, однако его можно сделать меньше. +</para> + +</directive> + + +<directive name="fastcgi_buffers"> +<syntax>fastcgi_buffers <value>число размер</value></syntax> +<default>fastcgi_buffers 8 4k/8k</default> +<context>http, server, location</context> + +<para> +Директива задаёт число и размер буферов для одного соединения, +в которые будет читаться ответ, получаемый от FastCGI-сервера. +По умолчанию размер одного буфера равен размеру страницы, в зависимости +от платформы это или 4K, или 8K. +</para> + +</directive> + + +<directive name="fastcgi_cache"> +<syntax>fastcgi_cache <value>[зона|off]</value></syntax> +<default>off</default> +<context>http, server, location</context> + +<para> +Директива задаёт зону для кэширования. +Одна и та же зона может использоваться в нескольких местах. +Параметр "off" запрещает кэширование, унаследованное с предыдущего +уровня конфигурации. +</para> + +</directive> + + +<directive name="fastcgi_cache_bypass"> +<syntax>fastcgi_cache_bypass <value>строка [...]</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт условия, при которых ответ не будет браться из кэша. +Если значение хотя бы одной из строк переменных не пустое и не равно "0", +то ответ не берётся из кэша: +<example> +fastcgi_cache_bypass $cookie_nocache $arg_nocache$arg_comment; +fastcgi_cache_bypass $http_pragma $http_authorization; +</example> +Можно использовать совместно с директивой <link id="fastcgi_no_cache"/>. +</para> + +</directive> + + +<directive name="fastcgi_cache_key"> +<syntax>fastcgi_cache_key <value>строка</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт ключ для кэширования, например, +<example> +fastcgi_cache_key localhost:9000$request_uri; +</example> +</para> + +</directive> + + +<directive name="fastcgi_cache_path"> +<syntax>fastcgi_cache_path <value>путь [levels=уровни] +keys_zone=название:размер [inactive=время] [max_size=размер]</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. +Ключом и именем файла в кэше является результат функции md5 от +проксированного URL. Параметр levels задаёт уровни иерархии кэша, +например, при использовании +<example> +fastcgi_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; +</example> +имена файлов в кэше будут такого вида: +<example> +/data/nginx/cache/<emphasis>c/29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis> +</example> +</para> + +<para> +Кэшируемый ответ записывается во временный файл, а потом этот файл +переименовывается. Начиная с версии 0.8.9, временные файлы и кэш +могут располагаться на разных файловых системах, но нужно учитывать, +что в этом случае вместо дешёвой операции переименовывания в пределах +одной файловой системы файл копируется с одной файловой системы на другую. +Поэтому лучше, если кэш будет находиться на той же файловой +системе, что и каталог с временными файлами, задаваемый директивой +<link id="fastcgi_temp_path"/> для данного location. +</para> + +<para> +Кроме того, все активные ключи и информация о данных хранятся в разделяемой +памяти — зоне, имя и размер которой задаётся параметром keys_zone. +Если к данным кэша не обращются в течение времени, заданного параметром +inactive, то данные удаляются, независимо от их свежести. +По умолчанию inactive равен 10 минутам. +</para> + +<para> +Специальный процесс "cache manager" следит за максимальным размером кэша, +заданным параметром max_size, и при превышении его размеров удаляет +самые невостребованные данные. +</para> + +</directive> + + +<directive name="fastcgi_cache_min_uses"> +<syntax>fastcgi_cache_min_uses <value>число</value></syntax> +<default>fastcgi_cache_min_uses 1</default> +<context>http, server, location</context> + +<para> +Директива задаёт число запросов, после которого ответ будет +закэширован. +</para> + +</directive> + + +<directive name="fastcgi_cache_valid"> +<syntax>fastcgi_cache_valid <value>ответ [ответ ...] время</value> +</syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт время кэширования для разных ответов. +Например, директивы +<example> +fastcgi_cache_valid 200 302 10m; +fastcgi_cache_valid 404 1m; +</example> +задают время кэширования 10 минут для ответов 200 и 302, +и 1 минуту для ответов 404. +</para> + +<para> +Если указано только время кэширования, +<example> +fastcgi_cache_valid 5m; +</example> +то кэшируются только ответы 200, 301 и 302. +</para> + +<para> +Кроме того, может кэшировать любые ответы с помощью параметра "any": +<example> +fastcgi_cache_valid 200 302 10m; +fastcgi_cache_valid 301 1h; +fastcgi_cache_valid any 1m; +</example> +</para> + +</directive> + + +<directive name="fastcgi_cache_use_stale"> +<syntax>fastcgi_cache_use_stale <value>[error | timeout | invalid_header + | updating | http_500 | http_503 | http_404 | off] +[...]</value></syntax> +<default>fastcgi_cache_use_stale off</default> +<context>http, server, location</context> + + +<para> +Директива определяет, в каких случаях можно использовать +устаревший закэшированный ответ, если при работе с проксированным +сервером возникла ошибка. Параметры директивы совпадают с параметрами +директивы <link id="fastcgi_next_upstream"/>. +И, кроме того, есть параметр updating, которой разрешает использовать +устаревший закэшированный ответ, если на данный момент он уже обновляется. +</para> + +</directive> + + +<directive name="fastcgi_connect_timeout"> +<syntax>fastcgi_connect_timeout <value>время</value></syntax> +<default>fastcgi_connect_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут для соединения с FastCGI-сервером. +Необходимо иметь в виду, что этот таймаут не может быть больше 75 секунд. +</para> + +</directive> + + +<directive name="fastcgi_index"> +<syntax>fastcgi_index <value>имя</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт имя файла, который при создании переменной +$fastcgi_script_name будет добавляться после URI, если URI +заканчивается слэшом. Например, при таких настройках +<example> +fastcgi_index index.php; +fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; +</example> +и запросе "/page.php" параметр SCRIPT_FILENAME будет равен +"/home/www/scripts/php/page.php", +а при запросе "/" — "/home/www/scripts/php/index.php". +</para> + +</directive> + + +<directive name="fastcgi_hide_header"> +<syntax>fastcgi_hide_header <value>имя</value></syntax> +<context>http, server, location</context> + +<para> +nginx не передаёт клиенту строки заголовка "Status" и "X-Accel-..." +из ответа FastCGI-сервера. +Директива fastcgi_hide_header задаёт дополнительные строки. +Если же строки нужно наоброт разрешить, то нужно воспользоваться +директивой <link id="fastcgi_pass_header"/>. +</para> + +</directive> + + +<directive name="fastcgi_ignore_client_abort"> +<syntax>fastcgi_ignore_client_abort <value>[on|off]</value></syntax> +<default>fastcgi_ignore_client_abort off</default> +<context>http, server, location</context> + + +<para> +Директива определяет, закрывать ли соединение с FastCGI-сервером +в случае, если клиент закрыл соединение, не дождавшись ответа. +</para> + +</directive> + + +<directive name="fastcgi_ignore_headers"> +<syntax>fastcgi_ignore_headers <value>имя [имя ...]</value></syntax> +<context>http, server, location</context> + +<para> +Директива fastcgi_ignore_headers запрещает обработку некоторых +строк заголовка из ответа FastCGI-сервера. +В директиве можно указать строки "X-Accel-Redirect", "X-Accel-Expires", +"Expires" и "Cache-Control". +</para> + +</directive> + + +<directive name="fastcgi_intercept_errors"> +<syntax>fastcgi_intercept_errors <value>on|off</value></syntax> +<default>fastcgi_intercept_errors off</default> +<context>http, server, location</context> + +<para> +Директива определяет, передавать ли клиенту ответы FastCGI-сервера с кодом +больше или равные 400 или же перенаправлять их на обработку nginx'у с помощью +директивы error_page. +</para> + +</directive> + + +<directive name="fastcgi_no_cache"> +<syntax>fastcgi_no_cache <value>строка [...]</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт условия, при которых ответ не будет сохраняться в кэш. +Если значение хотя бы одной из строк переменных не пустое и не равно "0", +то ответ не будет сохранён: +<example> +fastcgi_no_cache $cookie_nocache $arg_nocache$arg_comment; +fastcgi_no_cache $http_pragma $http_authorization; +</example> +Можно использовать совместно с директивой +<link id="fastcgi_cache_bypass"/>. +</para> + +</directive> + + +<directive name="fastcgi_next_upstream"> +<syntax>fastcgi_next_upstream +<value>[error|timeout|invalid_header|http_500|http_503|http_404|off]</value> +</syntax> +<default>fastcgi_next_upstream error timeout</default> +<context>http, server, location</context> + + +<para> +Директива определяет, в каких случаях запрос будет передан следующему серверу: +<list type="bullet"> + +<listitem> +error — произшла ошибка соединения с сервером, передачи ему запроса или +чтения заголовка ответа сервера; +</listitem> + +<listitem> +timeout — произошёл таймаут во время соединения с сервером, +передачи ему запроса или чтения заголовка ответа сервера; +</listitem> + +<listitem> +invalid_header — сервер вернул пустой или неверный ответ; +</listitem> + +<listitem> +http_500 — сервер вернул ответ с кодом 500; +</listitem> + +<listitem> +http_503 — сервер вернул ответ с кодом 503; +</listitem> + +<listitem> +http_404 — сервер вернул ответ с кодом 404; +</listitem> + +<listitem> +off — запрещает передачу запроса следующему серверу; +</listitem> + +</list> +</para> + +<para> +Необходимо понимать, что передача запроса следующему серверу возможна +только при условии, что клиенту ещё ничего не передавалось. +То есть, если ошибка или таймаут возникли в середине передачи ответа, +то исправить это уже невозможно. +</para> + +</directive> + + +<directive name="fastcgi_param"> +<syntax>fastcgi_param <value>параметр значение</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт параметр, который будут передаваться FastCGI-серверу. +В качестве значения можно использовать текст, переменные и их комбинации. +Директивы наследуются с предыдущего уровня при условии, что на данном +уровне не описаны свои директивы fastcgi_param. +</para> + +<para> +Ниже приведён пример минимально необходимых параметров для PHP: +<example> +fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; +fastcgi_param QUERY_STRING $query_string; +</example> +</para> + +<para> +Параметр SCRIPT_FILENAME используется в PHP для определения имени скрипта, +а в параметре QUERY_STRING передаются параметры запроса. +</para> + +<para> +Если скрипты обрабатывают запросы POST, то нужны ещё три параметра: +<example> +fastcgi_param REQUEST_METHOD $request_method; +fastcgi_param CONTENT_TYPE $content_type; +fastcgi_param CONTENT_LENGTH $content_length; +</example> +</para> + +<para> +Если PHP был собран с параметром конфигурации +<command>--enable-force-cgi-redirect</command>, то нужно передавать +параметр REDIRECT_STATUS со значением "200": +<example> +fastcgi_param REDIRECT_STATUS 200; +</example> +</para> + +</directive> + + +<directive name="fastcgi_pass"> +<syntax>fastcgi_pass <value>fastcgi-server</value></syntax> +<default>нет</default> +<context>location, if в location</context> + +<para> +Директива задаёт адрес FastCGI-сервера. +Адрес может быть указан в виде доменного имени или адреса и порта, например, +<example> + fastcgi_pass localhost:9000; +</example> +или в виде пути unix сокета: +<example> + fastcgi_pass unix:/tmp/fastcgi.socket; +</example> +</para> + +<para> +Если доменное имя резолвится в несколько адресов, то все они будут +использоваться в режиме round-robin. +И кроме того, адрес может быть +<link doc="ngx_http_upstream.xml">группой серверов</link>. +</para> + +</directive> + + +<directive name="fastcgi_pass_header"> +<syntax>fastcgi_pass_header <value>имя</value></syntax> +<context>http, server, location</context> + +<para> +Директива разрешает передавать клиенту запрещённые для передачи строки. +</para> + +</directive> + + +<directive name="fastcgi_read_timeout"> +<syntax>fastcgi_read_timeout <value>время</value></syntax> +<default>fastcgi_read_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут при чтении ответа FastCGI-сервера. +Таймаут устанавливается не на всю передачу ответа, +а только между двумя операциями чтения. +Если по истечении этого времени FastCGI-сервер ничего не передаст, +то nginx закрывает соединение. +</para> + +</directive> + + +<directive name="fastcgi_redirect_errors"> +<syntax>fastcgi_redirect_errors <value>on|off</value></syntax> + +<para> +Директива переименована в <link id="fastcgi_intercept_errors"/>. +</para> + +</directive> + + +<directive name="fastcgi_send_timeout"> +<syntax>fastcgi_send_timeout <value>время</value></syntax> +<default>fastcgi_send_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут при передаче запроса FastCGI-серверу. +Таймаут устанавливается не на всю передачу запроса, +а только между двумя операциями записи. +Если по истечении этого времени FastCGI-сервер не примет новых данных, +то nginx закрывает соединение. +</para> + +</directive> + + +<directive name="fastcgi_split_path_info"> +<syntax>fastcgi_split_path_info <value>regex</value></syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива задаёт регулярное выражение, выделяющее +значение для переменной $fastcgi_path_info. +Регулярное выражение должно иметь два выделения, из которых первое +становиться значением переменной $fastcgi_script_name, +а второе — значением переменной $fastcgi_path_info. +Например, при таких настройках +<example> +location ~ ^(.+\.php)(.*)$ { + fastcgi_split_path_info ^(.+\.php)(.*)$; + fastcgi_param SCRIPT_FILENAME /path/to/php$fastcgi_script_name; + fastcgi_param PATH_INFO $fastcgi_path_info; +</example> +и запросе "/show.php/article/0001" параметр SCRIPT_FILENAME будет +равен "/path/to/php/show.php", а параметр PATH_INFO — "/article/0001". +</para> + +</directive> + + +<directive name="fastcgi_store"> +<syntax>fastcgi_store <value>on | off | строка </value></syntax> +<default>fastcgi_store off</default> +<context>http, server, location</context> + +<para> +Директива разрешает сохранение на диск файлов. +Параметр "on" сохраняет файлы в соответствии с путями, указаными в директивах +<link doc="ngx_http_core_module.xml#alias">alias</link> или +<link doc="ngx_http_core_module.xml#root">root</link>. +Параметр "off" запрещает сохранение файлов. +Кроме того, имя файла можно явно задать с помощью строки с переменными: +<example> +fastcgi_store /data/www$original_uri; +</example> +</para> + +<para> +Время модификации файлов выставляется согласно полученной строке +"Last-Modified" в заголовке ответа. +Ответ записывается во временный файл, а потом этот файл переименовывается. +Начиная с версии 0.8.9, временный файл и постоянное место хранения ответа +могут располагаться на разных файловых системах, но нужно учитывать, +что в этом случае вместо дешёвой операции переименовывания в пределах +одной файловой системы файл копируется с одной файловой системы на другую. +Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой +системе, что и каталог с временными файлами, задаваемый директивой +<link id="fastcgi_temp_path"/> для данного location. +</para> + +<para> +Директиву можно использовать для создания локальных копий статических +неизменяемых файлов, например: +<example> +location /images/ { + root /data/www; + open_file_cache_errors off; + error_page 404 = /fetch$uri; +} + +location /fetch/ { + internal; + + fastcgi_pass backend:9000; + ... + + fastcgi_store on; + fastcgi_store_access user:rw group:rw all:r; + fastcgi_temp_path /data/temp; + + alias /data/www/; +} +</example> +</para> + +</directive> + + +<directive name="fastcgi_store_access"> +<syntax>fastcgi_store_access <value>пользователи:права [пользователи:права] +...</value></syntax> +<default>fastcgi_store_access user:rw</default> +<context>http, server, location</context> + +<para> +Директива задаёт права доступа для создаваемых файлов и каталогов, например, +<example> +fastcgi_store_access user:rw group:rw all:r; +</example> +</para> + +<para> +Если заданы какие-либо права для groups или all, то права для user +указывать необязательно: +<example> +fastcgi_store_access group:rw all:r; +</example> +</para> + +</directive> + + +<directive name="fastcgi_temp_path"> +<syntax>fastcgi_temp_path <value>путь [ уровень1 [ уровень2 [ уровень3 ] ] ] +</value></syntax> +<default>fastcgi_temp_path fastcgi_temp</default> +<context>http, server, location</context> + +<para> +Директива задаёт имя каталога для хранения временных файлов +полученных от другого сервера. +В каталоге может использоваться иерархия подкаталогов до трёх уровней. +Например, при такой конфигурации +<example> +fastcgi_temp_path /spool/nginx/fastcgi_temp 1 2; +</example> +имя временного будет такого вида: +<example> +/spool/nginx/fastcgi_temp/7/45/00000123457 +</example> +</para> + +</directive> + +</section> + + +<section name="Параметры, передаваемые FastCGI-серверу" id="parameters"> + +<para> +Строки заголовка HTTP запроса передаются FastCGI-серверу в виде параметров. +В приложениях и скриптах, запущенных в виде FastCGI-сервера, +эти параметры обычно доступны в виде переменных среды. +Например, строка заголовка "User-Agent" передаётся как параметр +HTTP_USER_AGENT. +Кроме строк заголовка HTTP запроса, можно передавать произвольные параметры +с помощью директивы <link id="fastcgi_param"/>. +</para> + +</section> + + +<section name="Встроенные переменные" id="variables"> + +<para> +В модуле ngx_http_fastcgi_module есть встроенные переменные, +которые можно использовать для формирования параметров с помощью директивы +<link id="fastcgi_param"/>: +<list type="bullet"> + +<listitem> +<para> +$fastcgi_script_name, эта переменная равна URI запроса +или же, если URI заканчивается слэшом, то — URI запроса плюс имя +индексного файла, задаваемого директивой <link id="fastcgi_index"/>. +Эту переменную можно использовать для задания параметра SCRIPT_FILENAME +и PATH_TRANSLATED, используемых, в частности, для определения имени +скрипта в PHP. Например, для запроса "/info/" и при использовании директив +<example> +fastcgi_index index.php; +fastcgi_param SCRIPT_FILENAME /home/www/scripts/php$fastcgi_script_name; +</example> +параметр SCRIPT_FILENAME будут равен "/home/www/scripts/php/info/index.php". +</para> + +<para> +При использовании директивы <link id="fastcgi_split_path_info"/> +переменная $fastcgi_script_name равна значению первого выделения, +задаваемого этой директивой. +</para> +</listitem> + +<listitem> +$fastcgi_path_info, эта переменная равна значению второго выделения, +задаваемого директивой <link id="fastcgi_split_path_info"/>. +Эту переменную можно использовать для задания параметра PATH_INFO. +</listitem> + +</list> +</para> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_flv_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,53 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_flv_module" + link="/ru/docs/http/ngx_http_flv_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_flv_module делает специальную обработку передаваемых файлов: +при передаче файла, начиная со смещения, указаного в аргументах +запроса "start=XXX", добавляет FLV-заголовок перед запрашиваемым файлом. +</para> + +<para> +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром <command>--with-http_flv_module</command>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + location ~ \.flv$ { + flv; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="flv"> +<syntax>flv</syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива разрешает специальную обработку передаваемых файлов. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_geo_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,142 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_geo_module" + link="/ru/docs/http/ngx_http_geo_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_geo_module создаёт переменные, значения которых +зависят от IP-адреса клиента. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + geo $geo { + default 0; + 127.0.0.1/32 2; + 192.168.1.0/24 1; + 10.1.0.0/16 1; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="geo"> +<syntax>geo <value>[$адрес] $переменная { ... }</value> +</syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива geo описывает для указанной переменной зависимость значения от +IP-адреса клиента. +По умолчанию адрес берётся из переменной $remote_addr, но его также (0.7.27) +можно получить из другой переменной, например: +<example> + geo $arg_remote_addr $geo { + ...; + } +</example> +Если значение переменной не представляет из себя правильный IP-адрес, +то используется адрес "255.255.255.255". +</para> +<para> +Адреса задаются в виде CIDR или в виде диапазонов (0.7.23). +Кроме того, есть четыре специальных параметра: +<list type="bullet"> + +<listitem> +delete — удаляет описанную сеть (0.7.23). +</listitem> + +<listitem> +default — значение переменной, если адрес клиента не соответствует +ни одному заданному адресу. +При использовании CIDR вместо default можно также написать 0.0.0.0/0. +</listitem> + +<listitem> +include — включает файл с адресами и значениями. +Включений может быть несколько. +</listitem> + +<listitem> +proxy — задаёт адреса проски-серверов (0.8.7, 0.7.63), +при запросе с которых будет использоваться адрес в переданной +в строке заголовка запроса "X-Forwarded-For". +В отличие от обычных адресов, адреса прокси-серверов проверяются +последовательно. +</listitem> + +<listitem> +ranges — указывает, что адреса задаются в виде диапазонов (0.7.23). +Эта директива должны быть первой. +Для ускорения загрузки гео-базы нужно располагать адреса в порядке возрастания. +</listitem> + +</list> +</para> + +<para> +Пример описания: +<example> + geo $country { + default ZZ; + include conf/geo.conf; + delete 127.0.0.0/16; + proxy 192.168.100.0/24; + + 127.0.0.0/24 US; + 127.0.0.1/32 RU; + 10.1.0.0/16 RU; + 192.168.1.0/24 UK; + } +</example> +</para> + +<para> +В файле conf/geo.conf могут быть такие строки: +<example> +10.2.0.0/16 RU; +192.168.2.0/24 RU; +</example> +</para> + +<para> +В качестве значения выбирается максимальное совпадение, например, +для адреса 127.0.0.1 будет выбрано значение "RU", а не "US". +</para> + +<para> +Пример описания диапазонов: +<example> + geo $country { + ranges; + default ZZ; + 127.0.0.0-127.0.0.0 US; + 127.0.0.1-127.0.0.1 RU; + 127.0.0.1-127.0.0.255 US; + 10.1.0.0-10.1.255.255 RU; + 192.168.1.0-192.168.1.255 UK; + } +</example> +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_geoip_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,116 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_geoip_module" + link="/ru/docs/http/ngx_http_geoip_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_geoip_module создаёт переменные, значения которых +зависят от IP-адреса клиента, используя готовые базы +<link url="http://www.maxmind.com">MaxMind</link> (0.8.6+). +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром <command>--with-http_geoip_module</command>. +Для сборки и работы этого модуля нужна библиотека +<link url="http://www.maxmind.com/app/c">MaxMind GeoIP</link>. + +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +http { + geoip_country GeoIP.dat; + geoip_city GeoLiteCity.dat; + ... +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="geoip_country"> +<syntax>geoip_country <value>база</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива geoip_country указывает базу для определения страны в зависимости +от значения IP-адреса клиента. +При использовании этой базы доступны следующие переменные: +<list type="bullet"> + +<listitem> +$geoip_country_code; — двухбуквенный код страны, например, "RU", "US". +</listitem> + +<listitem> +$geoip_country_code3; — трёхбуквенный код страны, например, "RUS", "USA". +</listitem> + +<listitem> +$geoip_country_name; — название страны, например, "Russian Federation", +"United States". +</listitem> + +</list> +</para> + +</directive> + + +<directive name="geoip_city"> +<syntax>geoip_city <value>база</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива geoip_city указывает базу для определения страны, региона и города +в зависимости от значения IP-адреса клиента. +При использовании этой базы доступны следующие переменные: +<list type="bullet"> + +<listitem> +$geoip_city_country_code; — двухбуквенный код страны, например, "RU", "US". +</listitem> + +<listitem> +$geoip_city_country_code3; — трёхбуквенный код страны, например, +"RUS", "USA". +</listitem> + +<listitem> +$geoip_city_country_name; — название страны, например, "Russian Federation", +"United States". +</listitem> + +<listitem> +$geoip_region; — название региона страны (область, край, штат, +провинция, федеральная земля и тому подобное), например, "Moscow City", "DC". +</listitem> + +<listitem> +$geoip_city; — название города, например, "Moscow", "Washington". +</listitem> + +<listitem> +$geoip_postal_code; — почтовый индекс. +</listitem> + +</list> +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_gzip_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,215 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_gzip_module" + link="/ru/docs/http/ngx_http_gzip_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_gzip_module - это фильтр, сжимающий ответ методом gzip, +что позволяет уменьшить размер передаваемых данных в 2 и более раз. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + gzip on; + gzip_min_length 1000; + gzip_proxied expired no-cache no-store private auth; + gzip_types text/plain application/xml; +</example> +</para> + +<para> +Для записи в лог степени сжатия можно использовать переменную $gzip_ratio. +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="gzip"> +<syntax>gzip <value>on|off</value></syntax> +<default>gzip off</default> +<context>http, server, location, if в location</context> + +<para> +Разрешает или запрещает сжатие ответа методом gzip. +</para> + +</directive> + + +<directive name="gzip_buffers"> +<syntax>gzip_buffers <value>число размер</value></syntax> +<default>gzip_buffers 32 4k/16 8k</default> +<context>http, server, location</context> + +<para> +Директива задаёт число и размер буферов, в которые будет сжиматься ответ. +По умолчанию размер одного буфера равен размеру страницы, в зависимости +от платформы это или 4K, или 8K. +До версии 0.7.28 по умолчанию использовалось 4 буфера размером 4K или 8K. +</para> + +</directive> + + +<directive name="gzip_comp_level"> + +<syntax>gzip_comp_level <value>1..9</value></syntax> +<default>gzip_comp_level 1</default> +<context>http, server, location</context> + +<para> +Устанавливает уровень сжатия ответа методом gzip. +</para> + +</directive> + + +<directive name="gzip_disable"> +<syntax>gzip_disable <value>regex [regex ...]</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива (0.6.23) запрещает сжатие ответа методом gzip для запросов +со строками "User-Agent", совпадающими с заданными регулярными выражениями. +</para> + +<para> +Специальная маска "msie6" (0.7.12) соответствует +регулярному выражению "MSIE [4-6]\.", но работает быстрее. +Начиная с версии 0.8.11, из этой маски исключается "MSIE 6.0; ... SV1". +</para> + +</directive> + + +<directive name="gzip_min_length"> +<syntax>gzip_min_length <value>длина</value></syntax> +<default>gzip_min_length 20</default> +<context>http, server, location</context> + +<para> +Устанавливает минимальную длину ответа, для которых +будет выполняться сжатие ответа методом gzip. +Длина определяется только из строки "Content-Length" заголовка ответа. +</para> + +</directive> + + +<directive name="gzip_http_version"> +<syntax>gzip_http_version <value>1.0|1.1</value></syntax> +<default>gzip_http_version 1.1</default> +<context>http, server, location</context> + +<para> +Устанавливает минимальную версию HTTP запроса для сжатия ответа. +</para> + +</directive> + + +<directive name="gzip_proxied"> +<syntax>gzip_proxied <value>[off|expired|no-cache|no-store|private|no_last_modified|no_etag|auth|any] ...</value></syntax> +<default>gzip_proxied off</default> +<context>http, server, location</context> + +<para> +Разрешает или запрещает сжатие ответа методом gzip для проксированных +запросов в зависимости от запроса и ответа. +То что, запрос проксированный, определяется на основании строки "Via" +в заголовке запроса. +В директиве можно указать одновременно несколько паарметров: +<list type="bullet"> + +<listitem> +off — запрещает сжатие для всех проксированных запросов, +игнорируя остальные параметры; +</listitem> + +<listitem> +expired — разрешить сжатие, если в ответе есть +строка "Expires" со значением, запрещающим кэширование; +</listitem> + +<listitem> +no-cache — разрешить сжатие, если в ответе есть +строка "Cache-Control" с параметром "no-cache"; +</listitem> + +<listitem> +no-store — разрешить сжатие, если в ответе есть +строка "Cache-Control" с параметром "no-store"; +</listitem> + +<listitem> +private — разрешить сжатие, если в ответе есть +строка "Cache-Control" с параметром "private"; +</listitem> + +<listitem> +no_last_modified — разрешить сжатие, если в ответе нет +строки "Last-Modified"; +</listitem> + +<listitem> +no_etag — разрешить сжатие, если в ответе нет строки "ETag"; +</listitem> + +<listitem> +auth — разрешить сжатие, если в запросе есть строка "Authorization"; +</listitem> + +<listitem> +any — разрешить сжатие для всех проксированных запросов; +</listitem> + +</list> +</para> + +</directive> + + +<directive name="gzip_types"> +<syntax>gzip_types <value>mime-тип [mime-тип ...]</value></syntax> +<default>gzip_types text/html</default> +<context>http, server, location</context> + +<para> +Разрешает сжатие ответа методом gzip для указанных MIME-типов в дополнение +к "text/html". "text/html" сжимается всегда. +</para> + +</directive> + + +<directive name="gzip_vary"> +<syntax>gzip_vary <value>on|off</value></syntax> +<default>gzip_vary off</default> +<context>http, server, location</context> + +<para> +Разрешает или запрещает выдавать в ответе строку заголовка +"Vary: Accept-Encoding", если директивы +<link id="gzip"/> или +<link doc="ngx_http_gzip_static_module.xml#gzip_static">gzip_static</link> +активны. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_gzip_static_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,62 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_gzip_static_module" + link="/ru/docs/http/ngx_http_gzip_static_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_gzip_static_module позволяет отдавать +вместо обычного файла предварительно сжатый файл с таким же именем +и с суффиксом ".gz". +</para> + +<para> +По умолчанию модуль не собирается, нужно разрешить его сборку при +конфигурировании параметром <command>--with-http_gzip_static_module</command>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + gzip_static on; + gzip_proxied expired no-cache no-store private auth; +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="gzip_static"> +<syntax>gzip_static <value>on|off</value></syntax> +<default>gzip_static off</default> +<context>http, server, location</context> + +<para> +Разрешает или запрещает проверку готового сжатого файла. +При использовании также учитываются директивы +<link doc="ngx_http_gzip_module.xml#gzip_http_version">gzip_http_version</link>, +<link doc="ngx_http_gzip_module.xml#gzip_proxied">gzip_proxied</link>, +<link doc="ngx_http_gzip_module.xml#gzip_disable">gzip_disable</link> +и <link doc="ngx_http_gzip_module.xml#gzip_vary">gzip_vary</link>. +</para> + +<para> +Сжимать файлы можно с помощью программы gzip или совместимой с ней. +Желательно, чтобы время модификации исходного и сжатого файлов совпадали. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_headers_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,109 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_headers_module" + link="/ru/docs/http/ngx_http_headers_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_headers_module позволяет выдавать строки "Expires" +и "Cache-Control" и добавлять произвольные строки в заголовке ответа. +</para> + +</section> + +<section name="Примеры конфигурации" id="example"> + +<para> +<example> + expires 24h; + expires modified +24h; + expires @24h; + expires 0; + expires -1; + expires epoch; + add_header Cache-Control private; +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="add_header"> +<syntax>add_header <value>название значение</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива добавляет строку в заголовке ответа при условии, что код ответа +равен 200, 204, 301, 302 или 304. +В значении можно использовать переменные. +</para> + +</directive> + + +<directive name="expires"> +<syntax>expires <value>[modified]</value> <value>[время|epoch|max|off]</value></syntax> +<default>expires off</default> +<context>http, server, location</context> + +<para> +Разрешает или запрещает добавлять или менять строки "Expires" +и "Cache-Control" в заголовке ответа. +В качестве параметра можно задать положительное или отрицательное +<link doc="../syntax.xml">время</link>. +</para> + +<para> +Время в строке "Expires" получается как сумма текущего времени +и времени, заданного в директиве. +Если используется параметр "modified" (0.7.0, 0.6.32), +то время получается как сумма +времени модификации файла и времени, заданного в директиве. +</para> + +<para> +Кроме того, с помощью префикса "@" можно задать время суток (0.7.9, 0.6.34): +<example> +expires @15h30m; +</example> +</para> + +<para> +Параметр "epoch" означает абсолютное время 1 января 1970 года 00:00:01 GMT. +Содержимое строки "Cache-Control" зависит от знака заданного времени: +<list type="bullet"> + +<listitem> +отрицательное время — "Cache-Control: no-cache". +</listitem> + +<listitem> +положительное время или равное нулю — "Cache-Control: max-age=#", +где "#" - это время в секундах, заданное в директиве. +</listitem> + +</list> +</para> + +<para> +Параметр "max" задаёт время 31 декабря 2037 23:55:55 GMT для строки "Expires" +и 10 лет для строки "Cache-Control". +</para> + +<para> +Параметр "off" запрещает добавлять или менять строки "Expires" +и "Cache-Control" в заголовке ответа. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_image_filter_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,135 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_image_filter_module" + link="/ru/docs/http/ngx_http_image_filter_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_image_filter_module — это фильтр для преобразования +изображений в форматах JPEG, GIF и PNG (0.7.54+). +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром +<command>--with-http_image_filter_module</command>. +Для сборки и работы этого модуля нужна библиотека +<link url="http://libgd.org">libgd</link>. +Рекомендуется использовать самую последнию версию библиотеки, +на текущий момент (май 2009) это версия 2.0.35. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +location /img/ { + proxy_pass http://backend; + image_filter resize 150 100; + error_page 415 = /empty; +} + +location = /empty { + empty_gif; +} +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="image_filter"> +<syntax>image_filter <value>(test|size|resize ширина высота|crop ширина высота) +</value></syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива задаёт тип преобразования изображения: +<list type="bullet"> + +<listitem> +test — проверка того, что ответ действительно является изображением +в формате JPEG, GIF или PNG. В противном случае выдаётся ошибка 415. +</listitem> + +<listitem> +size — выдаёт информацию об изображении в формате JSON, например: +<example> +{ "img" : { "width": 100, "height": 100, "type": "gif" } } +</example> +В случае ошибки выдаётся +<example> +{} +</example> +</listitem> + +<listitem> +resize — пропорционально уменьшает изображение до указанных размеров. +Если нужно уменьшить только по одному измерению, то в качестве второго +можно указать "-". +В случае ошибки выдаётся код 415. +</listitem> + +<listitem> +crop — пропорционально уменьшает изображение до размера большой стороны +и обрезает лишние края по другой стороне. +Если нужно уменьшить только по одному измерению, то в качестве второго +можно указать "-". +В случае ошибки выдаётся код 415. +</listitem> + +</list> +</para> + +</directive> + + +<directive name="image_filter_buffer"> +<syntax>image_filter_buffer <value>размер</value></syntax> +<default>image_filter_buffer 1M</default> +<context>http, server, location</context> + +<para> +Директива задаёт максимальный размер буфера для чтения изображения. +</para> + +</directive> + + +<directive name="image_filter_jpeg_quality"> +<syntax>image_filter_jpeg_quality <value>[0..100]</value></syntax> +<default>image_filter_jpeg_quality 75</default> +<context>http, server, location</context> + +<para> +Директива задаёт коэффициент потери информации при обработке изображений +в формате JPEG. Максимальное рекомендуемое значение — 95. +</para> + +</directive> + + +<directive name="image_filter_transparency"> +<syntax>image_filter_transparency <value>[on|off]</value></syntax> +<default>image_filter_transparency on</default> +<context>http, server, location</context> + +<para> +Директива определяет, сохранять ли прозрачность при обработке изображений +в формате PNG с цветами, заданными палитрой, и формате GIF. +Потеря прозрачности позволяет получить более качественное изображение. +Прозрачность альфа-канала в формате PNG сохраняется всегда. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_index_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,70 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_index_module" + link="/ru/docs/http/ngx_http_index_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_index_module обслуживает запросы, оканчивающиеся слэшом. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + location / { + index index.$geo.html index.html; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="index"> +<syntax>index <value>файл [файл ...]</value> +</syntax> +<default>index index.html</default> +<context>http, server, location</context> + +<para> +Директива определяет файлы, которые будут использоваться в качестве индекса. +В имени файла можно использовать переменные. +Наличие файлов проверяется в порядке их перечисления. +В конце списка может стоять файл с абсолютным путём. +Пример использования: +<example> + index index.$geo.html index.0.html /index.html; +</example> +</para> + +<para> +Необходимо иметь ввиду, что при использовании индексного файла делается +внутренний редирект и запрос может быть обработан уже в другом location'е. +Например, запрос "/" будет фактически обработан во втором location'е +как "/index.html" в такой конфигурации: +<example> + location = / { + index index.html; + } + + location / { + ... + } +</example> +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_limit_req_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,138 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_limit_req_module" + link="/ru/docs/http/ngx_http_limit_req_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_limit_req_module (0.7.21) позволяет ограничить число запросов +для заданной сессии или, как частный случай, с одного адреса. +Ограничение делается с помощью метода leaky bucket. +</para> + +</section> + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +http { + limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; + + ... + + server { + + ... + + location /search/ { + limit_req zone=one burst=5; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="limit_req_zone"> +<syntax>limit_req_zone <value>$переменная zone=название:размер + rate=скорость</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива описывает зону, в которой хранятся состояния сессий. +Значения сессий определяется заданной переменной. +Пример использования: +<example> +limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; +</example> +</para> + +<para> +В данном случае состояния сессий хранятся в зоне "one" размером 10 мегабайт +и средняя скорость запросов для этой зоны не может более 1 запроса в секунду. +</para> + +<para> +В качестве сессии используется адрес клиента. +Обратите внимание, что вместо переменной $remote_addr используется +переменная $binary_remote_addr, позволяющая уменьшить размер состояния +до 64 байт. +В зоне размером 1 мегабайт может разместиться около 16 000 состояний +размером 64 байта. +</para> + +<para> +Скорость задаётся в запросах в секунду. +Если же нужна скорость меньше одного запроса в секунду, +то она задаётся в запросах в минуту, например, +ползапроса в секунду — это 30r/m. +</para> + +</directive> + +<directive name="limit_req"> +<syntax>limit_req <value>zone=название burst=число [nodelay]</value> +</syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт зону (zone) и максимально возможные всплески запросов (burst). +Если скорость запросов превышает описанную в зоне, +то их обработка запроса задерживается так, чтобы запросы обрабывались +с заданной скоростью. +Избыточные запросы задерживаются до тех пор, пока их число +не превысит заданное число всплесков. +В этом случае запрос завершается кодом "Service unavailable" (503). +По умолчанию число всплесков равно нулю. +Например, директивы +<example> +limit_req_zone $binary_remote_addr zone=one:10m rate=1r/s; + + server { + location /search/ { + limit_req zone=one burst=5; + } + +</example> +позволяют в среднем не более 1 запроса в секунду +со всплесками не более 5 запросов. +</para> + +<para> +Если же избыточные запросы в пределах лимита всплесков задерживать +не надо, то нужно использовать параметр nodelay: +<example> + limit_req zone=one burst=5 nodelay; +</example> +</para> + +</directive> + + +<directive name="limit_req_log_level"> +<syntax>limit_req_log_level <value>[info|notice|warn|error]</value></syntax> +<default>limit_req_log_level error</default> +<context>http, server, location</context> + +<para> +Директива (0.8.18) задаёт уровень логирования случаев ограничения +числа запросов и задержек при обработке запроса. +Задержки логируются на один уровень ниже, чем ограничения, например, +если задан "limit_req_log_level notice", то задержки будут логироваться +на уровне info. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_limit_zone_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,110 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_limit_zone_module" + link="/ru/docs/http/ngx_http_limit_zone_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_limit_zone_module позволяет ограничить число одновременных +соединений для заданной сессии или, как частный случай, с одного адреса. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +http { + limit_zone one $binary_remote_addr 10m; + + ... + + server { + + ... + + location /download/ { + limit_conn one 1; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="limit_zone"> +<syntax>limit_zone <value>название $переменная размер</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива описывает зону, в которой хранятся состояния сессий. +Значения сессий определяется заданной переменной. +Пример использования: +<example> +limit_zone one $binary_remote_addr 10m; +</example> +</para> + +<para> +В качестве сессии используется адрес клиента. +Обратите внимание, что вместо переменной $remote_addr используется +переменная $binary_remote_addr. +Длина значений переменной $remote_addr может быть от 7 до 15 байт, +поэтому размер состоянии равен 32 или 64 байтам. +Длина всех значений переменной $binary_remote_addr всегда 4 байта +и размер состояния всегда 32 байта. +В зоне размером 1 мегабайт может разместиться около 32 000 состояний +размером 32 байта. +</para> + +</directive> + + +<directive name="limit_conn"> +<syntax>limit_conn <value>зона число</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт максимальное число одновременных соединений для одной сессии. +При превышении этого числа запрос завершается кодом "Service unavailable" (503). +Например, директивы +<example> +limit_zone one $binary_remote_addr 10m; + + server { + location /download/ { + limit_conn one 1; + } + +</example> +позволяют не более одного одновременного соединения с одного адреса. +</para> + +</directive> + + +<directive name="limit_conn_log_level"> +<syntax>limit_conn_log_level <value>[info|notice|warn|error]</value></syntax> +<default>limit_conn_log_level error</default> +<context>http, server, location</context> + +<para> +Директива (0.8.18) задаёт уровень логирования случаев ограничения +числа соединений. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_log_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,226 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_log_module" + link="/ru/docs/http/ngx_http_log_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_log_module записывает логи запросов в указанном формате. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + log_format gzip '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $bytes_sent ' + '"$http_referer" "$http_user_agent" "$gzip_ratio"'; + + access_log /spool/logs/nginx-access.log gzip buffer=32k; +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="access_log"> +<syntax>access_log <value>путь [формат [buffer=размер]]|off</value> +</syntax> +<default>access_log log/access.log combined</default> +<context>http, server, location, if в location, limit_except</context> + +<para> +Директива access_log задаёт путь, формат и размер буфера для буферизированной +записи в лог. На одном уровне может использоваться несколько логов. +Параметр "off" отменяет все директивы access_log для текущего уровня. +Если формат не указан, то используется предопределённый формат "combined". +</para> + +<para> +Размер буфера должен быть не больше размера атомарной записи в дисковый файл. +Для FreeBSD 3.0-6.0 этот размер неограничен. +</para> + +<para> +В пути файла можно использовать переменные (0.7.6+), +но такие логи имеют некоторые ограничения: +<list type="bullet"> + +<listitem> +пользователь, с правами которого работают рабочие процессы, должен +иметь права на создание файлов в каталоге с такими логами; +</listitem> + +<listitem> +не работает буферизация; +</listitem> + +<listitem> +файл открывается для каждой записи в лог и сразу же после записи закрывается. +Но дескрипторы часто используемых файлов могут храниться в +<link id="open_log_file_cache"/>. +При вращении логов нужно иметь в виду, что в течение времени, заданного +параметром valid директивы <link id="open_log_file_cache"/>, +запись может продолжаться в старый файл. +</listitem> + +<listitem> +при каждой записи в лог проверяется существование каталога root'а для +запроса — если этот каталог не существует, то лог не создаётся. +Поэтому <link doc="ngx_http_core_module.xml#root">root</link> +и access_log нужно описывать на одном уровне: +<example> +server { + root /spool/vhost/data/$host; + access_log /spool/vhost/logs/$host; + ... +</example> +</listitem> + +</list> +</para> + +</directive> + + +<directive name="log_format"> +<syntax>log_format <value>название строка [строка ...]</value> +</syntax> +<default>log_format combined "..." </default> +<context>http</context> + +<para> +Директива log_format описывает формат лога. +</para> + +<para> +Кроме общих переменных в формате можно использовать переменные, +существующие только на момент записи в лог: +<list type="bullet"> + +<listitem> +$body_bytes_sent, число байт, переданное клиенту за вычетом заголовка ответа, +переменная совместима с параметром %B модуля Apache mod_log_config; +</listitem> + +<listitem> +$bytes_sent, число байт, переданное клиенту; +</listitem> + +<listitem> +$connection, номер соединения; +</listitem> + +<listitem> +$msec, время в секундах с точностью до миллисекунд на момент записи в лог; +</listitem> + +<listitem> +$pipe, "p" если запрос был pipelined; +</listitem> + +<listitem> +$request_length, длина тела запроса; +</listitem> + +<listitem> +$request_time, время обработки запроса в секундах с точностью до миллисекунд; +</listitem> + +<listitem> +$status, статус ответа; +</listitem> + +<listitem> +$time_local, локальное время в common log format. +</listitem> + +</list> +</para> + +<para> +Строки заголовка, переданные клиенту, начинаются с префикса "sent_http_", +например, $sent_http_content_range. +</para> + +<para> +В конфигурации всегда существует предопределённый формат "combined": +<example> + log_format combined '$remote_addr - $remote_user [$time_local] ' + '"$request" $status $body_bytes_sent ' + '"$http_referer" "$http_user_agent"'; +</example> +</para> + +</directive> + +<directive name="open_log_file_cache"> + +<syntax>open_log_file_cache <value>max=N [inactive=время]|off</value> +</syntax> +<default>open_log_file_cache off</default> +<context>http, server, location</context> + +<para> +Директива задаёт кэш, в котором хранятся дескрипторы файлов часто используемых +логов, имена которых заданы переменными. +</para> + +<para> +Параметры директивы: +<list type="bullet"> + +<listitem> +max — задаёт маскимальное число дескрипторов в кэше; +при переполнении кэша наиболее давно не используемые дескрипторы закрываются +(LRU); +</listitem> + +<listitem> +inactive — задаёт время, после которого дескриптор кэша закрывается, +если к нему не было обращений в течение этого времени; +по умолчанию 10 секунд; +</listitem> + +<listitem> +min_uses — задаёт минимальное число использований файла в течение +времени, заданного параметром inactive в директиве +<link id="open_log_file_cache"/>, после которого дескриптор файла +будет оставаться окрытым в кэше; +по умолчанию 1 использование; +</listitem> + +<listitem> +valid — задаёт, через какое время нужно проверять, что файл ещё +существует под тем же именем; +по умолчанию 60 секунд; +</listitem> + +<listitem> +off — запрещает кэш. +</listitem> + +</list> +</para> + +<para> +Пример использования: +<example> +open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2; +</example> +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_map_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,117 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_map_module" + link="/ru/docs/http/ngx_http_map_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_map_module создаёт переменные, значение которых +зависят от значения других переменных. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + map $http_host $name { + hostnames; + + default 0; + + example.com 1; + *.example.com 1; + test.com 2; + *.test.com 2; + .site.com 3; + wap.* 4; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="map"> +<syntax>map <value>$переменная1 $переменная2 { ... }</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива создаёт переменную, значение которой +зависит от значения исходной переменной. +Директива поддерживает три специальных параметра: +<list type="bullet"> +<listitem> +default — задаёт значение для второй переменной, если значение +первой переменной не найдено. +</listitem> + +<listitem> +hostnames — указывает, что в качестве исходных значений можно +использовать маску для первой или последней части имени хоста, например, +<example> +*.example.com 1; +example.* 1; +</example> +Вместо двух записей +<example> +example.com 1; +*.example.com 1; +</example> +можно использовать одну +<example> +.example.com 1; +</example> +</listitem> + +<listitem> +include — включает файл со значениями. +Включений может быть несколько. +</listitem> + +</list> +</para> + +</directive> + + +<directive name="map_hash_max_size"> +<syntax>map_hash_max_size <value>число</value></syntax> +<default>map_hash_max_size 2048</default> +<context>http</context> + +<para> +Директива задаёт максимальный размер хэш-таблиц для переменных map. +Подробнее смотри в <link doc="../hash.xml">описании +настройки хэшей</link>. +</para> + +</directive> + + +<directive name="map_hash_bucket_size"> +<syntax>map_hash_bucket_size <value>число</value></syntax> +<default>map_hash_bucket_size 32/64/128</default> +<context>http</context> + +<para> +Директива задаёт размер корзины в хэш-таблицах для переменных map. +Значение по умолчанию зависит от размера строки кэша процессора. +Подробнее смотри в <link doc="../hash.xml">описании +настройки хэшей</link>. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_memcached_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,174 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_memcached_module" + link="/ru/docs/http/ngx_http_memcached_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_memcached_module позволяет получать ответ из сервера memcached. +Ключ задаётся в переменной $memcached_key. +Ответ в memcached должен быть предварительно помещён внешним по отношению +к nginx'у способом. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +server { + location / { + set $memcached_key "$uri?$args"; + memcached_pass host:11211; + error_page 404 502 504 = @fallback; + } + + location @fallback { + proxy_pass http://backend; + } +} +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="memcached_buffer_size"> +<syntax>memcached_buffer_size <value>размер</value></syntax> +<default>memcached_buffer_size 4k/8k</default> +<context>http, server, location</context> + +<para> +Директива задаёт размер буфера, в который будет читаться ответ, +получаемый от cервера memcached. +Ответ синхронно передаётся клиенту сразу же по мере его поступления. +</para> + +</directive> + + +<directive name="memcached_connect_timeout"> +<syntax>memcached_connect_timeout <value>время</value></syntax> +<default>memcached_connect_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут для соединения с cервером memcached. +Необходимо иметь в виду, что этот таймаут не может быть больше 75 секунд. +</para> + +</directive> + + +<directive name="memcached_next_upstream"> +<syntax>memcached_next_upstream +<value>[error|timeout|invalid_response|not_found|off]</value> +</syntax> +<default>memcached_next_upstream error timeout</default> +<context>http, server, location</context> + +<para> +Директива определяет, в каких случаях запрос будет передан следующему +серверу memcached: +<list type="bullet"> + +<listitem> +error — произшла ошибка соединения с сервером, передачи ему запроса или +чтения заголовка ответа сервера; +</listitem> + +<listitem> +timeout — произошёл таймаут во время соединения с сервером, +передачи ему запроса или чтения заголовка ответа сервера; +</listitem> + +<listitem> +invalid_response — сервер вернул пустой или неверный ответ; +</listitem> + +<listitem> +not_found — сервер не нашёл ответ; +</listitem> + +<listitem> +off — запрещает передачу запроса следующему серверу; +</listitem> + +</list> +</para> + +<para> +Необходимо понимать, что передача запроса следующему серверу возможна +только при условии, что клиенту ещё ничего не передавалось. +То есть, если ошибка или таймаут возникли в середине передачи ответа, +то исправить это уже невозможно. +</para> + +</directive> + + +<directive name="memcached_pass"> +<syntax>memcached_pass <value>URL</value></syntax> +<default>нет</default> +<context>location, if в location, limit_except</context> + +<para> +Директива задаёт адрес сервера memcached. +Адрес может быть указан в виде доменного имени или адреса и порта: +<example> + memcached_pass localhost:11211; +</example> +</para> + +<para> +Если доменное имя резолвится в несколько адресов, то все они будут +использоваться в режиме round-robin. +И кроме того, адрес может быть +<link doc="ngx_http_upstream.xml">группой серверов</link>. +</para> + +</directive> + + +<directive name="memcached_read_timeout"> +<syntax>memcached_read_timeout <value>время</value></syntax> +<default>memcached_read_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут при чтении ответа сервера memcached. +Таймаут устанавливается не на всю передачу ответа, +а только между двумя операциями чтения. +Если по истечении этого времени сервер ничего не передаст, +то nginx закрывает соединение. +</para> + +</directive> + + +<directive name="memcached_send_timeout"> +<syntax>memcached_send_timeout <value>время</value></syntax> +<default>memcached_send_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут при передаче запроса серверу memcached. +Таймаут устанавливается не на всю передачу запроса, +а только между двумя операциями записи. +Если по истечении этого времени сервер не примет новых данных, +то nginx закрывает соединение. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_perl_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,466 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_perl_module" + link="/ru/docs/http/ngx_http_perl_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_perl_module позволяет работать со встроенным в nginx perl'ом: +делать обработчики location и переменной и вставлять вызовы perl'а в SSI. +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром <command>--with-http_perl_module</command>. +Для сборки необходим perl версии 5.6.1 и выше, и компилятор C, совместимый +с тем, которым был собран perl. +</para> + +</section> + + +<section name="Известные проблемы" id="bugs"> + +<para> +Модуль экспериментальный, поэтому возможно всё. +</para> + +<para> +Для того, чтобы во время переконфигурации perl перекомпилировал +изменённые модули, его нужно собрать с параметрами -Dusemultiplicity=yes +или -Dusethreads=yes. +Кроме того, чтобы во время работы perl меньше терял память, его нужно собрать +с параметром -Dusemymalloc=no. +Узнать значения этих параметров у уже собранного +perl'а можно так (в примерах приведены желаемые значения параметров): +<example> +$perl -V:usemultiplicity +usemultiplicity='define'; + +$perl -V:usemymalloc +usemymalloc='n'; +</example> +</para> + +<para> +Необходимо учитывать, что после пересборки perl'а с новыми параметрами +-Dusemultiplicity=yes или -Dusethreads=yes +придётся также переустановить и все бинарные perl'овые модули — они +просто перестанут работать с новым perl'ом. +</para> + +<para> +Возможно, основной процесс, а вслед за ним и рабочие процессы, +будет увеличиваться в размерах при каждой переконфигурации. +Когда основной процесс вырастет до неприемлемых размеров, можно +воспользоваться процедурой +<link doc="../control.html#upgrade">обновления сервера на лету</link>, +не меняя при этом сам исполняемый файл. +</para> + +<para> +Если perl'овый модуль выполняет длительную операцию, например, определяет +адрес по имени, соединяется с другим сервером, делает запрос к базе данных, +то на это время все остальные запросы данного рабочего процесса не будут +обрабатываться. Поэтому рекомендуется ограничиться операциями, +время исполнения которых короткое и предсказуемое, например, обращение +к локальной файловой системе. +</para> + +<para> +<note> + +<para> +Нижеописанные проблемы отностятся только к версиям nignx'а до 0.6.22. +</para> + +<para> +Данные, возвращаемые методами объекта запроса $r, +имеют только текстовое значение, причём само значение хранится +в памяти, выделяемой не perl'ом, а nginx'ом из собственных пулов. +Это позволяет уменьшить число операций копирования в большинстве случаев, +однако в некоторых ситуациях это приводит к ошибке, +например, при попытке использования таких значений в численном контексте +рабочий процесс выходит с ошибкой (FreeBSD): +<example> +nginx in realloc(): warning: pointer to wrong page +Out of memory! +Callback called exit. +</example> +или (Linux): +<example> +*** glibc detected *** realloc(): invalid pointer: ... *** +Out of memory! +Callback called exit. +</example> +Обход такой ситуации простой — нужно присвоить значение метода +переменной, например, такой код +<example> +my $i = $r->variable('counter') + 1; +</example> +нужно заменить на +<example> +my $i = $r->variable('counter'); +$i++; +</example> +</para> + +<para> +Так как строки внутри nginx'а в большинстве случаев хранятся без +завершающего нуля, то они в таком же виде возвращаются методами +объекта запроса $r (исключения составляют методы $r->filename +и $r->request_body_file). Поэтому такие значения нельзя использовать +в качестве имени файла и тому подобном. +Обход такой же, как и предыдущей ситуации — присвоение значения +переменной (при этом происходит копирование данных и добавление необходимого +нуля) или же использование в выражении, например: +<example> +open FILE, '/path/' . $r->variable('name'); +</example> + +</para> + +</note> +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +http { + + perl_modules perl/lib; + perl_require hello.pm; + + perl_set $msie6 ' + + sub { + my $r = shift; + my $ua = $r->header_in("User-Agent"); + + return "" if $ua =~ /Opera/; + return "1" if $ua =~ / MSIE [6-9]\.\d+/; + return ""; + } + + '; + + server { + location / { + perl hello::handler; + } + } +</example> +</para> + +<para> +модуль perl/lib/hello.pm: +<example> +package hello; + +use nginx; + +sub handler { + my $r = shift; + + $r->send_http_header("text/html"); + return OK if $r->header_only; + + $r->print("hello!\n<br/>"); + + if (-f $r->filename or -d _) { + $r->print($r->uri, " exists!\n"); + } + + return OK; +} + +1; +__END__ + +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="perl"> +<syntax>perl <value>модуль::функция|'sub { ... }'</value></syntax> +<default>нет</default> +<context>location, limit_except</context> + +<para> +Директива устанавливает обработчик для данного location. +</para> + +</directive> + + +<directive name="perl_modules"> +<syntax>perl_modules <value>путь</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива задаёт дополнительный путь для perl'овых модулей. +</para> + +</directive> + + +<directive name="perl_require"> +<syntax>perl_require <value>модуль</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива задаёт имя модуля, который будет подгружаться при каждой +переконфигурации. Директив может быть несколько. +</para> + +</directive> + + +<directive name="perl_set"> +<syntax>perl_set <value>$переменная</value> + <value>модуль::функция|'sub { ... }'</value> +</syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива устанавливает обработчик переменной. +</para> + +</directive> + +</section> + + +<section name="Вызов perl'а из SSI" id="ssi"> + +<para> +Формат команды следующий: +<example> +<!--# perl sub="модуль::функция" arg="параметр1" arg="параметр2" ... +--> +</example> +</para> + +</section> + + +<section name="Методы объекта запроса $r" id="methods"> + +<para> +<list type="bullet"> + +<listitem> +<emphasis>$r->args</emphasis> — метод возвращает аргументы запроса. +</listitem> + +<listitem> +<emphasis>$r->filename</emphasis> — метод возвращает имя файла, +соответствующее URI запроса. +</listitem> + +<listitem> +<emphasis>$r->has_request_body(обработчик)</emphasis> — метод возвращает 0, +если в запросе нет тела. Если же тело запроса есть, то устанавливается +указанный обработчик и возвращается 1. +По окончании приёма тела nginx вызовет установленный обработчик. +Обратите внимание, что нужно передавать ссылку на функцию обработчика. +Пример использования: +<example> +package hello; + +use nginx; + +sub handler { + my $r = shift; + + if ($r->request_method ne "POST") { + return DECLINED; + } + + if ($r->has_request_body(<emphasis>\&post</emphasis>)) { + return OK; + } + + return HTTP_BAD_REQUEST; +} + +sub <emphasis>post</emphasis> { + my $r = shift; + + $r->send_http_header; + + $r->print("request_body: \"", $r->request_body, "\"<br/>"); + $r->print("request_body_file: \"", $r->request_body_file, "\"<br/>\n"); + + return OK; +} + +1; + +__END__ +</example> +</listitem> + +<listitem> +<emphasis>$r->allow_ranges</emphasis> — метод разрешает использовать +byte ranges при передаче ответа. +</listitem> + +<listitem> +<emphasis>$r->discard_request_body</emphasis> — метод указывает nginx'у +игнорировать тело запроса. +</listitem> + +<listitem> +<emphasis>$r->header_in(строка)</emphasis> — метод возвращает значение +заданной строки в заголовке запроса клиента. +</listitem> + +<listitem> +<emphasis>$r->header_only</emphasis> — метод определяет, нужно ли передавать +клиенту только заголовок ответа или весь ответ. +</listitem> + +<listitem> +<emphasis>$r->header_out(строка, значение)</emphasis> — метод устанавливает +значение для заданной строки в заголовке ответа. +</listitem> + +<listitem> +<emphasis>$r->internal_redirect(uri)</emphasis> — метод делает внутренний +редирект на указанный uri. +Редирект происходит уже после завершения perl'ового обработчика. +</listitem> + +<listitem> +<emphasis>$r->print(текст, ...)</emphasis> — метод передаёт клиенту данные. +</listitem> + +<listitem> +<emphasis>$r->request_body</emphasis> — метод возвращает тело запроса +клиента при условии, что тело не записано во временный файл. +Для того, чтобы тело запроса клиента гарантировано находилось в памяти, +нужно ограничить его размер с помощью <link doc="ngx_http_core_module.xml#client_max_body_size">client_max_body_size</link> +и задать достаточной размер для буфера +<link doc="ngx_http_core_module.xml#client_body_buffer_size">client_body_buffer_size</link>. +</listitem> + +<listitem> +<emphasis>$r->request_body_file</emphasis> — метод возвращает имя файла, +в котором хранится тело запроса клиента. +По завершению работы файл необходимо удалить. +Для того, чтобы тело запроса клиента всегда записывалось в файл, нужно +указать <link doc="ngx_http_core_module.xml#client_body_in_file_only">client_body_in_file_only on</link>. +</listitem> + +<listitem> +<emphasis>$r->request_method</emphasis> — метод возвращает HTTP метод +запроса клиента. +</listitem> + +<listitem> +<emphasis>$r->remote_addr</emphasis> — метод возвращает IP-адрес клиента. +</listitem> + +<listitem> +<emphasis>$r->flush</emphasis> — метод немедленно передаёт данные клиенту. +</listitem> + +<listitem> +<emphasis>$r->sendfile(имя [, смещение [, длина]])</emphasis> — метод +передаёт клиенту содержимое указанного файла. Необязательные параметры +указывают начальное смещение и длину передаваемых данных. +Собственно передача данных происходит уже после завершения +perl'ового обработчика. +Необходимо учитывать, что при использовании +этого метода в подзапросе и директиве <link doc="ngx_http_core_module.xml#sendfile">sendfile on</link> +содержимое файла не будет проходить через +<link doc="ngx_http_gzip_module.xml">gzip</link>, +<link doc="ngx_http_ssi_module.xml">SSI</link> и +<link doc="ngx_http_charset_module.xml">charset</link> +фильтры. +</listitem> + +<listitem> +<emphasis>$r->send_http_header(<value>тип</value>)</emphasis> — метод +передаёт клиенту заголовок ответа. +Необязательный параметр "тип" устанавливает значение строки "Content-Type" +в заголовке ответа. +Пустая строка в качестве типа запрещает строку "Content-Type". +</listitem> + +<listitem> +<emphasis>$r->status(код)</emphasis> — метод устанавливает код ответа. +</listitem> + +<listitem> +<emphasis>$r->sleep(миллисекунды, обработчик)</emphasis> — метод устанавливает +указанный обработчик и останавливает обработку запроса на заданное время. +nginx в это время продолжает обрабатывать другие запросы. +По истечении указанного времени nginx вызовет установленный обработчик. +Обратите внимание, что нужно передавать ссылку на функцию обработчика. +Для передачи данных между обработчиками следует использовать $r->variable(). +Пример использования: +<example> +package hello; + +use nginx; + +sub handler { + my $r = shift; + + $r->discard_request_body; + $r->variable("var", "OK"); + $r->sleep(1000, <emphasis>\&next</emphasis>); + + return OK; +} + +sub <emphasis>next</emphasis> { + my $r = shift; + + $r->send_http_header; + $r->print($r->variable("var")); + + return OK; +} + +1; + +__END__ +</example> +</listitem> + +<listitem> +<emphasis>$r->unescape(текст)</emphasis> — метод декодирует текст, +заданный в виде %XX. +</listitem> + +<listitem> +<emphasis>$r->uri</emphasis> — метод возвращает URI запроса. +</listitem> + +<listitem> +<emphasis>$r->variable(имя [, значение])</emphasis> — метод возвращает +или устанавливает значение указанной переменной. +Переменные локальны для каждого запроса. +</listitem> + +</list> +</para> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_proxy_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,867 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_proxy_module" + link="/ru/docs/http/ngx_http_proxy_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_proxy_module позволяет передавать запросы другому серверу. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +location / { + proxy_pass http://localhost:8000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; +} +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="proxy_buffer_size"> +<syntax>proxy_buffer_size <value>размер</value></syntax> +<default>proxy_buffer_size 4k/8k</default> +<context>http, server, location</context> + +<para> +Директива задаёт размер буфера, в который будет читаться +первая часть ответа, получаемого от проксируемого сервера. +В этой части ответа находится, как правило, небольшой заголовок ответа. +По умолчанию размер буфера равен размеру одного буфера в директиве +<link id="proxy_buffers"/>, однако его можно сделать меньше. +</para> + +</directive> + + +<directive name="proxy_buffering"> +<syntax>proxy_buffering <value>on|off</value></syntax> +<default>proxy_buffering on</default> +<context>http, server, location</context> + +<para> +Директива разрешает использовать буферизацию ответа проксируемого сервера. +Если буферизация включена, то nginx принимает ответ проксируемого сервера +как можно быстрее, сохраняя его в буфера, заданные директивами +<link id="proxy_buffer_size"/> и <link id="proxy_buffers"/>. +Если ответ не помещается полностью в память, то его часть записывается на диск. +</para> + +<para> +Если буферизация выключена, то ответ синхронно передаётся клиенту сразу же +по мере его поступления. nginx не пытается считать весь ответ проксируемого +сервера, максимальный размер данных, который nginx может принять от сервера +задаётся директивой <link id="proxy_buffer_size"/>. +</para> + +</directive> + + +<directive name="proxy_buffers"> +<syntax>proxy_buffers <value>число размер</value></syntax> +<default>proxy_buffers 8 4k/8k</default> +<context>http, server, location</context> + +<para> +Директива задаёт число и размер буферов для одного соединения, +в которые будет читаться ответ, получаемый от проксируемого сервера. +По умолчанию размер одного буфера равен размеру страницы, в зависимости +от платформы это или 4K, или 8K. +</para> + +</directive> + + +<directive name="proxy_cache"> +<syntax>proxy_cache <value>[зона|off]</value></syntax> +<default>off</default> +<context>http, server, location</context> + +<para> +Директива задаёт зону для кэширования. +Одна и та же зона может использоваться в нескольких местах. +Параметр "off" запрещает кэширование, унаследованное с предыдущего +уровня конфигурации. +</para> + +</directive> + + +<directive name="proxy_cache_bypass"> +<syntax>proxy_cache_bypass <value>строка [...]</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт условия, при которых ответ не будет браться из кэша. +Если значение хотя бы одной из строк переменных не пустое и не равно "0", +то ответ не берётся из кэша: +<example> +proxy_cache_bypass $cookie_nocache $arg_nocache$arg_comment; +proxy_cache_bypass $http_pragma $http_authorization; +</example> +Можно использовать совместно с директивой <link id="proxy_no_cache"/>. +</para> + +</directive> + + +<directive name="proxy_cache_key"> +<syntax>proxy_cache_key <value>строка</value></syntax> +<default>$scheme$proxy_host$request_uri</default> +<context>http, server, location</context> + +<para> +Директива задаёт ключ для кэширования, например, +<example> +proxy_cache_key "$host$request_uri $cookie_user"; +</example> +По умолчанию значение директивы близко к строке +<example> +proxy_cache_key $scheme$proxy_host$uri$is_args$args; +</example> +</para> + +</directive> + + +<directive name="proxy_cache_path"> +<syntax>proxy_cache_path <value>путь [levels=уровни] +keys_zone=название:размер [inactive=время] [max_size=размер]</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива задаёт путь и другие параметры кэша. Данные кэша хранятся в файлах. +Ключом и именем файла в кэше является результат функции md5 от +проксированного URL. Параметр levels задаёт уровни иерархии кэша, +например, при использовании +<example> +proxy_cache_path /data/nginx/cache levels=1:2 keys_zone=one:10m; +</example> +имена файлов в кэше будут такого вида: +<example> +/data/nginx/cache/<emphasis>c/29</emphasis>/b7f54b2df7773722d382f4809d650<emphasis>29c</emphasis> +</example> +</para> + +<para> +Кэшируемый ответ записывается во временный файл, а потом этот файл +переименовывается. Начиная с версии 0.8.9, временные файлы и кэш +могут располагаться на разных файловых системах, но нужно учитывать, +что в этом случае вместо дешёвой операции переименовывания в пределах +одной файловой системы файл копируется с одной файловой системы на другую. +Поэтому лучше, если кэш будет находиться на той же файловой +системе, что и каталог с временными файлами, задаваемый директивой +<link id="proxy_temp_path"/> для данного location. +</para> + +<para> +Кроме того, все активные ключи и информация о данных хранятся в разделяемой +памяти — зоне, имя и размер которой задаётся параметром keys_zone. +Если к данным кэша не обращются в течение времени, заданного параметром +inactive, то данные удаляются, независимо от их свежести. +По умолчанию inactive равен 10 минутам. +</para> + +<para> +Специальный процесс "cache manager" следит за максимальным размером кэша, +заданным параметром max_size, и при превышении его размеров удаляет +самые невостребованные данные. +</para> + +</directive> + + +<directive name="proxy_cache_min_uses"> +<syntax>proxy_cache_min_uses <value>число</value></syntax> +<default>proxy_cache_min_uses 1</default> +<context>http, server, location</context> + +<para> +Директива задаёт число запросов, после которого ответ будет +закэширован. +</para> + +</directive> + + +<directive name="proxy_cache_valid"> +<syntax>proxy_cache_valid <value>ответ [ответ ...] время</value> +</syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт время кэширования для разных ответов. +Например, директивы +<example> +proxy_cache_valid 200 302 10m; +proxy_cache_valid 404 1m; +</example> +задают время кэширования 10 минут для ответов 200 и 302, +и 1 минуту для ответов 404. +</para> + +<para> +Если указано только время кэширования, +<example> +proxy_cache_valid 5m; +</example> +то кэшируются только ответы 200, 301 и 302. +</para> + +<para> +Кроме того, может кэшировать любые ответы с помощью параметра "any": +<example> +proxy_cache_valid 200 302 10m; +proxy_cache_valid 301 1h; +proxy_cache_valid any 1m; +</example> +</para> + +</directive> + + +<directive name="proxy_cache_use_stale"> +<syntax>proxy_cache_use_stale <value>[error | timeout | invalid_header + | updating | http_500 | http_502 | http_503 | http_504 | http_404 | off] +[...]</value></syntax> +<default>proxy_cache_use_stale off</default> +<context>http, server, location</context> + +<para> +Директива определяет, в каких случаях можно использовать +устаревший закэшированный ответ, если при работе с проксированным +сервером возникла ошибка. Параметры директивы совпадают с параметрами +директивы <link id="proxy_next_upstream"/>. +И, кроме того, есть параметр updating, которой разрешает использовать +устаревший закэшированный ответ, если на данный момент он уже обновляется. +</para> + +</directive> + + +<directive name="proxy_connect_timeout"> +<syntax>proxy_connect_timeout <value>время</value></syntax> +<default>proxy_connect_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут для соединения с проксированным сервером. +Необходимо иметь в виду, что этот таймаут не может быть больше 75 секунд. +</para> + +</directive> + + +<directive name="proxy_hide_header"> +<syntax>proxy_hide_header <value>имя</value></syntax> +<context>http, server, location</context> + +<para> +nginx не передаёт клиенту строки заголовка "Date", "Server", "X-Pad" и +"X-Accel-..." из ответа проксированного сервера. +Директива proxy_hide_header задаёт дополнительные строки. +Если же строки нужно наоброт разрешить, то нужно воспользоваться +директивой <link id="proxy_pass_header"/>. +</para> + +</directive> + + +<directive name="proxy_ignore_client_abort"> +<syntax>proxy_ignore_client_abort <value>[on|off]</value></syntax> +<default>proxy_ignore_client_abort off</default> +<context>http, server, location</context> + +<para> +Директива определяет, закрывать ли соединение с проксированным сервером +в случае, если клиент закрыл соединение, не дождавшись ответа. +</para> + +</directive> + + +<directive name="proxy_ignore_headers"> +<syntax>proxy_ignore_headers <value>имя [имя ...]</value></syntax> +<context>http, server, location</context> + +<para> +Директива proxy_ignore_headers запрещает обработку некоторых +строк заголовка из ответа проксированного сервера. +В директиве можно указать строки "X-Accel-Redirect", "X-Accel-Expires", +"Expires" и "Cache-Control". +</para> + +</directive> + + +<directive name="proxy_intercept_errors"> +<syntax>proxy_intercept_errors <value>[on|off]</value></syntax> +<default>proxy_intercept_errors off</default> +<context>http, server, location</context> + +<para> +Директива определяет, передавать ли клиенту проксированные ответы с кодом +больше или равные 400 или же перенаправлять их на обработку nginx'у с помощью +директивы error_page. +</para> + +</directive> + + +<directive name="proxy_next_upstream"> +<syntax>proxy_next_upstream <value>[error | timeout | invalid_header + | http_500 | http_502 | http_503 | http_504 | http_404 | off] +[...]</value></syntax> +<default>proxy_next_upstream error timeout</default> +<context>http, server, location</context> + +<para> +Директива определяет, в каких случаях запрос будет передан следующему серверу: +<list type="bullet"> + +<listitem> +error — произшла ошибка соединения с сервером, передачи ему запроса или +чтения заголовка ответа сервера; +</listitem> + +<listitem> +timeout — произошёл таймаут во время соединения с сервером, +передачи ему запроса или чтения заголовка ответа сервера; +</listitem> + +<listitem> +invalid_header — сервер вернул пустой или неверный ответ; +</listitem> + +<listitem> +http_500 — сервер вернул ответ с кодом 500; +</listitem> + +<listitem> +http_502 — сервер вернул ответ с кодом 502; +</listitem> + +<listitem> +http_503 — сервер вернул ответ с кодом 503; +</listitem> + +<listitem> +http_504 — сервер вернул ответ с кодом 504; +</listitem> + +<listitem> +http_404 — сервер вернул ответ с кодом 404; +</listitem> + +<listitem> +off — запрещает передачу запроса следующему серверу; +</listitem> + +</list> +</para> + +<para> +Необходимо понимать, что передача запроса следующему серверу возможна +только при условии, что клиенту ещё ничего не передавалось. +То есть, если ошибка или таймаут возникли в середине передачи ответа, +то исправить это уже невозможно. +</para> + +</directive> + + +<directive name="proxy_no_cache"> +<syntax>proxy_no_cache <value>строка [...]</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт условия, при которых ответ не будет сохраняться в кэш. +Если значение хотя бы одной из строк переменных не пустое и не равно "0", +то ответ не будет сохранён: +<example> +proxy_no_cache $cookie_nocache $arg_nocache$arg_comment; +proxy_no_cache $http_pragma $http_authorization; +</example> +Можно использовать совместно с директивой <link id="proxy_cache_bypass"/>. +</para> + +</directive> + + +<directive name="proxy_pass"> +<syntax>proxy_pass <value>URL</value></syntax> +<default>нет</default> +<context>location, if в location, limit_except</context> + +<para> +Директива задаёт адрес проксируемоего сервера и URI, на который +будет отображаться location. +Адрес может быть указан в виде доменного имени или адреса и порта, например, +<example> + proxy_pass http://localhost:8000/uri/; +</example> +или в виде пути unix сокета: +<example> + proxy_pass http://unix:/tmp/backend.socket:/uri/; +</example> +путь указан после слова unix и заключён между двумя двоеточиями. +</para> + +<para> +Если доменное имя резолвится в несколько адресов, то все они будут +использоваться в режиме round-robin. +И кроме того, адрес можно задать +<link doc="ngx_http_upstream.xml">группой серверов</link>. +</para> + +<para> +При передаче запроса серверу часть URI, соответствующая location, +заменяется на URI, указанный в директиве proxy_pass. +Но из этого правила есть два исключения, в которых нельзя определить +заменяемый location: +<list type="bullet"> + +<listitem> +если location задан регулярным выражением; +</listitem> + +<listitem> +если внутри проксируемого location с помощью директивы rewrite изменяется +URI и именно с этой конфигурацией будет обрабатываться запрос (break): +<example> +location /name/ { + rewrite /name/([^/]+) /users?name=$1 break; + proxy_pass http://127.0.0.1; +} +</example> +Для этих случаев URI передаётся без отображения. +</listitem> + +</list> +</para> + +<para> +Кроме того, можно указать, чтобы URI запроса передавалось в том же виде, +как его прислал клиент, а не в в обработанном виде. +Во время обработки +<list type="bullet"> + +<listitem> +два и более слэшей преобразуются в один слэш: "//" — "/"; +</listitem> + +<listitem> +убираются ссылки на текущий каталог: "/./" — "/"; +</listitem> + +<listitem> +убираются ссылки на предыдущий каталог: "/dir/../" — "/". +</listitem> + +</list> +</para> + +<para> +Если на сервер нужно передать URI в необработанном виде, то для этого +в директиве proxy_pass нужно указать URL сервера без URI: +<example> +location /some/path/ { + proxy_pass http://127.0.0.1; +} +</example> +</para> + +<para> +Имя сервера, его порт и передаваемый URI можно также полностью задать +в помощью переменных: +<example> + proxy_pass http://$host$uri; +</example> +или так: +<example> + proxy_pass $request; +</example> +</para> + +<para> +В этом случае имя сервера ищется среди описанных +<link doc="ngx_http_upstream.xml">групп серверов</link> +и если не найдено, то определяется с помощью <link doc="ngx_http_core_module.xml#resolver">resolver'а</link>. +</para> + +</directive> + + +<directive name="proxy_pass_header"> +<syntax>proxy_pass_header <value>имя</value></syntax> +<context>http, server, location</context> + +<para> +Директива разрешает передавать от проксируемого сервера клиенту +запрещённые для передачи строки. +</para> + +</directive> + + +<directive name="proxy_redirect"> +<syntax>proxy_redirect <value>[default|off|редирект замена]</value> +</syntax> +<default>proxy_redirect default</default> +<context>http, server, location</context> + +<para> +Директива задаёт текст, который нужно изменить в строках заголовка "Location" +и "Refresh" в ответе проксируемого сервера. Предположим, проксируемый сервер +вернул строку "Location: http://localhost:8000/two/some/uri/". Директива +<example> + proxy_redirect http://localhost:8000/two/ http://frontend/one/; +</example> +перепишет эту строку в виде "Location: http://frontend/one/some/uri/". +</para> + +<para> +В заменяемой строке можно не указывать имя сервера: +<example> + proxy_redirect http://localhost:8000/two/ /; +</example> +тогда будет поставлено основное имя сервера и порт, если он отличен от 80. +</para> + +<para> +Изменение по умолчанию, задаваемое параметром "default", использует +параметры директив location и proxy_pass. +Поэтому две нижеприведённые конфигурации одинаковы: +<example> +location /one/ { + proxy_pass http://upstream:port/two/; + proxy_redirect default; +</example> + +<example> +location /one/ { + proxy_pass http://upstream:port/two/; + proxy_redirect http://upstream:port/two/ /one/; +</example> +</para> + +<para> +В заменяемой строке можно использовать переменные: +<example> + proxy_redirect http://localhost:8000/ http://$host:$server_port/; +</example> +</para> + +<para> +Директив может быть несколько: +<example> + proxy_redirect default; + proxy_redirect http://localhost:8000/ /; + proxy_redirect http://www.example.com/ /; +</example> +</para> + +<para> +Параметр "off" запрещает все директивы proxy_redirect на данном уровне: +<example> + proxy_redirect off; + proxy_redirect default; + proxy_redirect http://localhost:8000/ /; + proxy_redirect http://www.example.com/ /; +</example> +</para> + +<para> +С помощью этой директивы можно также добавлять имя хоста к относительным +редиректам, выдаваемым проксируемым сервером: +<example> + proxy_redirect / /; +</example> +</para> + +</directive> + + +<directive name="proxy_read_timeout"> +<syntax>proxy_read_timeout <value>время</value></syntax> +<default>proxy_read_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут при чтении ответа проксированного сервера. +Таймаут устанавливается не на всю передачу ответа, +а только между двумя операциями чтения. +Если по истечении этого времени проксируемый сервер ничего не передаст, +то nginx закрывает соединение. +</para> + +</directive> + + +<directive name="proxy_redirect_errors"> +<syntax>proxy_redirect_errors <value>[on|off]</value></syntax> + +<para> +Директива переименована в <link id="proxy_intercept_errors"/>. +</para> + +</directive> + + +<directive name="proxy_send_timeout"> +<syntax>proxy_send_timeout <value>время</value></syntax> +<default>proxy_send_timeout 60</default> +<context>http, server, location</context> + +<para> +Директива задаёт таймаут при передаче запроса проксированному серверу. +Таймаут устанавливается не на всю передачу запроса, +а только между двумя операциями записи. +Если по истечении этого времени проксируемый сервер не примет новых данных, +то nginx закрывает соединение. +</para> + +</directive> + + +<directive name="proxy_set_header"> +<syntax>proxy_set_header <value>заголовок значение</value></syntax> +<default>Host и Connection</default> +<context>http, server, location</context> + +<para> +Директива позволяет переопределять или добавлять строки заголовка запроса, +передаваемые проксируемому серверу. +В качестве значения можно использовать текст, переменные и их комбинации. +Директивы наследуются с предыдущего уровня при условии, что на данном +уровне не описаны свои директивы proxy_set_header. +По умолчанию переопределяются только две строки: +<example> +proxy_set_header Host $proxy_host; +proxy_set_header Connection close; +</example> +</para> + +<para> +Неизменённую строку заголовка запроса "Host" можно передать так: +<example> +proxy_set_header Host $http_host; +</example> +</para> + +<para> +Однако, если эта строка отсутствует в запросе клиента, то ничего +передаваться не будет. В этом случае лучше воспользоваться переменной +$host, её значение равно имени сервера в строке заголовка запроса "Host" +или же основному имени сервера, если строки нет: +<example> +proxy_set_header Host $host; +</example> +</para> + +<para> +Кроме того, можно передать имя сервера вместе с портом проксируемого сервера: +<example> +proxy_set_header Host $host:$proxy_port; +</example> +</para> + +<para> +Если значение строки заголовка — пустая строка, то строка вообще +не будет передаваться проксируемому серверу: +<example> +proxy_set_header Accept-Encoding ""; +</example> +</para> + +</directive> + + +<directive name="proxy_ssl_session_reuse"> +<syntax>proxy_ssl_session_reuse <value>[on|off]</value></syntax> +<default>proxy_ssl_session_reuse on</default> +<context>http, server, location</context> + +<para> +Директива определяет, использовать ли повторно SSL-сессии при +работе с проксированным сервером. Если в логах появляются ошибки +"SSL3_GET_FINISHED:digest check failed", то можно попробовать выключить +повторное использование сессий. +</para> + +</directive> + + +<directive name="proxy_store"> +<syntax>proxy_store <value>on | off | строка </value></syntax> +<default>proxy_store off</default> +<context>http, server, location</context> + +<para> +Директива разрешает сохранение на диск файлов. +Параметр "on" сохраняет файлы в соответствии с путями, указаными в директивах +<link doc="ngx_http_core_module.xml#alias">alias</link> или +<link doc="ngx_http_core_module.xml#root">root</link>. +Параметр "off" запрещает сохранение файлов. +Кроме того, имя файла можно явно задать с помощью строки с переменными: +<example> +proxy_store /data/www$original_uri; +</example> +</para> + +<para> +Время модификации файлов выставляется согласно полученной строке +"Last-Modified" в заголовке ответа. +Ответ записывается во временный файл, а потом этот файл переименовывается. +Начиная с версии 0.8.9, временный файл и постоянное место хранения ответа +могут располагаться на разных файловых системах, но нужно учитывать, +что в этом случае вместо дешёвой операции переименовывания в пределах +одной файловой системы файл копируется с одной файловой системы на другую. +Поэтому лучше, если сохраняемые файлы будут находиться на той же файловой +системе, что и каталог с временными файлами, задаваемый директивой +<link id="proxy_temp_path"/> для данного location. +</para> + +<para> +Директиву можно использовать для создания локальных копий статических +неизменяемых файлов, например, так: +<example> +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/; +} +</example> +</para> + +<para> +или так: +<example> +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; +} +</example> +</para> + +</directive> + + +<directive name="proxy_store_access"> +<syntax>proxy_store_access <value>пользователи:права [пользователи:права] +...</value></syntax> +<default>proxy_store_access user:rw</default> +<context>http, server, location</context> + +<para> +Директива задаёт права доступа для создаваемых файлов и каталогов, например, +<example> +proxy_store_access user:rw group:rw all:r; +</example> +</para> + +<para> +Если заданы какие-либо права для groups или all, то права для user +указывать необязательно: +<example> +proxy_store_access group:rw all:r; +</example> +</para> + +</directive> + + +<directive name="proxy_temp_path"> +<syntax>proxy_temp_path <value>путь [ уровень1 [ уровень2 [ уровень3 ] ] ] +</value></syntax> +<default>proxy_temp_path proxy_temp</default> +<context>http, server, location</context> + +<para> +Директива задаёт имя каталога для хранения временных файлов +полученных от другого сервера. +В каталоге может использоваться иерархия подкаталогов до трёх уровней. +Например, при такой конфигурации +<example> +proxy_temp_path /spool/nginx/proxy_temp 1 2; +</example> +имя временного будет такого вида: +<example> +/spool/nginx/proxy_temp/7/45/00000123457 +</example> +</para> + +</directive> + +</section> + + +<section name="Встроенные переменные" id="variables"> + +<para> +В модуле ngx_http_proxy_module есть встроенные переменные, +которые можно использовать для формирования заголовков с помощью директивы +<link id="proxy_set_header"/>: +<list type="bullet"> + +<listitem> +$proxy_host, эта переменная равна имени проксируемого хоста и порта; +</listitem> + +<listitem> +$proxy_port, эта переменная равна порту проксируемого хоста; +</listitem> + +<listitem> +$proxy_add_x_forwarded_for, эта переменная равна строке заголовка запроса +клиента "X-Forwarded-For" и добавленной к ней через запятую переменной +$remote_addr. Если же строки "X-Forwarded-For" в запросе клиента нет, +то переменная $proxy_add_x_forwarded_for равна переменной $remote_addr. +</listitem> + +</list> +</para> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_random_index_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,50 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_random_index_module" + link="/ru/docs/http/ngx_http_random_index_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_random_index_module выдаёт случайный файл в качестве +индексного файла каталога. Модуль работает до модуля +<link doc="ngx_http_index_module.xml">ngx_http_index_module</link>. +По умолчанию модуль не собирается, нужно разрешить его сборку при +конфигурировании параметром <command>--with-http_random_index_module</command>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + location / { + random_index on; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="random_index"> +<syntax>random_index <value>[on|off]</value></syntax> +<default>random_index off</default> +<context>location</context> + +<para> +Директива разрешает или запрещает работу модуля. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_realip_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,65 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_realip_module" + link="/ru/docs/http/ngx_http_realip_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_realip_module позволяет менять адрес клиента +на переданный в указанной строке заголовка. +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром <command>--with-http_realip_module</command>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + set_real_ip_from 192.168.1.0/24; + set_real_ip_from 192.168.2.1; + real_ip_header X-Real-IP; +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="set_real_ip_from"> +<syntax>set_real_ip_from <value>[адрес|CIDR]</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива описывает доверенные адреса, которые передают верный адрес +для замены. +</para> + +</directive> + + +<directive name="real_ip_header"> +<syntax>real_ip_header <value>имя строки[X-Real-IP|X-Forwarded-For]</value></syntax> +<default>real_ip_header X-Real-IP</default> +<context>http, server, location</context> + +<para> +Директива указывает название строки в заголовке запроса, +в котором передаётся адрес для замены. +В случае строки "X-Forwarded-For" используется последний адрес в значении +строки. Для остальных строк используется всё значение. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_referer_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,102 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_referer_module" + link="/ru/docs/http/ngx_http_referer_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_referer_module позволяет блокировать доступ +к сайту с неверными значениями строки "Referer" в заголовке запроса. +Следует иметь в виду, что подделать запрос с нужной строкой "Referer" +не составляет большого труда, поэтому цель использования данного модуля +заключается не в стопроцентном блокировании подобных запросов, +а в блокировании массового потока запросов, сделанных обычными браузерами. +Нужно также учитывать, что обычные браузеры могут не передавать cтроку +"Referer" даже для верных запросов. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + valid_referers none blocked server_names + *.example.com www.example.info/galleries/ + ~\.google\. ; + + if ($invalid_referer) { + return 403; + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="valid_referers"> +<syntax>valid_referers + [none|blocked|server_names|<value>строка</value>] ...</syntax> +<default>нет</default> +<context>server, location</context> + +<para> +Директива задаёт значения строки "Referer" в заголовке запроса, при +которых встроенная переменная $invalid_referer будет иметь значение 0. +</para> + +<para> +Параметры могут быть следующие: +<list type="bullet"> + +<listitem> +none — строка "Referer" в заголовке запроса отсутствует; +</listitem> + +<listitem> +blocked — строка "Referer" в заголовке запроса присутствует, +но её значение удалено файрволлом или прокси-сервером; к таким строкам +относятся строки, неначинающиеся на "http://"; +</listitem> + +<listitem> +server_names — в строке "Referer" в заголовке запроса указано одно +из имён сервера; +</listitem> + +<listitem> +произвольная строка — задаёт имя сервера и необязательное начало URI. +В начале или конце имени сервера может быть "*". +При проверке порт сервера в строке "Referer" игнорируется. +</listitem> + +<listitem> +регулярное выражение — в начале должен быть символ "~". +Необходимо учитывать, что на совпадение с выражением будет проверяться +текст, начинающийся после "http://". +</listitem> + +</list> +</para> + +<para> +Пример использования: +<example> + valid_referers none blocked server_names + *.example.com example.* www.example.info/galleries/ + ~\.google\. ; +</example> +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_rewrite_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,340 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_rewrite_module" + link="/ru/docs/http/ngx_http_rewrite_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_rewrite_module позволяет изменять URI с помощью +регулярных выражений, делать редиректы и выбирать конфигурацию +в зависимости от переменных. Если директивы этого модуля описаны +на уровне сервера, то они выполняются до того, как определяется +location для запроса. Если в выбранном location тоже есть +директивы модуля ngx_http_rewrite_module, то они также выполняются. +Если URI изменился в результате исполнения директив внутри location, +то снова определяется location для уже нового URI. Этот цикл может +повторяться до 10 раз, после чего nginx возвращает ошибку +"Server Internal Error" (500). +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="break"> +<syntax>break</syntax> +<default>нет</default> +<context>server, location, if</context> + +<para> +Директива завершает обработку текущего набора директив +ngx_http_rewrite_module. +</para> + +<para> +Пример использования: +<example> + if ($slow) { + limit_rate 10k; + break; + } +</example> +</para> + +</directive> + + +<directive name="if"> +<syntax>if (<value>условие</value>) { ... }</syntax> +<default>нет</default> +<context>server, location</context> + +<para> +Директива if проверяет истинность условия, если оно истинно, +то выполняется указанный в фигурных скобках код и запрос обрабатывается +в соответствии с заданной там же конфигурацией. +Конфигурация внутри директивы if наследуется из предыдущего уровня. +</para> + +<para> +В качестве условия могут быть заданы: +<list type="bullet"> + +<listitem> +имя переменной; ложными значениями переменной являются пустая строка "" +или любая строка, начинающиеся на "0"; +</listitem> + +<listitem> +сравнение переменной со строкой с помощью операторов "=" и "!="; +</listitem> + +<listitem> +проверка переменной с помощью регулярного выражения без учёта +регистра символов — "~*" и с учётом — "~". +В регулярных выражениях можно использовать выделения, которые затем +доступны в виде переменных $1 — $9. +Также можно использовать отрицательные операторы "!~" и "!~*". +Если в регулярном выражении встречаются символы "}" или ";", то +всё выражение нужно заключить в одинарные или двойные кавычки. +</listitem> + +<listitem> +проверка существования файла с помощью операторов "-f" и "!-f"; +</listitem> + +<listitem> +проверка существования каталога с помощью операторов "-d" и "!-d"; +</listitem> + +<listitem> +проверка существования файла, каталога или символической ссылки +с помощью операторов "-e" и "!-e"; +</listitem> + +<listitem> +проверка исполняемости файла с помощью операторов "-x" и "!-x". +</listitem> + +</list> +</para> + +<para> +Примеры использования: +<example> + if ($http_user_agent ~ MSIE) { + rewrite ^(.*)$ /msie/$1 break; + } + + if ($http_cookie ~* "id=([^;]+)(?:;|$)" ) { + set $id $1; + } + + if ($request_method = POST ) { + return 405; + } + + + if ($slow) { + limit_rate 10k; + } + + if ($invalid_referer) { + return 403; + } +</example> +Значение встроенной переменной $invalid_referer задаётся директивой <link doc="ngx_http_referer_module.xml#valid_referers">valid_referers</link>. +</para> + +</directive> + + +<directive name="return"> +<syntax>return <value>код</value></syntax> +<default>нет</default> +<context>server, location, if</context> + +<para> +Директива return завершает исполнение кода и возвращает клиенту +указанный код. Можно использовать следующие значения: 204, 400, +402 — 406, 408, 410, 411, 413, 416 и 500 — 504. +Кроме того, нестандартный код 444 закрывает соединение без передачи +заголовка ответа. +</para> + +</directive> + + +<directive name="rewrite"> +<syntax>rewrite <value>regex</value> <value>замена</value> + <value>флаг</value> +</syntax> +<default>нет</default> +<context>server, location, if</context> + +<para> +Директива rewrite изменяет URI в соответствии с регулярным выражением +и строкой замены. Директивы выполняются в порядке их следования в +конфигурационном файле. С помощью флагов можно досрочно прекратить +исполнение директив. Если строка замены начинается с "http://", то +клиенту будет возвращён редирект и обработка директив также завершается. +</para> + +<para> +Флаги могут быть следующими: +<list type="bullet"> + +<listitem> +last — завершает обработку текущего набора директив +ngx_http_rewrite_module, после чего ищется соответствие URI и location; +</listitem> + +<listitem> +break — завершает обработку текущего набора директив +ngx_http_rewrite_module; +</listitem> + +<listitem> +redirect — возвращает временный редирект с кодом 302; +используется, если заменяющая строка не начинается с "http://"; +</listitem> + +<listitem> +permanent — возвращает постоянный редирект с кодом 301. +</listitem> + +</list> +</para> + +<para> +</para> + +<para> +Пример использования: +<example> + rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 last; + rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra last; + return 403; +</example> +</para> + +<para> +Если же эти директивы поместить в location /download/, то нужно +заменить флаг last на break, иначе nginx сделает 10 циклов и вернёт +ошибку 500: +<example> + location /download/ { + rewrite ^(/download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; + rewrite ^(/download/.*)/audio/(.*)\..*$ $1/mp3/$2.ra break; + return 403; + } +</example> +</para> + +<para> +Если в строке замены указаны аргументы, то предыдущие аргументы запроса +добавляются после них. Можно отказаться от этого добавления, указав +в конце строки замены знак вопроса: +<example> + rewrite ^/users/(.*)$ /show?user=$1? last; +</example> +</para> + +<para> +Если в регулярном выражении встречаются символы "}" или ";", то +всё выражение нужно заключить в одинарные или двойные кавычки. +</para> + +</directive> + + +<directive name="set"> +<syntax>set <value>переменная</value> <value>значение</value> +</syntax> +<default>нет</default> +<context>server, location, if</context> + +<para> +Директива устанавливает значение для указанной переменной. +В качестве значения можно использовать текст, переменные и их комбинации. +</para> + +</directive> + + +<directive name="uninitialized_variable_warn"> +<syntax>uninitialized_variable_warn <value>on|off</value></syntax> +<default>uninitialized_variable_warn on</default> +<context>http, server, location, if</context> + +<para> +Директива определяет, нужно ли писать в лог предупреждение +о неинициализированной переменной. +</para> + +</directive> + +</section> + + +<section name="Внутреннее устройство" id="internals"> + +<para> +Директивы модуля ngx_http_rewrite_module компилируется на стадии +конфигурирования во внутренние коды, исполняемые во время запроса +интерпретатором. Интерпретатор представляет из себя простую +стековую виртуальную машину. +</para> + +<para> +Например, директивы +<example> + location /download/ { + if ($forbidden) { + return 403; + } + + if ($slow) { + limit_rate 10k; + } + + rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; + } +</example> +будет скомпилированы в такие коды: +<example> + переменная $forbidden + проверка на ноль + возврат 403 + завершение всего кода + переменная $slow + проверка на ноль + проверка регулярного выражения + копирование "/" + копирование $1 + копирование "/mp3/" + копирование $2 + копирование ".mp3" + завершение регулярного выражения + завершение всего кода +</example> +</para> + +<para> +Обратите внимание, что кода для директивы limit_rate нет, поскольку +она не имеет отношения к модулю ngx_http_rewrite_module. Для блока +if создаётся такая же конфигурация, как и для блока location. +Если условие истинно, то запрос получает конфигурацию, соответствующую +блоку if, и в этой конфигурации limit_rate равен 10k. +</para> + +<para> +Директиву +<example> + rewrite ^/(download/.*)/media/(.*)\..*$ /$1/mp3/$2.mp3 break; +</example> +можно сделать на один код меньше, если в регулярном выражении включить +первый слэш в скобки: +<example> + rewrite ^(<emphasis>/</emphasis>download/.*)/media/(.*)\..*$ $1/mp3/$2.mp3 break; +</example> +тогда её коды будут выглядеть так: +<example> + проверка регулярного выражения + копирование $1 + копирование "/mp3/" + копирование $2 + копирование ".mp3" + завершение регулярного выражения + завершение всего кода +</example> +</para> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_secure_link_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,82 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_secure_link_module" + link="/ru/docs/http/ngx_http_secure_link_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_secure_link_module — это модуль проверяющий +правильность запрашиваемой ссылки (0.7.18+). +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром +<command>--with-http_secure_link_module</command>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +location /p/ { + secure_link_secret some_secret_word; + + if ($secure_link = "") { + return 403; + } +} +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="secure_link_secret"> +<syntax>secure_link_secret <value>слово</value></syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива задаёт секретное слово для проверки правильности ссылки. +Полный URL защищённой ссылки вглядит так: +<example> +/prefix/<value>hash</value>/<value>ссылка</value> +</example> +где hash считается как +<example> +md5(ссылка, секретное_слово); +</example> +</para> + +<para> +Префикс — произвольная строка, не включающая слэш. +</para> + +</directive> + +</section> + + +<section name="Встроенные переменные" id="variables"> + +<para> +<list type="bullet"> + +<listitem> +$secure_link, эта переменная равна ссылке выделенной из полного URL'а. +Если хэш неверный, то переменная равна пустой строке. +</listitem> + +</list> +</para> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_split_clients_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,65 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_split_clients_module" + link="/ru/docs/http/ngx_http_split_clients_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_split_clients_module создаёт переменные для +A/B split-тестирования. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +http { + split_clients "${remote_addr}AAA" $variant { + 0.5% .one; + 2.0% .two; + * ""; + } + + server { + location / { + index index${variant}.html; +</example> +</para> +</section> + + +<section name="Директивы" id="directives"> + +<directive name="split_clients"> +<syntax>split_clients <value>$переменная1 $переменная2 { ... }</value></syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива создаёт переменную для A/B split-тестирования, например: +<example> +split_clients "${remote_addr}AAA" $variant { + 0.5% .one; + 2.0% .two; + * ""; +} +</example> +Значение исходной строки переменных хэшируется с помощью CRC32. +В приведённом примере при значениях хэша от 0 до 21474836 (0.5%) +переменная $variant получит значение ".one". +При значениях хэша от 21474837 до 107374182 (2%) — ".two". +И при значениях хэша от 107374183 до 4294967297 — "". +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_ssi_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,307 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_ssi_module" + link="/ru/docs/http/ngx_http_ssi_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_ssi_module — фильтр, обрабатывающий команды SSI (Server +Side Includes) в проходящих через него ответах. +На данный момент список поддерживаемых команд SSI неполон. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + location / { + ssi on; + ... + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="ssi"> +<syntax>ssi <value>[on|off]</value></syntax> +<default>ssi off</default> +<context>http, server, location, if в location</context> + +<para> +Директива разрешает обработку команд SSI в ответах. +</para> + +</directive> + + +<directive name="ssi_silent_errors"> +<syntax>ssi_silent_errors <value>[on|off]</value></syntax> +<default>ssi_silent_errors off</default> +<context>http, server, location</context> + +<para> +Директива разрешает не выводить строку +"[an error occurred while processing the directive]", +если во время обработки SSI произошла ошибка. +</para> + +</directive> + + +<directive name="ssi_types"> +<syntax>ssi_types <value>mime-тип [mime-тип ...]</value></syntax> +<default>ssi_types text/html</default> +<context>http, server, location</context> + +<para> +Разрешает обработку команд SSI в ответах с указанными MIME-типами в дополнение +к "text/html". +</para> + +</directive> + +</section> + + +<section name="Команды SSI" id="commands"> + +<para> +Формат команды следующий +<example> +<!--# команда параметр1=значение параметр2=значение ... --> +</example> +</para> + +<para> +Ниже перечислены поддерживаемые команды: +<list type="bullet"> + +<listitem> +<emphasis>block</emphasis> — команда описывает блок, который можно использовать +как заглушку в команде include. +Внутри блока могут быть команды SSI. + +<list type="bullet"> +<listitem> +<emphasis>name</emphasis> — имя блока. +</listitem> +</list> + +Пример использования: +<example> +<!--# block name="one" --> +заглушка +<!--# endblock --> +</example> + +</listitem> + +<listitem> +<emphasis>config</emphasis> — команда задаёт некоторые параметры при обработке SSI. + +<list type="bullet"> +<listitem> +<emphasis>errmsg</emphasis> — строка, выводящаяся при ошибке во время обработки +SSI. По умолчанию используется такая строка: +<example> +[an error occurred while processing the directive] +</example> +</listitem> + +<listitem> +<emphasis>timefmt</emphasis> — строка, используемая функцией strftime(3) +для вывода дат и времени. +По умолчанию используется такой формат: +<example> +"%A, %d-%b-%Y %H:%M:%S %Z" +</example> +Для вывода времени в секундах подходит формат "%s". +</listitem> +</list> + +</listitem> + + +<listitem> +<emphasis>echo</emphasis> — команда выводит значение переменной. + +<list type="bullet"> +<listitem> +<emphasis>var</emphasis> — имя переменной. +</listitem> + +<listitem> +<emphasis>encoding</emphasis> — способ кодирования. +Возможны три значения — none, url и entity. +По умолчанию используется entity. +</listitem> + +<listitem> +<emphasis>default</emphasis> — нестандартный параметр, задающий строку, +которая выводится, если переменная не опеределена. +По умолчанию выводится строка "none". Команда +<example> +<!--# echo var="name" default="<emphasis>нет</emphasis>" --> +</example> +заменяет такую последовательность команд +<example> +<!--# if expr="$name" --><!--# echo var="name" --><!--# + else --><emphasis>нет</emphasis><!--# endif --> +</example> +</listitem> +</list> + +</listitem> + + +<listitem> +<emphasis>if</emphasis> — команда выполняет условное включение. +Поддерживаются следующие команды: +<example> +<!--# if expr="..." --> +... +<!--# elif expr="..." --> +... +<!--# else --> +... +<!--# endif --> +</example> +На данный момент поддерживаются только один уровень вложенности. + +<list type="bullet"> +<listitem> +<emphasis>expr</emphasis> — выражение. +В выражении может быть проверка существования переменной: +<example> +<!--# if expr="$name" --> +</example> +сравнение переменной с текстом: +<example> +<!--# if expr="$name = text" --> +<!--# if expr="$name != text" --> +</example> +или с регулярным выражением: +<example> +<!--# if expr="$name = /text/" --> +<!--# if expr="$name != /text/" --> +</example> +Если в text встречаются переменные, то производится подстановка их значений. +</listitem> +</list> + +</listitem> + + +<listitem> +<emphasis>include</emphasis> — команда включает в ответ результат другого запроса. + +<list type="bullet"> +<listitem> +<emphasis>file</emphasis> — задаёт включаемый файл, например: +<example> +<!--# include file="footer.html" --> +</example> +</listitem> + +<listitem> +<emphasis>virtual</emphasis> — задаёт включаемый запрос, например: +<example> +<!--# include virtual="/remote/body.php?argument=value" --> +</example> +Несколько запросов на одной странице, обрабатываемые через прокси или FastCGI, +работают параллельно. Если нужно последовательная обработка, то нужно +воспользоваться параметром wait. +</listitem> + +<listitem> +<emphasis>stub</emphasis> — нестандартный параметр, задающий имя блока, +содержимое которого будет выведено, если тело ответа на включаемый запрос +пустое или при исполнении запроса произошла ошибка, например: +<example> +<!--# block name="one" -->&nbsp;<!--# endblock --> +<!--# include virtual="/remote/body.php?argument=value" stub="one" --> +</example> +при этом содержимое замещающего блока обрабатывается в контексте включаемого +запроса. +</listitem> + +<listitem> +<emphasis>wait</emphasis> — нестандартный параметр, указывающий, нужно ли ждать +полного исполнения данного запроса, прежде чем продолжать выполнение +SSI, например: +<example> +<!--# include virtual="/remote/body.php?argument=value" wait="yes" --> +</example> +</listitem> + +<listitem> +<emphasis>set</emphasis> — нестандартный параметр, указывающий, что удачный +результат выполнения запроса нужно записать в заданную переменную, +например: +<example> +<!--# include virtual="/remote/body.php?argument=value" set="one" --> +</example> +Необходимо учитывать, что в переменные можно записать только результаты +ответов, полученные через модули +ngx_http_proxy_module и ngx_http_memcached_module. +</listitem> + +</list> + +</listitem> + +<listitem> +<emphasis>set</emphasis> — команда присваивает значение переменной. + +<list type="bullet"> +<listitem> +<emphasis>var</emphasis> — имя переменной. +</listitem> + +<listitem> +<emphasis>value</emphasis> — значение переменной. Если в присваиваемом значении +есть переменные, то производится подстановка их значений. +</listitem> +</list> + +</listitem> + +</list> +</para> + +</section> + + +<section name="Встроенные переменные" id="variables"> + +<para> +Модуль ngx_http_ssi_module поддерживает две встроенные переменные: +<list type="bullet"> + +<listitem> +$date_local, эта переменная равна текущему времени в локальной временной зоне. +Формат даты задаётся командой config с параметром timefmt. +</listitem> + +<listitem> +$date_gmt, эта переменная равна текущему времени в GMT. +Формат даты задаётся командой config с параметром timefmt. +</listitem> + +</list> +</para> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_ssl_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,418 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_ssl_module" + link="/ru/docs/http/ngx_http_ssl_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_ssl_module обеспечивает работу по протоколу HTTPS. +Поддерживается проверка сертификатов клиентов с ограничением — +если в файле, заданном директивой <link id="ssl_certificate"/>, +указана цепочка сертификатов, то при проверке клиентских сертификатов +nginx также будет использовать и сертификаты этих промежуточных CA. +</para> + +<para> +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром +<command>--with-http_ssl_module</command>. +Для сборки и работы этого модуля нужна библиотека +<link url="http://www.openssl.org">OpenSSL</link>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +Для уменьшения загрузки процессора рекомендуется +<list type="bullet"> + +<listitem> +установить число рабочих процессов равным числу процессоров, +</listitem> + +<listitem> +разрешить keep-alive соединения, +</listitem> + +<listitem> +включить разделяемый кэш сессий, +</listitem> + +<listitem> +выключить встроенный кэш сессий +</listitem> + +<listitem> +и, возможно, увеличить время жизни сессии (по умолчанию 5 минут): +</listitem> + +</list> + +<example> +<emphasis>worker_processes 2;</emphasis> + +http { + + ... + + server { + listen 443; + <emphasis>keepalive_timeout 70;</emphasis> + + ssl on; + ssl_protocols SSLv3 TLSv1; + ssl_ciphers AES128-SHA:AES256-SHA:RC4-SHA:DES-CBC3-SHA:RC4-MD5; + ssl_certificate /usr/local/nginx/conf/cert.pem; + ssl_certificate_key /usr/local/nginx/conf/cert.key; + <emphasis>ssl_session_cache shared:SSL:10m;</emphasis> + <emphasis>ssl_session_timeout 10m;</emphasis> + + ... + } +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="ssl"> +<syntax>ssl <value>[on|off]</value></syntax> +<default>ssl off</default> +<context>http, server</context> + +<para> +Директива разрешает протокол HTTPS для данного виртуального сервера. +</para> + +</directive> + + +<directive name="ssl_certificate"> +<syntax>ssl_certificate <value>файл</value></syntax> +<default>нет</default> +<context>http, server</context> + +<para> +Директива указывает файл с сертификатом в формате PEM +для данного виртуального сервера. +Если вместе с основным сертификатом нужно указать промежуточные, +то они должны находиться в этом же файле в следующем порядке — сначала +основной сертификат, а затем промежуточные. +В этом же файле может находиться секретный ключ в формате PEM. +</para> + +<para> +Нужно иметь ввиду, что из-за ограничения протокола HTTPS +виртуальные сервера должны слушать на разных IP-адресах: +<example> + server { + listen 192.168.1.1:443; + server_name one.example.com; + ssl_certificate /usr/local/nginx/conf/one.example.com.cert; + ... + } + + server { + listen 192.168.1.2:443; + server_name two.example.com; + ssl_certificate /usr/local/nginx/conf/two.example.com.cert; + ... + } +</example> +иначе для второго сайта будет выдаваться +<link doc="../faq.xml#name_based_vhost_ssl">сертификат +первого сервера</link>. +</para> + +</directive> + + +<directive name="ssl_certificate_key"> +<syntax>ssl_certificate_key <value>файл</value></syntax> +<default>нет</default> +<context>http, server</context> + +<para> +Директива указывает файл с секретным ключом в формате PEM +для данного виртуального сервера. +</para> + +</directive> + + +<directive name="ssl_client_certificate"> +<syntax>ssl_client_certificate <value>файл</value></syntax> +<default>нет</default> +<context>http, server</context> + +<para> +Директива указывает файл с сертификатами CA в формате PEM, используемыми для +для проверки клиентских сертификатов. +</para> + +</directive> + + +<directive name="ssl_ciphers"> +<syntax>ssl_ciphers <value>шифры</value></syntax> +<default>ssl_ciphers HIGH:!ADH:!MD5</default> +<context>http, server</context> + +<para> +Директива описывает разрешённые шифры. +Шифры задаются в формате, поддерживаемом библиотекой +OpenSSL, например: +<example> + ssl_ciphers ALL:!ADH:!EXPORT56:RC4+RSA:+HIGH:+MEDIUM:+LOW:+SSLv2:+EXP; +</example> +</para> + +<para> +Полный список можно посмотреть с помощью команды +<command>openssl ciphers</command>. +</para> + +</directive> + + +<directive name="ssl_crl"> +<syntax>ssl_crl <value>файл</value></syntax> +<default>нет</default> +<context>http, server</context> + +<para> +Директива (0.8.7) указывает файл с отозванными сертификатами (CRL) +в формате PEM, используемыми для для проверки клиентских сертификатов. +</para> + +</directive> + + +<directive name="ssl_dhparam"> +<syntax>ssl_dhparam <value>файл</value></syntax> +<default>нет</default> +<context>http, server</context> + +<para> +Директива (0.7.2) указывает файл с параметрами для шифров с обменом EDH-ключами. +</para> + +</directive> + + +<directive name="ssl_prefer_server_ciphers"> +<syntax>ssl_prefer_server_ciphers <value>[on|off]</value></syntax> +<default>ssl_prefer_server_ciphers off</default> +<context>http, server</context> + +<para> +Директива указывает, чтобы при использовании протоколов SSLv3 и TLSv1 +серверные шифры были более приоритетны, чем клиентские. +</para> + +</directive> + + +<directive name="ssl_protocols"> +<syntax>ssl_protocols <value>[SSLv2] [SSLv3] [TLSv1]</value></syntax> +<default>ssl_protocols SSLv3 TLSv1</default> +<context>http, server</context> + +<para> +Директива разрешает указанные протоколы. +</para> + +</directive> + + +<directive name="ssl_verify_client"> +<syntax>ssl_verify_client <value>on|off|optional</value></syntax> +<default>ssl_verify_client off</default> +<context>http, server</context> + +<para> +Директива разрешает проверку клиентских сертификатов. +Параметр optional (0.8.7+) запрашивает сертификат клиента +и проверяет его, если он предоставлен. +Результат проверки можно узнать в переменной $ssl_client_verify. +</para> + +</directive> + + +<directive name="ssl_verify_depth"> +<syntax>ssl_verify_depth <value>число</value></syntax> +<default>ssl_verify_depth 1</default> +<context>http, server</context> + +<para> +Директива устанавливает глубину проверку в цепочке клиентских сертификатов. +</para> + +</directive> + + +<directive name="ssl_session_cache"> +<syntax>ssl_session_cache <value>off|none|[builtin[:размер]] [shared:название:размер] +</value></syntax> +<default>ssl_session_cache none</default> +<context>http, server</context> + +<para> +Директива задаёт тип и размеры кэшей для хранения параметров сессий. +Тип кэша может быть следующим: +<list type="bullet"> + +<listitem> +off — жёсткое запрещение использования кэша сессий: +nginx явно говорит клиенту, что сессии не могут использоваться повторно. +</listitem> + +<listitem> +none — мягкое запрещение использования кэша сессий: +nginx говорит клиенту, что сессии могут использоваться повторно, но +на самом деле не используются. +</listitem> + +<listitem> +builtin — встроенный в OpenSSL кэш, используется в рамках только +одного рабочего процесса. Размер кэша задаётся в сессиях. +Если размер не задан, то он равен 20480 сессиям. +Использование встроенного кэша может вести к фрагментации памяти. +</listitem> + +<listitem> +shared — разделяемый между всеми рабочими процессами. +Размер кэша задаётся в байтах, в 1 мегабайт может поместиться +около 4000 сессий. +У каждого разделяемого кэша должно быть произвольное название. +Кэш с одинаковым названием может использоваться в нескольких +виртуальных серверах. +</listitem> + +</list> +</para> + +<para> +Можно использовать одновременно оба типа кэша, например: +<example> +ssl_session_cache builtin:1000 shared:SSL:10m; +</example> +однако использование только разделяемого кэша без встроенного должно +быть более эффективным. +</para> + +</directive> + + +<directive name="ssl_session_timeout"> +<syntax>ssl_session_timeout <value>время</value></syntax> +<default>ssl_session_timeout 5m</default> +<context>http, server</context> + +<para> +Директива задаёт время, в течение которого клиент может повторно +использовать параметры сессии, хранящейся в кэше. +</para> + +</directive> + +</section> + + +<section name="Обработка ошибок" id="errors"> + +<para> +Модуль ngx_http_ssl_module поддерживает несколько нестандартных кодов ошибок, +которые можно использовать для перенаправления с помощью директивы <link doc="ngx_http_core_module.xml#error_page">error_page</link>: +<list type="bullet"> + +<listitem> +495 — при проверке клиентского сертификата произошла ошибка; +</listitem> + +<listitem> +496 — клиент не предоставил требуемый сертификат; +</listitem> + +<listitem> +497 — обычный запрос был послан на порт HTTPS. +</listitem> + +</list> +</para> + +<para> +Перенаправление делается после того, как запрос полностью разобран +и доступны такие переменные, как $request_uri, $uri, $arg и прочие. +</para> + +</section> + + +<section name="Встроенные переменные" id="variables"> + +<para> +Модуль ngx_http_ssl_module поддерживает несколько встроенных переменных: +<list type="bullet"> + +<listitem> +$ssl_cipher возвращает строку используемых шифров для установленного +SSL-соединения; +</listitem> + +<listitem> +$ssl_client_cert возвращает клиентский сертификат +для установленного SSL-соединения в формате PEM +перед каждой строкой которого, кроме первой, вставляется символ табуляции; +предназачен для использования в директиве <link doc="ngx_http_proxy_module.xml#proxy_set_header">proxy_set_header</link>. +</listitem> + +<listitem> +$ssl_client_raw_cert возвращает клиентский сертификат +для установленного SSL-соединения в формате PEM; +</listitem> + +<listitem> +$ssl_client_serial возвращает серийный номер клиентского сертификата +для установленного SSL-соединения; +</listitem> + +<listitem> +$ssl_client_s_dn возвращает строку subject DN клиентского сертификата +для установленного SSL-соединения; +</listitem> + +<listitem> +$ssl_client_i_dn возвращает строку issuer DN клиентского сертификата +для установленного SSL-соединения. +</listitem> + +<listitem> +$ssl_client_verify возвращает результат проверки клиентского сертификата: +"SUCCESS", "FAILED" и, если серфтикат не был предоставлен - "NONE". +</listitem> + +<listitem> +$ssl_protocol возвращает протокол установленного SSL-соединения; +</listitem> + +<listitem> +$ssl_session_id возвращает идентификатор сессии установленного SSL-соединения; +</listitem> + +</list> +</para> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_sub_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,79 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_sub_module" + link="/ru/docs/http/ngx_http_sub_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_sub_module — это фильтр, +изменяющий в ответе одну заданную строку на другую. +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром <command>--with-http_sub_module</command>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +location / { + sub_filter </head> + '</head><script language="javascript" src="$script"></script>'; + sub_filter_once on; +} +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="sub_filter"> +<syntax>sub_filter <value>строка замена</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт строку, которую нужно заменить, и строку замены. +Заменяемая строка проверяется без учёта регистра. +В строке замены можно использовать переменные. +</para> + +</directive> + + +<directive name="sub_filter_once"> +<syntax>sub_filter_once <value>on|off</value></syntax> +<default>sub_filter_once on</default> +<context>http, server, location</context> + +<para> +Директива определяет, сколько раз нужно искать заменяемую строку — один +раз или несколько. +</para> + +</directive> + + +<directive name="sub_filter_types"> +<syntax>sub_filter_types <value>mime-тип [mime-тип ...]</value></syntax> +<default>sub_filter_types text/html</default> +<context>http, server, location</context> + +<para> +Директива разрешает замену строк в ответах с указанными MIME-типами +в дополнение к "text/html". +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_upstream.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,241 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_upstream" + link="/ru/docs/http/ngx_http_upstream.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль позволяет описывать группы серверов, +которые могут использоваться в директивах +<link doc="ngx_http_proxy_module.xml#proxy_pass">proxy_pass</link> +и <link doc="ngx_http_fastcgi_module.xml#fastcgi_pass">fastcgi_pass</link>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +upstream <emphasis>backend</emphasis> { + server backend1.example.com weight=5; + server backend2.example.com:8080; + server unix:/tmp/backend3; + + server backup1.example.com:8080 backup; + server backup2.example.com:8080 backup; +} + +server { + location / { + proxy_pass http://<emphasis>backend</emphasis>; + } +} +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="ip_hash"> +<syntax>ip_hash</syntax> +<default>нет</default> +<context>upstream</context> + +<para> +Директива задаёт метод распределения запросов по серверам на основе +IP-адресов клиентов. В качестве ключа для хеширования используется сеть +класса C, в которой находится адрес клиента. +Метод гарантирует, что запросы клиента будут передаваться на один и тот же +сервер. Если же этот сервер будет считаться неработающим, то запросы этого +клиента будут передаваться на другой сервер. С большой долей вероятности +это также будет один и тот же сервер. +</para> + +<para> +Для серверов, использующих метод распределения ip_hash, нельзя задать вес. +Если один из серверов нужно убрать на некоторое время, то для сохранения +текущего хеширования IP-адресов клиентов этот сервер нужно пометить +параметром down. +</para> + +<para> +Пример конфигурации: +<example> +upstream backend { + ip_hash; + + server backend1.example.com; + server backend2.example.com; + server backend3.example.com down; + server backend4.example.com; +} +</example> +</para> + +</directive> + + +<directive name="server"> +<syntax>server <value>название [параметры]</value></syntax> +<default>нет</default> +<context>upstream</context> + +<para> +Директива задаёт имя и параметры сервера. +В качестве имени можно использовать доменное имя, адрес, порт или путь +unix-сокета. Если доменное имя резолвится в несколько адресов, то +используются все. +<list type="bullet"> + +<listitem> +weight=число — задаёт вес сервера, по умолчанию вес равен одному. +</listitem> + +<listitem> +max_fails=число — задаёт число неудачных попыток работы с сервером +в течение времени, заданного параметром fail_timeout, +после которых он считается неработающим также в течение времени +заданного параметром fail_timeout. +По умолчанию число попыток равно одной. +Нулевое значение запрещает учёт попыток. +Что считается неудачной попыткой, задаётся директивами +<link doc="ngx_http_proxy_module.xml#proxy_next_upstream">proxy_next_upstream</link> +и <link doc="ngx_http_fastcgi_module.xml#fastcgi_next_upstream">fastcgi_next_upstream</link>. +Состояние http_404 не считается неудачной попыткой. +</listitem> + +<listitem> +fail_timeout=время — задаёт +<list type="bullet"> + +<listitem> +время, в течение которого должно произойти заданное число неудачных +попыток работы с сервером для того, чтобы сервер считался неработающим; +</listitem> + +<listitem> +и время, в течение которого сервер будет считаться неработающим. +</listitem> + +</list> +По умолчанию время равно 10 секундам. +</listitem> + +<listitem> +backup — помечает сервер как запасной сервер. На него будут +передаваться запросы в случае, если не работают основные сервера. +</listitem> + +<listitem> +down — помечает сервер как постоянно неработающий, используется +совместно с директивой <link id="ip_hash"/>. +</listitem> + +</list> +</para> + +<para> +Пример конфигурации: +<example> +upstream backend { + server backend1.example.com weight=5; + server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; + server unix:/tmp/backend3; + + server backup1.example.com:8080 backup; +} +</example> +</para> + +</directive> + + +<directive name="upstream"> +<syntax>upstream <value>название</value> { ... }</syntax> +<default>нет</default> +<context>http</context> + +<para> +Директива описывает группу серверов. +Сервера могут слушать на разных портах, кроме того, можно одновременно +использовать сервера, слушающие на TCP и unix сокетах. +</para> + +<para> +Пример конфигурации: +<example> +upstream backend { + server backend1.example.com weight=5; + server 127.0.0.1:8080 max_fails=3 fail_timeout=30s; + server unix:/tmp/backend3; +} +</example> +</para> + +<para> +Запросы распределяются по серверам в режиме round-robin с учётом весов серверов. +В вышеприведённом примере каждые 7 семь запросов будут распределены так: +5 запросов на backend1.example.com и по одному запросу на второй и третий +сервера. +Если при попытке работы с сервером произошла ошибка, то запрос будет +передан следующему серверу и так до тех пор, пока не будут опробованы +все работающие сервера. Если не удастся получить успешный ответ +от всех серверов, то клиенту будет возвращён результат работы +с последним сервером. +</para> + +</directive> + +</section> + + +<section name="Встроенные переменные" id="variables"> + +<para> +Модуль ngx_http_upstream поддерживает следующие встроенные переменные: +<list type="bullet"> + +<listitem> +$upstream_addr — в переменной хранятся ip-адрес и порт сервера +или путь к unix-сокету. +Если при обработке запроса были сделаны обращения к нескольким серверам, +то их адреса разделяются запятой, например, +"192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock". +Если произошёл внутренний редирект от одной группы серверов на другую с помощью +"X-Accel-Redirect" или error_page, то эти группы серверов разделяются +двоеточием, например, +"192.168.1.1:80, 192.168.1.2:80, unix:/tmp/sock : 192.168.10.1:80, 192.168.10.2:80". +</listitem> + +<listitem> +$upstream_response_time — в переменной хранятся времена ответов серверов +в секундах с точностью до миллисекунд. +Несколько ответов также разделяются запятыми и двоеточиями. +</listitem> + +<listitem> +$upstream_status — в переменной хранятся коды ответов серверов. +Несколько ответов также разделяются запятыми и двоеточиями. +</listitem> + +<listitem> +$upstream_http_... — в переменных хранятся строки заголовков ответов +серверов, например, строка заголовка ответа "Server" доступна в переменной +$upstream_http_server. Необходимо иметь ввиду, что запоминаются только +строки последнего сервера. +</listitem> + +</list> +</para> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_userid_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,153 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_userid_module" + link="/ru/docs/http/ngx_http_userid_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_userid_module выдаёт сookies для идентификации клиентов. +Для записи в лог можно использовать переменные $uid_got и $uid_set. +Модуль совместим с модулем +<link url="http://www.lexa.ru/programs/mod-uid.html">mod_uid</link> +для Apache. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + userid on; + userid_name uid; + userid_domain example.com; + userid_path /; + userid_expires 365d; + userid_p3p 'policyref="/w3c/p3p.xml", CP="CUR ADM OUR NOR STA NID"'; +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="userid"> +<syntax>userid <value>[on|v1|log||off]</value></syntax> +<default>userid off</default> +<context>http, server, location</context> + +<para> +Разрешает или запрещает выдавать cookie и записывать приходящие cookie в лог: +<list type="bullet"> + +<listitem> +on — разрешает выдавать сookie версии 2 +и записывать приходящие cookie в лог; +</listitem> + +<listitem> +v1 — разрешает выдавать сookie версии 1 +и записывать приходящие cookie в лог; +</listitem> + +<listitem> +log — запрещает выдавать cookie, +но разрешает записывать приходящие cookie в лог; +</listitem> + +<listitem> +off — запрещает выдавать cookie и записывать приходящие cookie в лог; +</listitem> + +</list> +</para> + +</directive> + + +<directive name="userid_domain"> +<syntax>userid_domain <value>[имя|none]</value></syntax> +<default>userid_domain none</default> +<context>http, server, location</context> + +<para> +Директива задаёт домен, для которого устанавливается cookie. +Параметр "none" запрещает выдавать домен для cookie. +</para> + +</directive> + + +<directive name="userid_expires"> +<syntax>userid_expires <value>[время|max]</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт время, в течение которого браузер должен хранить cookie. +Параметр "max" задаёт время 31 декабря 2037 года 23:55:55 GMT. +Это максимальное время, которое понимают старые браузеры. +</para> + +</directive> + + +<directive name="userid_name"> +<syntax>userid_name <value>имя</value></syntax> +<default>userid_name uid</default> +<context>http, server, location</context> + +<para> +Директива задаёт имя cookie. +</para> + +</directive> + + +<directive name="userid_p3p"> +<syntax>userid_p3p <value>строка</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт значение для строки заголовка P3P, который будет +выдваться вместе с cookie. +</para> + +</directive> + + +<directive name="userid_path"> +<syntax>userid_path <value>путь</value></syntax> +<default>userid_path /</default> +<context>http, server, location</context> + +<para> +Директива задаёт путь, для которого устанавливается cookie. +</para> + +</directive> + + +<directive name="userid_service"> +<syntax>userid_service <value>число</value></syntax> +<default>userid_service IP-адрес сервера</default> +<context>http, server, location</context> + +<para> +Директива задаёт номер сервиса, выдавшего cookie. +По умолчанию для cookie первой версии используется ноль, +а для второй — IP-адрес сервера. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/http/ngx_http_xslt_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,124 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../../dtd/module.dtd"> + +<module name="Директивы модуля ngx_http_xslt_module" + link="/ru/docs/http/ngx_http_xslt_module.html" + lang="ru"> + +<section name="" id="summary"> + +<para> +Модуль ngx_http_xslt_module — это фильтр, преобразующий XML-ответ +с помощью одного или нескольких XSLT-шаблонов (0.7.8+). +По умолчанию модуль не собирается, нужно разрешить его сборку +при конфигурировании параметром <command>--with-http_xslt_module</command>. +Для сборки и работы этого модуля нужны библиотеки +<link url="http://www.xmlsoft.org">libxml2 и libxslt</link>. +</para> + +</section> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> +location / { + xml_entities /site/dtd/entities.dtd; + xslt_stylesheet /site/xslt/one.xslt param=value; + xslt_stylesheet /site/xslt/two.xslt; +} +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="xml_entities"> +<syntax>xml_entities <value>путь</value></syntax> +<default>нет</default> +<context>http, server, location</context> + +<para> +Директива задаёт файл DTD, в котором описаны символьные сущности. +Этот файл компилируется на стадии конфигурации. +По техническим причинам модуль не имеет возможности +использовать внешнее подмножество, заданное в обрабатываемом XML, +поэтому оно игнорируется, а вместо него используется специально заданный файл. +В этом файле не нужно описывать структуру XML, достаточно только объявления +необходимых символьных сущностей, например: +<example> +<!ENTITY nbsp "&#xa0;"> +</example> +</para> + +</directive> + + +<directive name="xslt_stylesheet"> +<syntax>xslt_stylesheet <value>шаблон [параметр ...]</value></syntax> +<default>нет</default> +<context>location</context> + +<para> +Директива задаёт XSLT-шаблон и параметры для этого шаблона. +Шаблон компилируется на стадии конфигурации. +Параметры задаются в формате +<example> +param=value +</example> +</para> + +<para> +Их можно задавать как по отдельности, так и группировать +в одной строке, разделяя символом ":". +Если же в самих параметрах встречается символ ":", то его нужно +экранировать в виде "%3A". +Кроме того, необходимо помнить о требовании libxslt, чтобы параметры, +содержащие не только алфавитно-цифровые символы, +были заключены в одинарные или двойные кавычки, например: +<example> +param1='http%3A//www.example.com':param2=value2 +</example> +</para> + +<para> +В описании параметров можно использовать переменные, например, +целая строка параметров может быть взята из одной переменной: +<example> +location / { + xslt_stylesheet /site/xslt/one.xslt + $arg_xslt_params + param1='$value1':param2=value2 + param3=value3; +} +</example> +</para> + +<para> +Можно указать несколько шаблонов — в этом случае они +будут применяться последовательно в порядке их описания. +</para> + +</directive> + +<directive name="xslt_types"> +<syntax>xslt_types <value>mime-тип [mime-тип ...]</value></syntax> +<default>xslt_types text/xml</default> +<context>http, server, location</context> + +<para> +Директива разрешает замену строк в ответах с указанными MIME-типами +в дополнение к "text/xml". +Если в результате преобразования выдаётся HTML-ответ, то его MIME-тип +меняется на "text/html". +</para> + +</directive> + +</section> + +</module>
--- a/xml/ru/docs/index.xml Mon Oct 10 14:47:09 2011 +0000 +++ b/xml/ru/docs/index.xml Tue Oct 11 12:57:50 2011 +0000 @@ -43,6 +43,218 @@ --> +<para> +<list> + +<item> +<a href="/ru/docs/ngx_core_module.xml" /> +</item> + +<item> +<para> +Директивы модулей http + +<list> + +<item> +<a href="/ru/docs/http/ngx_http_core_module.xml">ngx_http_core_module</a> +</item> + +<!-- + +<item> +<a href="/ru/docs/http/ngx_http_mp4_module.xml" /> +</item> + +--> + +<item> +<a href="/ru/docs/http/ngx_http_upstream.xml"> +ngx_http_upstream</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_access_module.xml"> +ngx_http_access_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_addition_module.xml"> +ngx_http_addition_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_auth_basic_module.xml"> +ngx_http_auth_basic_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_autoindex_module.xml"> +ngx_http_autoindex_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_browser_module.xml"> +ngx_http_browser_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_charset_module.xml"> +ngx_http_charset_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_dav_module.xml"> +ngx_http_dav_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_empty_gif_module.xml"> +ngx_http_empty_gif_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_fastcgi_module.xml"> +ngx_http_fastcgi_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_flv_module.xml"> +ngx_http_flv_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_geo_module.xml"> +ngx_http_geo_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_geoip_module.xml"> +ngx_http_geoip_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_gzip_module.xml"> +ngx_http_gzip_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_gzip_static_module.xml"> +ngx_http_gzip_static_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_headers_module.xml"> +ngx_http_headers_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_image_filter_module.xml"> +ngx_http_image_filter_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_index_module.xml"> +ngx_http_index_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_limit_zone_module.xml"> +ngx_http_limit_zone_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_limit_req_module.xml"> +ngx_http_limit_req_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_log_module.xml"> +ngx_http_log_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_map_module.xml"> +ngx_http_map_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_memcached_module.xml"> +ngx_http_memcached_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_perl_module.xml"> +ngx_http_perl_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_proxy_module.xml"> +ngx_http_proxy_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_random_index_module.xml"> +ngx_http_random_index_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_realip_module.xml"> +ngx_http_realip_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_referer_module.xml"> +ngx_http_referer_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_rewrite_module.xml"> +ngx_http_rewrite_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_secure_link_module.xml"> +ngx_http_secure_link_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_split_clients_module.xml"> +ngx_http_split_clients_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_ssi_module.xml"> +ngx_http_ssi_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_ssl_module.xml"> +ngx_http_ssl_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_sub_module.xml"> +ngx_http_sub_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_userid_module.xml"> +ngx_http_userid_module</a> +</item> + +<item> +<a href="/ru/docs/http/ngx_http_xslt_module.xml"> +ngx_http_xslt_module</a> +</item> + +</list> +</para> + +</item> +</list> +</para> + </section> </article>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/install.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,225 @@ +<!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> + +<article title="Установка nginx" + link="/ru/docs/install.html" + lang="ru"> + +<section> + +<para> +Конфигурация сборки осуществляется командой <command>configure</command>. +Она определяет особенности системы и, в частности, методы, которые nginx +может использовать для обработки соединений. +В конце концов она создаёт <command>Makefile</command>. +<command>configure</command> поддерживает следующие параметры: +<list> + +<listitem> +<para> +<command>--prefix=<<value>путь</value>></command>—задаёт каталог, +в котором будут находиться файлы сервера. +Этот же каталог будет использоваться для всех относительных путей, +задаваемых <command>./configure</command> (кроме путей к исходным текстам +библиотек) и в конфигурационном файле <command>nginx.conf</command>. +По умолчанию—каталог <command>/usr/local/nginx</command>. +</para> +</listitem> + +<listitem> +<para> +<command>--sbin-path=<<value>путь</value>></command>—задаёт +имя исполняемого файла nginx. +Это имя используется только на стадии установки. +По умолчанию файл называется +<command><<value>prefix</value>>/sbin/nginx</command>. +</para> +</listitem> + +<listitem> +<para> +<command>--conf-path=<<value>путь</value>></command>—задаёт +имя конфигурационного файла <command>nginx.conf</command>. +При желании nginx можно всегда запустить с другим конфигурационным файлом, +указав его в параметре командной строки +<nobr><command>-c <<value>файл</value>></command></nobr>. +По умолчанию файл называется +<command><<value>prefix</value>>/conf/nginx.conf</command>. +</para> +</listitem> + +<listitem> +<para> +<command>--pid-path=<<value>путь</value>></command>—задаёт +имя файла nginx.pid, в котором будет хранится номер главного процесса. +После установки имя файла можно всегда поменять в конфигурационном +файле <command>nginx.conf</command> с помощью директивы <dirname>pid</dirname>. +По умолчанию имя +файла—<command><<value>prefix</value>>/logs/nginx.pid</command>. +</para> +</listitem> + +<listitem> +<para> +<command>--error-log-path=<<value>путь</value>></command>—задаёт +имя основного файла ошибок, предупреждений и диагностики. +После установки имя файла можно всегда поменять в конфигурационном +файле <command>nginx.conf</command> с помощью директивы +<dirname>error_log</dirname>. +По умолчанию имя +файла—<command><<value>prefix</value>>/logs/error.log</command>. +</para> +</listitem> + +<listitem> +<para> +<command>--http-log-path=<<value>путь</value>></command>—задаёт +имя основного файла регистрации запросов http сервера. +После установки имя файла можно всегда поменять в конфигурационном +файле <command>nginx.conf</command> с помощью директивы +<dirname>access_log</dirname>. +По умолчанию имя +файла—<command><<value>prefix</value>>/logs/access.log</command>. +</para> +</listitem> + +<listitem> +<para> +<command>--user=<<value>имя</value>></command>—задаёт +имя непривилегированного пользователя, с правами которого будут +выполняться рабочие процессы. +После установки это имя можно всегда поменять в конфигурационном +файле <command>nginx.conf</command> с помощью директивы +<dirname>user</dirname>. +По умолчанию имя пользователя nobody. +</para> +</listitem> + +<listitem> +<para> +<command>--group=<<value>группа</value>></command>—задаёт +группу, с правами которой будут выполняться рабочие процессы. +После установки это имя можно всегда поменять в конфигурационном +файле <command>nginx.conf</command> с помощью директивы <dirname>user</dirname>. +По умолчанию группа совпадает с именем непривилегированного пользователя. +</para> +</listitem> + +<listitem> +<para> +<command>--with-select_module</command><br/> +<command>--without-select_module</command>—разрешает или запрещает +сборку модуля для работы сервера с помощью метода select. +Этот модуль собирается автоматически, если на платформе не обнаружено +более подходящего метода—kqueue, epoll, rtsig или /dev/poll. +</para> +</listitem> + +<listitem> +<para> +<command>--with-poll_module</command><br/> +<command>--without-poll_module</command>—разрешает или запрещает +сборку модуля для работы сервера с помощью метода poll. +Этот модуль собирается автоматически, если на платформе не обнаружено +более подходящего метода—kqueue, epoll, rtsig или /dev/poll. +</para> +</listitem> + +<listitem> +<para> +<command>--without-http_gzip_module</command>—запрещает сборку модуля +сжатия ответов http сервера. +Для сборки и работы этого модуля нужна библиотека zlib. +</para> +</listitem> + +<listitem> +<para> +<command>--without-http_rewrite_module</command>—запрещает сборку модуля +http сервера, позволяющего делать редиректы и менять URI запросов. +Для сборки и работы этого модуля нужна библиотека PCRE. +Модуль экспериментальный—директивы модуля впоследствии могут измениться. +</para> +</listitem> + +<listitem> +<para> +<command>--without-http_proxy_module</command>—запрещает сборку +проксирующего модуля http сервера. +<!-- +Для сборки и работы этого модуля нужна библиотека md5. +--> +</para> +</listitem> + +<listitem> +<para> +<command>--with-http_ssl_module</command>—разрешает сборку модуля +для работы http сервера по протоколу HTTPS. По умолчанию модуль не собирается. +Для сборки и работы этого модуля нужна библиотека OpenSSL. +</para> +</listitem> + +<listitem> +<para> +<command>--with-pcre=<<value>путь</value>></command>—задаёт +путь к исходным текстам библиотеки PCRE. Дистрибутив библиотеки (версию +4.4—6.1) нужно взять на сайте <link url="http://www.pcre.org">PCRE</link> +и распаковать. +Всё остальное сделают nginx'овские ./configure и make. +Библиотека нужна для использования регулярных выражений в +<dirname>location</dirname> и для модуля ngx_http_rewrite_module. +</para> +</listitem> + +<listitem> +<para> +<command>--with-zlib=<<value>путь</value>></command>—задаёт +путь к исходным текстам библиотеки zlib. Дистрибутив библиотеки (версию +1.1.3—1.2.2) нужно взять на сайте +<link url="http://www.gzip.org/zlib/">zlib</link> и распаковать. +Всё остальное сделают nginx'овские ./configure и make. +Библиотека нужна для модуля ngx_http_gzip_module. +</para> +</listitem> + +<listitem> +<para> +<command>--with-cc-opt=<<value>параметры</value>></command>—задаёт +дополнительные параметры, которые будут добавлены к переменной CFLAGS. +При использовании системной библиотеки PCRE во FreeBSD, нужно указать +<command>--with-cc-opt="-I /usr/local/include"</command>. +Если нужно увеличить число файлов, с которыми может работать select(), +то это тоже можно задать здесь же: +<command>--with-cc-opt="-D FD_SETSIZE=2048"</command>. +</para> +</listitem> + +<listitem> +<para> +<command>--with-ld-opt=<<value>параметры</value>></command>—задаёт +дополнительные параметры, которые будут использованы при линковке. +При использовании системной библиотеки PCRE во FreeBSD, нужно указать +<command>--with-ld-opt="-L /usr/local/lib"</command>. +</para> +</listitem> + +</list> + +</para> + +<para> +Пример использования параметров (всё это нужно набрать в одной строке): +<programlisting> +./configure + --sbin-path=/usr/local/nginx/nginx + --conf-path=/usr/local/nginx/nginx.conf + --pid-path=/usr/local/nginx/nginx.pid + --with-http_ssl_module + --with-pcre=../pcre-4.4 + --with-zlib=../zlib-1.1.3 +</programlisting> +</para> + +</section> + +</article>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/ngx_core_module.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,288 @@ +<?xml version="1.0" encoding="utf-8"?> + +<!DOCTYPE module SYSTEM "../../../dtd/module.dtd"> + +<module name="Глобальные директивы" + link="/ru/docs/ngx_core_module.html" + lang="ru"> + + +<section name="Пример конфигурации" id="example"> + +<para> +<example> + +user www www; +worker_processes 2; + +error_log /var/log/nginx-error.log info; + +events { + use kqueue; + worker_connections 2048; +} + +... +</example> +</para> + +</section> + + +<section name="Директивы" id="directives"> + +<directive name="daemon"> +<syntax>daemon <value>on|off</value></syntax> +<default>daemon on</default> +<context>main</context> + +<para> +Директива определяет, будет ли nginx запускаться в режиме демона. +Используется в основном для разработки. +</para> + +</directive> + + +<directive name="env"> +<syntax>env <value>VAR|VAR=VALUE</value></syntax> +<default>env TZ</default> +<context>main</context> + +<para> +Директива позволяет ограничить набор переменных среды, поменять им значения +или же создать новые переменные для следующих случаев: +<list type="bullet"> + +<listitem> +наследование переменных во время <link doc="../control.xml#upgrade">обновления исполняемого файла +на лету</link>; +</listitem> + +<listitem> +использование переменных модулем <link doc="ngx_http_perl_module.xml">ngx_http_perl_module</link>; +</listitem> + +<listitem> +использование переменных рабочими процессами. +Однако нужно иметь в виду, что управление поведением системных библиотек +подобным образом возможно не всегда, поскольку зачастую библиотеки используют +переменные только во время инициализации, то есть ещё до того, как их +можно задать с помощью данной директивы. +Исключением из этого является вышеописанное обновление исполняемого файла +на лету. +</listitem> + +</list> +</para> + +<para> +Если переменная TZ не описана явно, то она всегда наследуется +и всегда доступна модулю ngx_http_perl_module. +</para> + +<para> +Пример использования: +<example> +env MALLOC_OPTIONS; +env PERL5LIB=/data/site/modules; +env OPENSSL_ALLOW_PROXY_CERTS=1; +</example> +</para> + +</directive> + + +<directive name="include"> +<syntax>include <value>файл|маска</value></syntax> +<default>нет</default> +<context>везде</context> + +<para> +Директива позволяет включить в конфигурацию другой файл. +Файл должен содержать синтаксически законченные директивы и блоки. +</para> + +<para> +Пример использования: +<example> +include mime.types; +include vhosts/*.conf; +</example> +</para> + +</directive> + + +<directive name="master_process"> +<syntax>master_process <value>on|off</value></syntax> +<default>master_process on</default> +<context>main</context> + +<para> +Директива определяет, будут ли запускаться рабочие процессы. +Используется только для разработки. +</para> + +</directive> + + +<directive name="pid"> +<syntax>pid <value>файл</value></syntax> +<default>pid nginx.pid</default> +<context>main</context> + +<para> +Директива задаёт файл, в котором хранится номер основго процесса. +</para> + +</directive> + + +<directive name="ssl_engine"> +<syntax>ssl_engine <value>устройство</value></syntax> +<default>нет</default> +<context>main</context> + +<para> +Директива задаёт название аппартного SSL-акселератора. +</para> + +</directive> + + +<directive name="user"> +<syntax>user <value>пользователь [группа]</value></syntax> +<default>user nobody nobody</default> +<context>main</context> + +<para> +Директива задаёт пользователя и группу, с правами которого будут работать +рабочие процессы. Если группа не задана, то используется группа, имя +которой совпадает с именем пользователя. +</para> + +</directive> + + +<directive name="timer_resolution"> +<syntax>timer_resolution <value>время</value></syntax> +<default>нет</default> +<context>main</context> + +<para> +Директива уменьшает разрешение времени в рабочих процессах, за счёт +чего уменьшается число системных вызовов gettimeofday(). +По умолчанию gettimeofday() вызывается после каждой операции получения +событий из ядра. +C уменьшенным разрешением gettimeofday() вызывается только +один раз за указанный интервал. +</para> + +<para> +Пример использования: +<example> +timer_resolution 100ms; +</example> +</para> + +<para> +Внутренняя реализация интервала зависит от используемого метода: +<list type="bullet"> + +<listitem> +фильтр EVFILT_TIMER при использовании kqueue; +</listitem> + +<listitem> +timer_create() при использовании eventport; +</listitem> + +<listitem> +и setitimer() во всех остальных случаяx. +</listitem> + +</list> +</para> + +</directive> + + +<directive name="worker_rlimit_core"> +<syntax>worker_rlimit_core <value>размер</value></syntax> +<default>нет</default> +<context>main</context> + +<para> +Директива изменяет ограничение на размер core-файла RLIMIT_CORE +для рабочего процесса. +Используется для увеличения ограничения без перезапуска основного процесса. +</para> + +</directive> + + +<directive name="worker_rlimit_nofile"> +<syntax>worker_rlimit_nofile <value>число</value></syntax> +<default>нет</default> +<context>main</context> + +<para> +Директива изменяет ограничение на число используемых файлов RLIMIT_NOFILE +для рабочего процесса. +Используется для увеличения ограничения без перезапуска основного процесса. +</para> + +</directive> + + +<directive name="worker_priority"> +<syntax>worker_priority <value>число</value></syntax> +<default>worker_priority 0</default> +<context>main</context> + +<para> +Директива задаёт приоритет рабочих процессов подобно тому, +как это делается командой <command>nice</command>: +отрицательное число означает более высокий приоритет. +Диапазон возможных значений, как правило, от -20 до 20. +</para> + +<para> +Пример использования: +<example> +worker_priority -10; +</example> +</para> + +</directive> + + +<directive name="worker_processes"> +<syntax>worker_processes <value>число</value></syntax> +<default>worker_processes 1</default> +<context>main</context> + +<para> +Директива задаёт число рабочих процессов. +</para> + +</directive> + + +<directive name="working_directory"> +<syntax>working_directory <value>путь</value></syntax> +<default>нет</default> +<context>main</context> + +<para> +Директива задаёт каталог, который будет текущим для рабочего процесса. +Основное применение — запись core-файла, в этом случае рабочий +процесс должен иметь права на запись в этот каталог. +</para> + +</directive> + +</section> + +</module>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/switches.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,47 @@ +<!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> + +<article title="Параметры командной строки nginx" + link="/ru/docs/switches.html" + lang="ru"> + +<section> + +<para> +nginx поддерживает следующие параметры: +<list> + +<listitem> +<command>-c <<value>файл</value>></command>—указывает +использовать конфигурационный файл <<value>файл</value>> вместо файла +по умолчанию. +</listitem> + +<listitem> +<command>-g</command>—задаёт глобальные директивы конфигурации, +например, +<programlisting> +nginx -g "pid /var/run/nginx.pid; worker_processes `sysctl -n hw.ncpu`;" +</programlisting> +</listitem> + +<listitem> +<command>-t</command>—тестировать конфигурацию. nginx проверяет +синтаксическую правильность конфигурации, а затем пытается открыть файлы, +описанные в конфигурации. +</listitem> + +<listitem> +<command>-v</command>—показать версию nginx. +</listitem> + +<listitem> +<command>-V</command>—показать версию nginx, версию компилятора +и параметры конфигурации сборки. +</listitem> + +</list> +</para> + +</section> + +</article>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/syntax.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,45 @@ +<!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> + +<article title="Синтаксис конфигурационного файла" + link="/ru/docs/syntax.html" + lang="ru"> + +<section> + +<!-- + +<para lang="ru"> +<programlisting> + директива параметр [параметр ...]; +</programlisting> +</para> + +--> + +<para> +Размеры можно указывать в килобайтах и мегабайтах: +<table width="30%"> +<tr><td width="20%">k,K</td><td>килобайты</td></tr> +<tr><td width="20%">m,M</td><td>мегабайты</td></tr> +</table> +например, "8k", "1m". По умолчанию размер в байтах. +</para> + +<para> +Время можно указывать в минутах, часах, днях и так далее: +<table width="30%"> +<tr><td width="20%">ms</td><td>миллисекунды</td></tr> +<tr><td width="20%">s</td><td>секунды</td></tr> +<tr><td width="20%">m</td><td>минуты</td></tr> +<tr><td width="20%">h</td><td>часы</td></tr> +<tr><td width="20%">d</td><td>дни</td></tr> +<tr><td width="20%">w</td><td>недели</td></tr> +<tr><td width="20%">M</td><td>месяцы, 30 дней</td></tr> +<tr><td width="20%">y</td><td>годы, 365 дней</td></tr> +</table> +например, "1h 30m", "1y 6M". По умолчанию время в секундах. +</para> + +</section> + +</article>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/virtual_hosts.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,64 @@ +<!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> + +<article title="Настройка виртуальных серверов" + link="/ru/docs/virtual_hosts.html" + lang="ru"> + +<section> + +<para> +Настраивать виртуальные сервера очень просто. В каждом сервере нужно описать +все адреса и порты, на которых нужно принимать соединения для этого сервера, +и все имена серверов. Рассмотрим следующую конфигурацию: +<programlisting> +http { + + server { + listen 192.168.10.1; + listen 192.168.10.1:8000; + + server_name one.example.com www.one.example.com; + + ... + } + + server { + listen 192.168.10.1; + listen 192.168.10.2:8000; + listen 9000; + + server_name two.example.com www.two.example.com + three.example.com www.three.example.com; + + ... + } + + server { + listen 9000; + + server_name four.example.com www.four.example.com; + + ... + } + +} +</programlisting> +</para> + +<para> +При такой настройке запрос, пришедший на 192.168.10.1:80 с заголовком +"Host: www.three.example.com", будет обслужен вторым сервером. +Если в запросе нет заголовка "Host" или же в нём указано имя, неописанное +ни в одном сервере, слушающем на адресе и порту, на которые пришёл запрос, +то запрос будет обслужен сервером, у которого первым описаны эти адрес и порт. +Например, все запросы без заголовка "Host", пришедшие на 9000 порт, +будут обслужены вторым сервером (two.example.com). +То же самое произойдёт и с запросом с заголовком "Host: www.one.example.com", +пришедшим на 9000 порт. +Для гибкой настройки серверов по умолчанию можно использовать параметр +default в директиве listen. +</para> + +</section> + +</article>
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/xml/ru/docs/windows.xml Tue Oct 11 12:57:50 2011 +0000 @@ -0,0 +1,54 @@ +<!DOCTYPE article SYSTEM "../../../dtd/article.dtd"> + +<article title="Установка и использование под Windows" + link="/ru/docs/windows.html" + lang="ru"> + +<section> + +<para> +nginx/Windows работает с Win32 API (не эмуляция Cygwin). +В качестве метода обработки соединений используется select, +поэтому не стоит ожидать высокой производительности и масштабируемости: +пока это бета-версия. +На данный момент доступна практически вся функциональность, что и в nginx/Unix, +за исключением XSLT-фильтра, фильтра изображений, модуля geoip +и встроенного perl'а. +</para> + +<para> +Распаковываем дистрибутив на диск C:, переходим в каталог +nginx-<development_version/> и запускаем <command>nginx</command>: +<programlisting> +cd c:\ +unzip nginx-<development_version/>.zip +cd nginx-<development_version/> +start nginx +</programlisting> +</para> + +<para> +Если nginx не запустился, нужно смотреть причины в error_log. +Если же error_log не создался, то об этом сообщается в Event Log. +</para> + +<para> +nginx/Windows работает как обычное приложение (не сервис) и +управляется следующим образом: +<note> +<table> + +<tr><td width="20%">nginx -s stop</td><td>быстрое завершение</td></tr> +<tr><td width="20%">nginx -s quit</td><td>плавное завершение</td></tr> +<tr><td width="20%">nginx -s reload</td><td>изменение конфигурации, +запуск новых рабочих процессов с новой конфигурацией, +плавное завершение старых рабочих процессов</td></tr> +<tr><td width="20%">nginx -s reopen</td><td>переоткрытие лог-файлов</td></tr> + +</table> +</note> +</para> + +</section> + +</article>