+ + +An HTTP request is always connected to a location via the +loc_conf field of the ngx_http_request_t +structure. +This means that at any point the location configuration of any module can be +retrieved from the request by calling +ngx_http_get_module_loc_conf(r, module). +Request location may be changed several times throughout its lifetime. +Initially, a default server location of the default server is assigned to a +request. +Once a request switches to a different server (chosen by the HTTP +

Host

header or SSL SNI extension), the request switches to the +default location of that server as well. +The next change of the location takes place at the +NGX_HTTP_FIND_CONFIG_PHASE request phase. +At this phase a location is chosen by request URI among all non-named locations +configured for the server. +The +ngx_http_rewrite_module +may change the request URI at the +NGX_HTTP_REWRITE_PHASE request phase as a result of +rewrite and +return to the NGX_HTTP_FIND_CONFIG_PHASE phase for choosing a +new location based on the new URI. + + + +It is also possible to redirect a request to a new location at any point by +calling one of the functions +ngx_http_internal_redirect(r, uri, args) or +ngx_http_named_location(r, name). + + + +The function ngx_http_internal_redirect(r, uri, args) changes +the request URI and returns the request to the +NGX_HTTP_SERVER_REWRITE_PHASE phase. +The request proceeds with a server default location. +Later at NGX_HTTP_FIND_CONFIG_PHASE a new location is chosen +based on the new request URI. + + + +The following example performs an internal redirect with the new request +arguments. + + + +ngx_int_t +ngx_http_foo_redirect(ngx_http_request_t *r) +{ + ngx_str_t uri, args; + + ngx_str_set(&uri, "/foo"); + ngx_str_set(&args, "bar=1"); + + return ngx_http_internal_redirect(r, &uri, &args); +} + + + +The function ngx_http_named_location(r, name) redirects +a request to a named location. The name of the location is passed as the +argument. The location is looked up among all named locations of the current +server, after which the requests switches to the +NGX_HTTP_REWRITE_PHASE phase. + + + +The following example performs a redirect to a named location @foo. + + + +ngx_int_t +ngx_http_foo_named_redirect(ngx_http_request_t *r) +{ + ngx_str_t name; + + ngx_str_set(&name, "foo"); + + return ngx_http_named_location(r, &name); +} + + + +Both functions ngx_http_internal_redirect(r, uri, args) +and ngx_http_named_location(r, name) may be called when +a request already has some contexts saved in its ctx field +by nginx modules. These contexts could become inconsistent with the new +location configuration. To prevent inconsistency, all request contexts are +erased by both redirect functions. + + + +Redirected and rewritten requests become internal and may access the +internal +locations. Internal requests have the internal flag set. + + +