# HG changeset patch # User Ruslan Ermilov # Date 1315215650 0 # Node ID 4dbdfd9858637545fe06af510c408be038be90f0 # Parent 22364b1f61c9b509a847e5192387571034620998 Regenerate HTML for the previous revision. diff --git a/docs/html/http/ngx_http_core_module.html b/docs/html/http/ngx_http_core_module.html --- a/docs/html/http/ngx_http_core_module.html +++ b/docs/html/http/ngx_http_core_module.html @@ -1,10 +1,1151 @@ -ngx_http_core_module

Directives

client_body_buffer_size

syntax: client_body_buffer_size size
default: client_body_buffer_size 8k/16k
context: http, server, location

-Directive sets client request body buffer size. -If the request body is larger than the buffer, -then the whole body or some its part is written to temporary file. -By default buffer size is equal to 2 memory page sizes. +HTTP Core Module

Directives

syntax: + aio + on | + off | + sendfile
default: + aio off
context: + http, server, location
appeared in version: + 0.8.11

+Enables or disables the use of asynchronous file I/O (AIO) +on FreeBSD and Linux. +

+On FreeBSD, AIO is usable used starting from FreeBSD 4.3. +AIO can either be linked statically into a kernel: +

+options VFS_AIO
+
+or loaded dynamically as a kernel loadable module: +
+kldload aio
+

+In FreeBSD versions 5 and 6, enabling AIO statically, or dynamically +when booting the kernel, will cause the entire networking subsystem +to use the Giant lock that can impact overall performance negatively. +This limitation has been removed in FreeBSD 6.4-STABLE in 2009, and in +FreeBSD 7. +However, starting from FreeBSD 5.3, it's possible to enable AIO +without the penalty of running the networking subsystem under a +Giant lock - for this to work, the AIO module needs to be loaded +after the kernel has booted. +In this case, the following message will appear in +/var/log/messages

+WARNING: Network stack Giant-free, but aio requires Giant.
+Consider adding 'options NET_WITH_GIANT' or setting debug.mpsafenet=0
+
+and can safely be ignored. + +The requirement to use the Giant lock with AIO is related to the +fact that FreeBSD supports asynchronous calls +aio_read() +and +aio_write() +when working with sockets. +However, since nginx only uses AIO for disk I/O, no problems should arise. +

+For AIO to work, +sendfile +needs to be disabled: +

+location  /video/ {
+    sendfile        off;
+    aio             on;
+    output_buffers  1 64k;
+}
+

+In addition, starting from FreeBSD 5.2.1 and nginx 0.8.12, AIO can +also be used to pre-load data for sendfile(): +

+location  /video/ {
+    sendfile        on;
+    tcp_nopush      on;
+    aio             sendfile;
+}
+
+In this configuration, sendfile() is called with +the SF_NODISKIO flag which causes it not to +block on disk I/O and instead report back when the data are not in +memory; nginx then initiates an asynchronous data load by reading +one byte. The FreeBSD kernel then loads the first 128K bytes +of a file into memory, however next reads will only load data +in 16K chunks. This can be tuned using the +read_ahead +directive. +

+On Linux, AIO is usable starting from kernel version 2.6.22; +plus, it is also necessary to enable +directio, +otherwise reading will be blocking: +

+location  /video/ {
+    aio             on;
+    directio        512;
+    output_buffers  1 128k;
+}
+

+On Linux, +directio +can only be used for reading blocks that are aligned on 512-byte +boundaries (or 4K for XFS). +Reading of unaligned file's tail is still made in blocking mode. +The same holds true for byte range requests, and for FLV requests +not from the beginning of a file: reading of unaligned data at the +beginning and end of a file will be blocking. +There is no need to turn off +sendfile +explicitly as it is turned off automatically when +directio +is used. +

syntax: + alias path
default: + none
context: + location

+Defines a replacement for the specified location. +For example, with the following configuration +

+location  /i/ {
+    alias  /data/w3/images/;
+}
+
+the request of "/i/top.gif" will be responded +with the file "/data/w3/images/top.gif". +

+The path value can contain variables. +

+If alias is used inside a location defined +with a regular expression then such regular expression should +contain captures and alias should refer to +these captures (0.7.40), for example: +

+location ~ ^/users/(.+\.(?:gif|jpe?g|png))$ {
+    alias  /data/w3/images/$1;
+}
+

+When location matches the last part of the directive's value: +

+location  /images/ {
+    alias  /data/w3/images/;
+}
+
+it's better to use the +root +directive instead: +
+location  /images/ {
+    root   /data/w3;
+}
+

syntax: + client_body_in_file_only + on | + clean | + off
default: + client_body_in_file_only off
context: + http, server, location

+Determines whether nginx should save the entire client request body +into a file. +This directive can be used during debugging, or when using the +$request_body_file +variable, or the +$r->request_body_file +method of the +http_perl module. +

+When set to the value on, temporary files are not +removed after request processing. +

+The value clean will cause the temporary files +left after request processing to be removed. +

syntax: + client_body_in_single_buffer on | off
default: + client_body_in_single_buffer off
context: + http, server, location

+Determines whether nginx should save the entire client request body +in a single buffer. +The directive is recommended when using the +$request_body +variable, to save the number of copy operations involved. +

syntax: + client_body_buffer_size size
default: + client_body_buffer_size 8k/16k
context: + http, server, location

+Sets buffer size for reading client request body. +In case request body is larger than the buffer, +the whole body or only its part is written to a temporary file. + +By default, buffer size is equal to two memory pages. This is 8K on x86, other 32-bit platforms, and x86-64. It is usually 16K on other 64-bit platforms. -

sendfile

syntax: sendfile [on|off]
default: sendfile off
context: http, server, location

-Directive enables or disables sendfile() usage. -

+

syntax: + client_body_temp_path + path + [level1 + [level2 + [level3]]] +
default: + client_body_temp_path client_body_temp
context: + http, server, location

+Defines a directory for storing temporary files holding client request bodies. +Up to three-level subdirectory hierarchy can be used underneath the specified +directory. +For example, in the following configuration +

+client_body_temp_path  /spool/nginx/client_temp 1 2;
+
+a temporary file might look like this: +
+/spool/nginx/client_temp/7/45/00000123457
+

syntax: + client_body_timeout time
default: + client_body_timeout 60
context: + http, server, location

+Defines a timeout for reading client request body. +A timeout is only set between two successive read operations, +not for the transmission of the whole request body. +If a client does not transmit anything within this time, +the error +"Request time out" (408) +is returned. +

syntax: + client_header_buffer_size size
default: + client_header_buffer_size 1k
context: + http, server

+Sets buffer size for reading client request header. +For most requests, a buffer of 1K bytes is enough. +However, if a request includes long cookies, or comes from a WAP client, +it may not fit into 1K. +If a request line, or a request header line do not fit entirely into +this buffer then larger buffers are allocated, configured by the +large_client_header_buffers +directive. +

syntax: + client_header_timeout time
default: + client_header_timeout 60
context: + http, server

+Defines a timeout for reading client request header. +If a client does not transmit the entire header within this time, +the error +"Request time out" (408) +is returned. +

syntax: + client_max_body_size size
default: + client_max_body_size 1m
context: + http, server, location

+Sets the maximum allowed size of the client request body, +specified in the +Content-Length +request header line. +If size is greater than the configured value, the +"Request Entity Too Large" (413) +error is returned to a client. +Please be aware that +browsers cannot correctly display +this error. +

syntax: + default_type mime-type
default: + default_type text/plain
context: + http, server, location

+Defines a default MIME-type of a response. +

syntax: + directio size | off
default: + directio off
context: + http, server, location
appeared in version: + 0.7.7

+Enables the use of +the O_DIRECT flag (FreeBSD, Linux), +the F_NOCACHE flag (Mac OS X), +or the directio() function (Solaris), +when reading files that are larger than the specified size. +It automatically disables (0.7.15) the use of +sendfile +for a given request. +It could be useful for serving large files: +

+directio  4m;
+
+or when using aio on Linux. +

syntax: + directio_alignment size
default: + directio_alignment 512
context: + http, server, location
appeared in version: + 0.8.11

+Sets an alignment for +directio. +In most cases, a 512-byte alignment is enough, however, when +using XFS under Linux, it needs to be increased to 4K. +

syntax: + error_page + code ... + [=[response]] + uri
default: + none
context: + http, server, location, if in location

+Defines the URI that will be shown for the specified errors. +These directives are inherited from the previous level if and +only if there are no error_page directives on +the current level. +A URI value can contain variables. +

+Example usage: +

+error_page   404          /404.html;
+error_page   502 503 504  /50x.html;
+error_page   403          http://example.com/forbidden.html;
+

+Furthermore, it is possible to change the response code to another, for example: +

+error_page   404  =200  /empty.gif;
+

+If an error response is processed by a proxied server, or a FastCGI-server, +and the server may return different response codes (e.g., 200, 302, 401 +or 404), it is possible to respond with a returned code: +

+error_page   404  =  /404.php;
+

+If there is no need to change URI during redirection it is possible to redirect +error processing into a named location: +

+location / {
+    error_page   404  =  @fallback;
+}
+
+location @fallback {
+    proxy_pass   http://backend;
+}
+

syntax: + if_modified_since + off | + exact | + before
default: + if_modified_since exact
context: + http, server, location
appeared in version: + 0.7.24

+Specifies how to compare modification time of a response +with the time in the +If-Modified-Since +request header: + +

syntax: + internal
default: + none
context: + location

+Specifies that a given location can only be used for internal requests. +For external requests, the "Not found" (404) +error is returned. +Internal requests are the following: + +

+Example usage: +

+error_page   404   /404.html;
+
+location  /404.html {
+    internal;
+}
+

syntax: + keepalive_requests number
default: + keepalive_requests 100
context: + http, server, location
appeared in version: + 0.8.0

+Sets the maximum number of requests that can be +made through one keep-alive connection. +

syntax: + keepalive_timeout + time + [time] +
default: + keepalive_timeout 75
context: + http, server, location

+The first argument sets a timeout during which a keep-alive +client connection will stay open on the server side. +The optional second argument sets a value in the +"Keep-Alive: timeout=time" +response header. +Two arguments may differ. +

+The +"Keep-Alive: timeout=" +is understood by Mozilla and Konqueror. +MSIE will close keep-alive connection in about 60 seconds. +

syntax: + large_client_header_buffers number size
default: + large_client_header_buffers 4 4k/8k
context: + http, server

+Sets the maximum number and size of +buffers used when reading large client request headers. +A request line cannot exceed the size of one buffer, or the +"Request URI too large" (414) +error is returned. +A request header line cannot exceed the size of one buffer as well, or the +"Bad request" (400) +error is returned. +Buffers are allocated only on demand. +By default, the buffer size is equal to one memory page size. +It is either 4K or 8K, platform dependent. +If after the end of request processing a connection is transitioned +into the keep-alive state, these buffers are freed. +

syntax: + limit_except method ... { ... }
default: + none
context: + location

+Limits allowed HTTP methods inside a location. +The GET method also implies the HEAD method. +Access to other methods can be limited using the +http_access +and +http_auth_basic +modules directives: +

+limit_except  GET {
+    allow  192.168.1.0/32;
+    deny   all;
+}
+
+Please note that this will limit access to all methods +except GET and HEAD. +

syntax: + limit_rate rate
default: + none
context: + http, server, location, if in location

+Rate limits the transmission of a response to a client. +The rate is specified in bytes per second. + +The limit is per connection, so if a single client opens 2 connections, +an overall rate will be 2x more than specified. +

+This directive is not applicable if one wants to rate limit +a group of clients on the +server +level. +If that is the case, the desired limit can be specified in the +$limit_rate +variable: +

+server {
+
+    if ($slow) {
+        set $limit_rate  4k;
+    }
+
+    ...
+}
+

syntax: + limit_rate_after size
default: + none
context: + http, server, location, if in location
appeared in version: + 0.8.0

+Sets the initial amount after which the further transmission +of a response to a client will be rate limited. +

+Example: +

+location /flv/ {
+    flv;
+    limit_rate_after  500k;
+    limit_rate        50k;
+}
+

syntax: + listen + address[:port] + [default | default_server + [backlog=number] + [rcvbuf=size] + [sndbuf=size] + [accept_filter=filter] + [deferred] + [bind] + [ipv6only=on|off] + [ssl]] +
       listen + port + [default | default_server + [backlog=number] + [rcvbuf=size] + [sndbuf=size] + [accept_filter=filter] + [deferred] + [bind] + [ipv6only=on|off] + [ssl]] +
default: + listen *:80 | *:8000
context: + server

+Sets an address and a port, on which +the server will accept requests. +Only one of address or port can be +specified. +An address may also be a hostname, for example: +

+listen  127.0.0.1:8000;
+listen  127.0.0.1;
+listen  8000;
+listen  *:8000;
+listen  localhost:8000;
+
+IPv6 addresses (0.7.36) are specified in square brackets: +
+listen  [::]:8000;
+listen  [fe80::1];
+

+If only address is given, the port 80 is used. +

+If directive is not present then either the *:80 is used +if nginx runs with superuser privileges, or *:8000 otherwise. +

+The default parameter, if present, +will cause the server to become the default server for the specified +address:port pair. +If none of the directives have the default +parameter then the first server with the +address:port pair will be +the default server for this pair. +Starting from version 0.8.21 it is possible to use the +default_server +parameter. +

+A listen directive which has the default +parameter can have several additional parameters specific to system calls +listen() and bind(). +Starting from version 0.8.21, these parameters can be specified in any +listen directive, but only once for the given +address:port pair. +

+Example: +

+listen  127.0.0.1 default accept_filter=dataready backlog=1024;
+

syntax: + location [ + = | + ~ | + ~* | + ^~ | + @ + ] uri +{ ... }
default: + none
context: + server

+Sets a configuration based on a request URI. +A location can either be defined by a prefix string, or by a regular expression. +Regular expressions are specified by prepending them with the +"~*" prefix (for case-insensitive matching), or with the +"~" prefix (for case-sensitive matching). +To find a location matching a given request, nginx first checks +locations defined using the prefix strings (prefix locations). +Amongst them, the most specific one is searched. +Then regular expressions are checked, in the order of their appearance +in a configuration file. +A search terminates on the first match, and its corresponding +configuration is used. +If no match with a regular expression location is found then a +configuration of the most specific prefix location is used. +

+For case-insensitive operating systems such as Mac OS X and Cygwin, +the string matching ignores a case (0.7.7). +However, comparison is limited to one-byte locales. +

+Regular expressions can contain captures (0.7.40) that can later +be used in other directives. +

+If the most specific prefix location has the "^~" prefix +then regular expressions are not checked. +

+Also, using the "=" prefix it's possible to define +an exact match of URI and location. +If an exact match is found, the search terminates. +For example, if a "/" request happens frequently, +defining "location = /" will speed up the processing +of these requests, as search terminates right after the first +comparison. +

+In versions from 0.7.1 to 0.8.41, if a request matched the prefix +location without the "=" and "^~" +prefixes, the search also terminated and regular expressions were +not checked. +

+Let's illustrate the above by an example: +

+location  = / {
+    [ configuration A ]
+}
+
+location  / {
+    [ configuration B ]
+}
+
+location ^~ /images/ {
+    [ configuration C ]
+}
+
+location ~* \.(gif|jpg|jpeg)$ {
+    [ configuration D ]
+}
+
+The "/" request will match configuration A, +the "/documents/document.html" request - configuration B, +the "/images/1.gif" request - configuration C, and +the "/documents/1.jpg" request - configuration D. +

+The "@" prefix defines a named location. +Such a location isn't used for a regular request processing, but instead +used for request redirection. +

syntax: + log_not_found on | off
default: + log_not_found on
context: + http, server, location

+Enables or disables logging of errors about not found files into the +error_log. +

syntax: + log_subrequest on | off
default: + log_subrequest off
context: + http, server, location

+Enables or disables logging of subrequests into the +access_log. +

syntax: + merge_slashes on | off
default: + merge_slashes on
context: + http, server

+Enables or disables compression of two or more adjacent slashes +in a URI into a single slash. +

+Note that compression is essential for the correct prefix string +and regular expressions location matching. +Without it, the "//scripts/one.php" request would not match +

+location /scripts/ {
+    ...
+}
+
+and might be processed as a static file, +so it gets converted to "/scripts/one.php". +

+Turning the compression off can become necessary if a URI +contains base64-encoded names, since base64 uses the "/" character internally. +However, for security considerations, it's better to avoid turning off +the compression. +

+If a directive is specified on the +server +level, which is also a default server, its value will cover +all virtual servers listening on the same address and port. +

syntax: + msie_padding on | off
default: + msie_padding on
context: + http, server, location

+Enables or disables adding of comments to responses with status +greater than 400 for MSIE clients, to pad the response size to 512 bytes. +

syntax: + msie_refresh on | off
default: + msie_refresh off
context: + http, server, location

+Enables or disables issuing refreshes instead of redirects, for MSIE clients. +

syntax: + open_file_cache +max=N +[inactive=time] | +off
default: + open_file_cache off
context: + http, server, location

+Configures a cache that can store: +

+The directive has the following parameters: +

+Example: +

+open_file_cache          max=1000  inactive=20s;
+open_file_cache_valid    30s;
+open_file_cache_min_uses 2;
+open_file_cache_errors   on;

syntax: + open_file_cache_errors on | off
default: + open_file_cache_errors off
context: + http, server, location

+Enables or disables caching of file lookup errors by the +open_file_cache. +

syntax: + open_file_cache_min_uses number
default: + open_file_cache_min_uses 1
context: + http, server, location

+Sets the minimum number of file accesses during +the period configured by the inactive parameter +of the open_file_cache directive, +after which a file descriptor will remain open in the cache. +

syntax: + open_file_cache_valid time
default: + open_file_cache_valid 60
context: + http, server, location

+Sets a time after which +open_file_cache +elements should be validated. +

syntax: + optimize_server_names on | off
default: + optimize_server_names on
context: + http, server

+This directive is obsolete. +

+Enables or disables optimization of hostname checking in name-based +virtual servers. +In particular, the checking affects hostnames used in redirects. +If optimization is enabled, and all name-based servers listening on +the same address:port pair have identical configuration, then +names are not checked during request processing, and the first +server name is used in redirects. +In case redirects should use hostnames sent by clients, +optimization needs to be disabled. +

syntax: + port_in_redirect on | off
default: + port_in_redirect on
context: + http, server, location

+Enables or disables specifying the port in redirects issued by nginx. +

syntax: + read_ahead size
default: + read_ahead 0
context: + http, server, location

+Sets the amount of pre-reading when working with files, in the kernel. +

+On Linux, the +posix_fadvise(0, 0, 0, POSIX_FADV_SEQUENTIAL) +system call is used, so the size argument is ignored. +

+On FreeBSD, the +fcntl(O_READAHEAD,size) +system call is used, supported in FreeBSD 9.0-CURRENT. +FreeBSD 7 needs to be +patched. +

syntax: + recursive_error_pages on | off
default: + recursive_error_pages off
context: + http, server, location

+Enables or disables doing several redirects using the +error_page +directive. +

syntax: + reset_timedout_connection on | off
default: + reset_timedout_connection off
context: + http, server, location

+Enables or disables resetting of timed out connections. +The reset is performed as follows: before closing a socket, the +SO_LINGER +option is set on it with a timeout value of 0. +When the socket is closed, a client is sent TCP RST, and all memory +occupied by this socket is freed. +This avoids keeping of an already closed socket with filled buffers +for a long time, in a FIN_WAIT1 state. +

+It should be noted that timed out keep-alive connections are still +closed normally. +

syntax: + resolver address
default: + none
context: + http, server, location

+Sets the address of a name server, for example: +

+resolver  127.0.0.1;
+

syntax: + resolver_timeout time
default: + resolver_timeout 30s
context: + http, server, location

+Sets a timeout for name resolution, for example: +

+resolver_timeout  5s;
+

syntax: + root path
default: + root html
context: + http, server, location, if in location

+Sets the root directory for requests. +For example, with the following configuration +

+location  /i/ {
+    root  /data/w3;
+}
+
+the request of "/i/top.gif" will be responded +with the file "/data/w3/images/top.gif". +

+The path value can contain variables. +

+A path to the file is constructed by merely adding a URI to the value +of the root directive. +If a URI need to be modified, the +alias directive should be used. +

syntax: + satisfy all | any
default: + satisfy all
context: + location

+Allows access if any of the +http_access +or http_auth_basic +modules grant access. +

+location / {
+    satisfy  any;
+
+    allow  192.168.1.0/32;
+    deny   all;
+
+    auth_basic            "closed site";
+    auth_basic_user_file  conf/htpasswd;
+}
+

syntax: + satisfy_any on | off
default: + satisfy_any off
context: + location

+This directive was renamed to the satisfy directive. +

syntax: + send_timeout time
default: + send_timeout 60
context: + http, server, location

+Sets a timeout for transmitting a response to the client. +A timeout is only set between two successive write operations, +not for the transmission of the whole response. +If a client does not receive anything within this time, +a connection is closed. +

syntax: + sendfile on | off
default: + sendfile off
context: + http, server, location

+Enables or disables the use of +sendfile(). +

syntax: + server { ... }
default: + none
context: + http

+Sets a configuration for the virtual server. +There is no clean separation between IP-based (based on the IP address) +and name-based (based on the Host header string) +virtual servers. +Instead, the listen directives describe all +addresses and ports that should accept connections for a server, and the +server_name directive lists all server names. +An example configuration is provided in the + +Setting Up Virtual Servers document. +

syntax: + server_name name ...
default: + server_name hostname
context: + server

+Sets names of the virtual server, for example: +

+server {
+    server_name   example.com  www.example.com;
+}
+

+The first name becomes a primary server name. +By default, the machine's hostname is used. +Server names can include an asterisk ("*") +to replace the first or last part of a name: +

+server {
+    server_name   example.com  *.example.com  www.example.*;
+}
+

+The first two of the above mentioned names can be combined: +

+server {
+    server_name   .example.com;
+}
+

+It is also possible to use regular expressions in server names, +prepending the name with a tilde ("~"): +

+server {
+    server_name   www.example.com   ~^www\d+\.example\.com$;
+}
+

+Regular expressions can contain captures (0.7.40) that can later +be used in other directives: +

+server {
+    server_name   ~^(www\.)?(.+)$;
+
+    location / {
+        root  /sites/$2;
+    }
+}
+
+server {
+    server_name   _;
+
+    location / {
+        root  /sites/default;
+    }
+}
+

+Starting from version 0.8.25, named captures in regular expressions create +variables that can later be used in other directives: +

+server {
+    server_name   ~^(www\.)?(?<domain>.+)$;
+
+    location / {
+        root  /sites/$domain;
+    }
+}
+
+server {
+    server_name   _;
+
+    location / {
+        root  /sites/default;
+    }
+}
+

+Starting from version 0.7.11, it is possible to specify an empty name "": +

+server {
+    server_name   www.example.com   "";
+}
+
+It allows this server to process requests without the Host +header, instead of the default server for the given address:port pair. +

+The name checking order is as follows: +

  1. +full names +
  2. +names with the prefix mask - *.example.com +
  3. +names with the suffix mask - mail.* +
  4. +regular expressions +

syntax: + server_name_in_redirect on | off
default: + server_name_in_redirect on
context: + http, server, location

+Enables or disables the use of the primary server name, specified by the +server_name +directive, in redirects issued by nginx. +When disabled, the name from the Host request header string +is used. +If there's no such a string, an IP address of the server is used. +

syntax: + server_names_hash_max_size size
default: + server_names_hash_max_size 512
context: + http

+Sets the maximum size of the server names hash tables. +For more information, please refer to +Setting Up Hashes. +

syntax: + server_names_hash_bucket_size size
default: + server_names_hash_bucket_size 32/64/128
context: + http

+Sets the bucket size for the server names hash tables. +Default value depends on the size of the processor's cache line. +For more information, please refer to +Setting Up Hashes. +

syntax: + server_tokens on | off
default: + server_tokens on
context: + http, server, location

+Enables or disables emitting of nginx version in error messages and in the +Server response header string. +

syntax: + tcp_nodelay on | off
default: + tcp_nodelay on
context: + http, server, location

+Enables or disables the use of the TCP_NODELAY option. +The option is enabled only when a connection is transitioned into the +keep-alive state. +

syntax: + tcp_nopush on | off
default: + tcp_nopush off
context: + http, server, location

+Enables or disables the use of +the TCP_NOPUSH socket option on FreeBSD +or the TCP_CORK socket option on Linux. +Opitons are enables only when sendfile is used. +Enabling the option allows to +

syntax: + try_files file ... uri
       try_files file ... =code
default: + none
context: + location

+Checks the existence of files in the specified order, and uses +the first found file for request processing; the processing +is performed in this location's context. +It is possible to check the directory existence by specifying +the slash at the end of a name, e.g. "$uri/". +If none of the files were found, an internal redirect to the +uri specified by the last argument is made. +As of version 0.7.51, the last argument can also be a +code: +

+location / {
+    try_files      $uri  $uri/index.html  $uri.html  =404;
+}
+

+Example when proxying Mongrel: +

+location / {
+    try_files      /system/maintenance.html
+                   $uri  $uri/index.html  $uri.html
+                   @mongrel;
+}
+
+location @mongrel {
+    proxy_pass     http://mongrel;
+}
+

+Example for Drupal/FastCGI: +

+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;
+
+    ... other fastcgi_param's
+}
+
+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;
+
+    ... other fastcgi_param's
+}
+
+In the following example, +
+location / {
+    try_files      $uri  $uri/  @drupal;
+}
+
+the try_files directive is equivalent to +
+location / {
+    error_page     404 = @drupal;
+    log_not_found  off;
+}
+
+And here, +
+location ~ \.php$ {
+    try_files      $uri  @drupal;
+
+    fastcgi_pass   ...;
+
+    fastcgi_param  SCRIPT_FILENAME  /path/to$fastcgi_script_name;
+
+    ...
+}
+
try_files checks the existence of the PHP file +before passing the request to the FastCGI server. +

+Example for Wordpress and Joomla: +

+location / {
+    try_files      $uri  $uri/  @wordpress;
+}
+
+location ~ \.php$ {
+    try_files      $uri  @wordpress;
+
+    fastcgi_pass   ...;
+
+    fastcgi_param  SCRIPT_FILENAME  /path/to$fastcgi_script_name;
+    ... other fastcgi_param's
+}
+
+location @wordpress {
+    fastcgi_pass   ...;
+
+    fastcgi_param  SCRIPT_FILENAME  /path/to/index.php;
+    ... other fastcgi_param's
+}
+

diff --git a/docs/html/ngx_core_module.html b/docs/html/ngx_core_module.html new file mode 100644 --- /dev/null +++ b/docs/html/ngx_core_module.html @@ -0,0 +1,149 @@ +Core Module

Example Configuration

+user               www  www;
+worker_processes   2;
+
+error_log   /var/log/nginx-error.log  info;
+
+events {
+    use    kqueue;
+    worker_connections   2048;
+}
+
+...
+

Directives

syntax: + daemon on | off
default: + daemon on
context: + main

+Determines whether nginx should become a daemon. +Mainly used during development. +

syntax: + env VAR[=VALUE]
default: + env TZ
context: + main

+Allows to limit a set of environment variables, change their values, +or create new environment variables, for the following cases: +

+The TZ variable is always inherited and made available to the +http_perl +module, unless configured explicitly. +

+Usage example: +

+env  MALLOC_OPTIONS;
+env  PERL5LIB=/data/site/modules;
+env  OPENSSL_ALLOW_PROXY_CERTS=1;
+

syntax: + include file | mask
default: + none
context: + any

+Includes another file, or files matching the +specified mask, into configuration. +Included files should consist of +syntactically correct directives and blocks. +

+Usage example: +

+include  mime.types;
+include  vhosts/*.conf;
+

syntax: + master_process on | off
default: + master_process on
context: + main

+Determines whether worker processes are started. +This directive is intended for nginx developers. +

syntax: + pid file
default: + pid nginx.pid
context: + main

+Defines a file which will store the process ID of the main process. +

syntax: + ssl_engine device
default: + none
context: + main

+Defines the name of the hardware SSL accelerator. +

syntax: + user user [group]
default: + user nobody nobody
context: + main

+Defines user and group +credentials used by worker processes. +If group is omitted, a group whose name equals +that of user is used. +

syntax: + timer_resolution interval
default: + none
context: + main

+Reduces timer resolution in worker processes, thus reducing the +number of gettimeofday() system calls made. +By default, gettimeofday() is called each time +on receiving a kernel event. +With reduced resolution, gettimeofday() is only +called once per specified interval. +

+Example: +

+timer_resolution   100ms;
+

+An internal implementation of interval depends on the method used: +

syntax: + worker_rlimit_core size
default: + none
context: + main

+Changes the limit on the largest size of a core file +(RLIMIT_CORE) for worker processes. +Used to increase the limit without restarting the main process. +

syntax: + worker_rlimit_nofile number
default: + none
context: + main

+Changes the limit on the maximum number of open files +(RLIMIT_NOFILE) for worker processes. +Used to increase the limit without restarting the main process. +

syntax: + worker_priority number
default: + worker_priority 0
context: + main

+Defines a scheduling priority for worker processes like is +done by the nice: a negative +number +means higher priority. +Allowed range normally varies from -20 to 20. +

+Example: +

+worker_priority  -10;
+

syntax: + worker_processes number
default: + worker_processes 1
context: + main

+Defines the number of worker processes. +

syntax: + working_directory directory
default: + none
context: + main

+Defines a current working directory for a worker process. +It's primarily used for writing a core-file, in which case +a working process should have write permission for the +specified directory. +