en translation for execution order 10

Author: Kai Wu

en-uk/02-NginxDirectiveExecOrder10.tut

@@ -0,0 +1,249 @@
+= Nginx directive execution order (10) =
+
+After C<post-rewrite>, it is the C<preaccess> phase.
+Just as its name implies, the phase is called C<preaccess>
+simply because it is executed right before C<access> phase.
+
+Built-in module L<ngx_limit_req> and L<ngx_limit_zone> are
+executed in this phase. The former limits the number of
+requests per hour/minute, and the latter limits the number
+of simultaneous requests. We will be discussing them more
+thoroughly afterwards.
+
+Actually, built-in module L<ngx_realip> registers its
+handler in C<preaccess> as well. You might need to ask
+then: "why do it again? Did it register its handlers in
+C<post-read> phase already". Before the answer is uncovered
+let's study following example:
+
+    :nginx
+    server {
+        listen 8080;
+
+        location /test {
+            set_real_ip_from 127.0.0.1;
+            real_ip_header X-Real-IP;
+
+            echo "from: $remote_addr";
+        }
+    }
+
+Comparing to the earlier example, the major difference is
+that commands of module L<ngx_realip> are written in a
+specific C<location> directive. As we have learnt before,
+Nginx matches its C<location> directives in C<find-config>
+phase, which is far behind C<post-read>, hence the request
+has nothing to do with commands written in any C<location>
+directive in C<post-read> phase. Back to our example,
+it is exactly the case where commands are written in a
+C<location> directive and module L<ngx_realip> won't carry
+out any rewrite of the remote address, because it is not
+instructed as such in C<post-read> phase.
+
+What if we do need the rewrite? To help resolve the issue,
+module L<ngx_realip> registers its handlers in C<preaccess>
+again, so that it is given the chance to execute in a
+C<location> directive. Now the example runs as we would've
+expected:
+
+    $ curl -H 'X-Real-IP: 1.2.3.4' localhost:8080/test
+    from: 1.2.3.4
+
+Be really careful though, module L<ngx_realip> could easily
+be misused, as our following example illustrates:
+
+    :nginx
+    server {
+        listen 8080;
+
+        location /test {
+            set_real_ip_from 127.0.0.1;
+            real_ip_header X-Real-IP;
+
+            set $addr $remote_addr;
+            echo "from: $addr";
+        }
+    }
+
+In the example, we introduces a variable C<$addr>, to which
+the value of L<ngx_core/$remote_addr> is saved in C<rewrite>
+phase. The variable is then used in the output. Slow down
+right here and you might have noticed the issue, phase C<rewrite>
+occurs earlier than C<preaccess>, so variable assignment
+actually happens before module L<ngx_realip> has the chance
+to rewrite the remote address in C<preaccess> phase. The
+output proves our observation:
+
+    :bash
+    $ curl -H 'X-Real-IP: 1.2.3.4' localhost:8080/test
+    from: 127.0.0.1
+
+The output gives the actual remote address (not the rewritten one)
+Again Nginx "debug log" helps assert it too:
+
+    :bash
+    $ grep -E 'http script (var|set)|realip' logs/error.log
+    [debug] 32488#0: *1 http script var: "127.0.0.1"
+    [debug] 32488#0: *1 http script set $addr
+    [debug] 32488#0: *1 realip: "1.2.3.4"
+    [debug] 32488#0: *1 realip: 0100007F FFFFFFFF 0100007F
+    [debug] 32488#0: *1 http script var: "127.0.0.1"
+
+Among the logs, the first line writes:
+
+    :text
+    [debug] 32488#0: *1 http script var: "127.0.0.1"
+
+The log is generated when variable L<ngx_core/$remote_addr>
+is fetched by command L<ngx_rewrite/set>, string C<"127.0.0.1">
+is the fetched value.
+
+The second line writes:
+
+    :text
+    [debug] 32488#0: *1 http script set $addr
+
+It indicates Nginx assigns value to variable C<$addr>.
+
+For the following two lines:
+
+    :text
+    [debug] 32488#0: *1 realip: "1.2.3.4"
+    [debug] 32488#0: *1 realip: 0100007F FFFFFFFF 0100007F
+
+They are generated when module L<ngx_realip> rewrites
+the remote address in C<preaccess> phase. As we can tell,
+the new address becomes C<1.2.3.4> as expected but it
+happens only after the variable assignment and that's
+already too late.
+
+Now the last line:
+
+    :text
+    [debug] 32488#0: *1 http script var: "127.0.0.1"
+
+It is generated when command L<ngx_echo/echo> outputs
+variable C<$addr>, clearly the value is the original
+remote address, not the rewritten one.
+
+Some people might come up with a solution immediately:"
+what if module L<ngx_realip> registers its handlers in
+C<rewrite> phase instead, not in C<preacccess> phase ?"
+The solution however is, not necessarily correct. This is
+because module L<ngx_rewrite> registers its handlers in
+C<rewrite> phase too, and we have learnt in L<ordertut/(02)>
+that the execution order, under the circumstances, can
+not be guaranteed, so there is a good chance that
+module L<ngx_realip> still executes its commands after
+command L<ngx_rewrite/set>.
+
+Always we have the backup option: instead of C<preaccess>,
+try use L<ngx_realip> module in C<server> directive, it
+bypasses the bothersome situations encountered above.
+
+After phase C<preaccess>, it is another old friend, the
+C<access> phase. As we've learnt, built-in module L<ngx_access>,
+3rd party module L<ngx_auth_request> and 3rd party module
+L<ngx_lua> (L<ngx_lua/access_by_lua>) have their commands
+executed in this phase.
+
+After phase C<access>, it is the C<post-access> phase. Again
+as the name implies, we can easily spot that the phase is
+executed right after C<access> phase. Similar to C<post-rewrite>,
+the phase does not allow Nginx module to register their
+handlers, instead it runs a few tasks by Nginx core, among
+them, primarily is the L<ngx_core/satisfy> functionality, provided
+by module L<ngx_http_core>.
+
+When multiple Nginx module execute their commands in C<access>
+phase, command L<ngx_core/satisfy> controls their relationships
+in between. For example, both module A and module B register
+their access control handlers in C<access> phase, we may have
+two working modes, one is to let access when both A and B pass
+their control, the other is to let access when either A or B
+pass their control. The first one is called C<all> mode ("AND"
+relation), the second one is called C<any> mode ("OR" relation)
+By default, Nginx uses C<all> mode, below is an example:
+
+    :nginx
+    location /test {
+        satisfy all;
+
+        deny all;
+        access_by_lua 'ngx.exit(ngx.OK)';
+
+        echo something important;
+    }
+
+Under C</test> directive, both L<ngx_access> and
+L<ngx_lua> are used, so we have two modules monitoring
+access in C<access> phase. Specifically, statement
+C<deny all> tells module L<ngx_access> to rejects all
+access, whereas statement C<access_by_lua 'ngx.exit(ngx.OK)'>
+allows all access. When C<all> mode is used with command
+L<ngx_core/satisfy>, it means to let access only if every
+module allows access. Since module L<ngx_access> always
+rejects in our case, the request is rejected:
+
+    :bash
+    $ curl localhost:8080/test
+    <html>
+    <head><title>403 Forbidden</title></head>
+    <body bgcolor="white">
+    <center><h1>403 Forbidden</h1></center>
+    <hr><center>nginx</center>
+    </body>
+    </html>
+
+Careful readers might find following error log in the Nginx
+error log file:
+
+    :text
+    [error] 6549#0: *1 access forbidden by rule
+
+If however, we change the C<satisfy all> statement to C<satisfy
+any>.
+
+    :nginx
+    location /test {
+        satisfy any;
+
+        deny all;
+        access_by_lua 'ngx.exit(ngx.OK)';
+
+        echo something important;
+    }
+
+The outcome is completely different:
+
+    :bash
+    $ curl localhost:8080/test
+    something important
+
+The request is allowed to access. Because overall
+access is allowed whenever one module passes the control
+in C<any> mode. In our example, module L<ngx_lua>
+and its command L<ngx_lua/access_by_lua> always allow
+the access.
+
+Certainly, if every module rejects the access in the
+C<satisfy any> circumstances, the request will be rejected:
+
+    :nginx
+    location /test {
+        satisfy any;
+
+        deny all;
+        access_by_lua 'ngx.exit(ngx.HTTP_FORBIDDEN)';
+
+        echo something important;
+    }
+
+Now request to C</test> will encounter C<403 Forbidden>
+error page. In the process, the "OR" relation of access
+control of each C<access> module, is implemented in
+C<post-access>.
+
+Be careful though, above example requires the version of
+L<ngx_lua> be 0.5.0rc19 or above, its predecessors cannot
+work together with C<satisfy any> statement.