# HG changeset patch
# User Ruslan Ermilov <ru@nginx.com>
# Date 1330521922 0
# Node ID 3a9f39341c7c56e41e4549ff26713195c903787a
# Parent  338c5aa982f8f954c37d8609240863308283f4a5
- Documented the "from" parameter of the "disable_symlinks" directive,
  and that read permissions on intermediate directories are no longer
  required on OSes that support opening directories for searching.

- Improved documentation of $document_root and $realpath_root.

diff -r 338c5aa982f8 -r 3a9f39341c7c xml/en/docs/http/ngx_http_core_module.xml
--- a/xml/en/docs/http/ngx_http_core_module.xml	Wed Feb 29 10:56:18 2012 +0000
+++ b/xml/en/docs/http/ngx_http_core_module.xml	Wed Feb 29 13:25:22 2012 +0000
@@ -465,10 +465,11 @@
 
 
 <directive name="disable_symlinks">
+<syntax><literal>off</literal></syntax>
 <syntax>
     <literal>on</literal> |
-    <literal>off</literal> |
-    <literal>if_not_owner</literal></syntax>
+    <literal>if_not_owner</literal>
+    [<literal>from</literal>=<value>prefix</value>]</syntax>
 <default>off</default>
 <context>http</context>
 <context>server</context>
@@ -476,12 +477,12 @@
 <appeared-in>1.1.15</appeared-in>
 
 <para>
-Determines how nginx treats symbolic links when opening files:
+Determines how symbolic links should be treated when opening files:
 <list type="tag">
 
 <tag-name><literal>off</literal></tag-name>
 <tag-desc>
-Symbolic links in the pathname are not processed specially.
+Symbolic links in the pathname are allowed and not checked.
 This is the default behavior.
 </tag-desc>
 
@@ -498,10 +499,31 @@
 points to have different owners.
 </tag-desc>
 
+<tag-name><literal>from</literal>=<value>prefix</value></tag-name>
+<tag-desc>
+When checking symbolic links
+(parameters <literal>on</literal> and <literal>if_not_owner</literal>),
+each component of the pathname is normally checked.
+If however the
+<literal>from</literal>=<value>prefix</value> is also given,
+symbolic links are checked only from the component of the pathname
+specified by <value>prefix</value>.
+The <value>prefix</value> value can contain variables.
+If a value is not a prefix of the checked pathname, the whole
+pathname is checked as if this parameter was not specified at all.
+</tag-desc>
+
 </list>
 </para>
 
 <para>
+Example:
+<example>
+disable_symlinks on from=$document_root;
+</example>
+</para>
+
+<para>
 This directive is only available on systems that have the
 <c-func>openat</c-func> and <c-func>fstatat</c-func> interfaces.
 This includes modern versions of FreeBSD, Linux, and Solaris.
@@ -510,10 +532,12 @@
 <para>
 Parameters <literal>on</literal> and <literal>if_not_owner</literal>
 add a processing overhead.
-Furthermore,
+<note>
+On systems that do not support opening directories for search only,
 the use of these parameters requires that
 worker processes be able to read all intermediate
 directories.
+</note>
 </para>
 
 </directive>
@@ -2565,7 +2589,8 @@
 
 <tag-name><var>$document_root</var></tag-name>
 <tag-desc>
-<link id="root"/> directive's value for the current request
+<link id="root"/> or <link id="alias"/> directive's value
+for the current request
 </tag-desc>
 
 <tag-name><var>$document_uri</var></tag-name>
@@ -2624,8 +2649,10 @@
 
 <tag-name><var>$realpath_root</var></tag-name>
 <tag-desc>
-<link id="root"/> directive's value
-for the current request, with all symbolic links resolved to real paths
+an absolute pathname corresponding to the
+<link id="root"/> or <link id="alias"/> directive's value
+for the current request,
+with all symbolic links resolved to real paths
 </tag-desc>
 
 <tag-name><var>$remote_addr</var></tag-name>
diff -r 338c5aa982f8 -r 3a9f39341c7c xml/ru/docs/http/ngx_http_core_module.xml
--- a/xml/ru/docs/http/ngx_http_core_module.xml	Wed Feb 29 10:56:18 2012 +0000
+++ b/xml/ru/docs/http/ngx_http_core_module.xml	Wed Feb 29 13:25:22 2012 +0000
@@ -454,10 +454,11 @@
 
 
 <directive name="disable_symlinks">
+<syntax><literal>off</literal></syntax>
 <syntax>
     <literal>on</literal> |
-    <literal>off</literal> |
-    <literal>if_not_owner</literal></syntax>
+    <literal>if_not_owner</literal>
+    [<literal>from</literal>=<value>префикс</value>]</syntax>
 <default>off</default>
 <context>http</context>
 <context>server</context>
@@ -471,7 +472,7 @@
 
 <tag-name><literal>off</literal></tag-name>
 <tag-desc>
-Символические ссылки в пути никак специально не обрабатываются.
+Символические ссылки в пути допускаются и не проверяются.
 Это стандартное поведение.
 </tag-desc>
 
@@ -484,14 +485,35 @@
 <tag-name><literal>if_not_owner</literal></tag-name>
 <tag-desc>
 Доступ к файлу запрещается, если любой компонент пути
-является символической ссылкой, и ссылка и объект, на
+является символической ссылкой, а ссылка и объект, на
 который она ссылается, имеют разных владельцев.
 </tag-desc>
 
+<tag-name><literal>from</literal>=<value>префикс</value></tag-name>
+<tag-desc>
+При проверке символических ссылок
+(параметры <literal>on</literal> и <literal>if_not_owner</literal>)
+обычно проверяется каждый элемент пути.
+Однако если дополнительно указан параметр
+<literal>from</literal>=<value>префикс</value>,
+символические ссылки проверяются лишь начиная с элемента пути,
+заданного префиксом.
+В значении префикса можно использовать переменные.
+Если значение не является префиксом проверяемого пути,
+путь проверяется целиком, как если бы этот параметр не был указан вовсе.
+</tag-desc>
+
 </list>
 </para>
 
 <para>
+Пример:
+<example>
+disable_symlinks on from=$document_root;
+</example>
+</para>
+
+<para>
 Эта директива доступна только на системах, в которых есть
 интерфейсы <c-func>openat</c-func> и <c-func>fstatat</c-func>.
 К таким системам относятся современные версии FreeBSD, Linux и Solaris.
@@ -500,10 +522,13 @@
 <para>
 Параметры <literal>on</literal> и <literal>if_not_owner</literal>
 требуют дополнительных затрат на обработку.
-Кроме того,
+<note>
+На системах, не поддерживающих операцию открытия каталогов только для поиска,
 использование этих параметров требует, чтобы
 рабочие процессы имели возможность читать все
 промежуточные каталоги.
+</note>
+
 </para>
 
 </directive>
@@ -2552,7 +2577,8 @@
 
 <tag-name><var>$document_root</var></tag-name>
 <tag-desc>
-значение директивы <link id="root"/> для текущего запроса
+значение директивы <link id="root"/> или <link id="alias"/>
+для текущего запроса
 </tag-desc>
 
 <tag-name><var>$document_uri</var></tag-name>
@@ -2611,8 +2637,10 @@
 
 <tag-name><var>$realpath_root</var></tag-name>
 <tag-desc>
-значение директивы <link id="root"/> для текущего запроса,
-при этом все символические ссылки преобразованы в реальные путь
+абсолютный путь, соответствующий
+значению директивы <link id="root"/> или <link id="alias"/>
+для текущего запроса,
+в котором все символические ссылки преобразованы в реальные пути
 </tag-desc>
 
 <tag-name><var>$remote_addr</var></tag-name>