+ + +aio + on | + off | + sendfile + +aio off +http +server +location + + +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. + + + + + + +alias path + +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; +} + + + + + + + +client_body_in_file_only + on | + clean | + off + +client_body_in_file_only off +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. + + + + + + +client_body_in_single_buffer on | off + +client_body_in_single_buffer off +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. + + + + -client_body_buffer_size size +client_body_buffer_size size client_body_buffer_size 8k/16k -http, server, location +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. +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. @@ -24,14 +257,1630 @@ It is usually 16K on other 64-bit platfo + +client_body_temp_path + path + [level1 + [level2 + [level3]]] + +client_body_temp_path client_body_temp +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 + + + + + + + +client_body_timeout time +client_body_timeout 60 +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 + +is returned. + + + + + + +client_header_buffer_size size +client_header_buffer_size 1k +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. + + + + + + +client_header_timeout time +client_header_timeout 60 +http +server + + +Defines a timeout for reading client request header. +If a client does not transmit the entire header within this time, +the error + +is returned. + + + + + + +client_max_body_size size +client_max_body_size 1m +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 + +error is returned to a client. +Please be aware that +browsers cannot correctly display +this error. + + + + + + +default_type mime-type +default_type text/plain +http +server +location + + +Defines a default MIME-type of a response. + + + + + + +directio size | off +directio off +http +server +location + + +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. + + + + + + +directio_alignment size +directio_alignment 512 +http +server +location + + +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. + + + + + + +error_page + code ... + [=[response]] + uri + + +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; +} + + + + + + + +if_modified_since + off | + exact | + before + +if_modified_since exact +http +server +location + + +Specifies how to compare modification time of a response +with the time in the +

If-Modified-Since

+request header: + + + + +off—the +

If-Modified-Since

request header is ignored (0.7.34); + + + +exact—exact match; + + + +before—modification time of a response is +less than or equal to the time in the

If-Modified-Since

+request header. + + + + + + + + + +internal + +location + + +Specifies that a given location can only be used for internal requests. +For external requests, the +error is returned. +Internal requests are the following: + + + + +requests redirected by the error_page directive; + + + +subrequests formed by the +include virtual +command of the +http_ssi module; + + + +requests changed by the +rewrite +directive of the +http_rewrite module. + + + + + + +Example usage: + +error_page 404 /404.html; + +location /404.html { + internal; +} + + + + + + + +keepalive_requests number +keepalive_requests 100 +http +server +location + + +Sets the maximum number of requests that can be +made through one keep-alive connection. + + + + + + +keepalive_timeout + time + [time] + +keepalive_timeout 75 +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. + + + + + + +large_client_header_buffers number size +large_client_header_buffers 4 4k/8k +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 + +error is returned. +A request header line cannot exceed the size of one buffer as well, or the + +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. + + + + + + +limit_except method ... { ... } + +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. + + + + + + +limit_rate rate + +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; + } + + ... +} + + + + + + + +limit_rate_after size + +http +server +location +if in location + + +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; +} + + + + + + + +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]] + +listen *:80 | *:8000 +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. + + + +backlog=number— +sets the backlog parameter in the +listen call. +By default, backlog equals -1 on FreeBSD +and 511 on other platforms. + + + +rcvbuf=size— +sets the SO_RCVBUF parameter for the listening socket. + + + +sndbuf=size— +sets the SO_SNDBUF parameter for the listening socket. + + + +accept_filter=filter— +sets the name of the accept filter. +This works only on FreeBSD, acceptable values are dataready +and httpready. +On receiving SIGHUP signal, an accept filter can only be +changed in recent versions of FreeBSD, starting from 6.0, 5.4-STABLE +and 4.11-STABLE. + + + +deferred— +instructs to use a deferred accept on Linux +using the TCP_DEFER_ACCEPT option. + + + +bind— +specifies to make a separate bind call for a given +address:port pair. +This is because nginx will only bind to +*:port +if there are several listen directives with +the same port and different addresses, and one of the +listen directives listens on all addresses +for the given port (*:port). +It should be noted that in this case a getsockname +system call will be made to determine an address that accepted a +connection. +If parameters backlog, rcvbuf, +sndbuf, accept_filter, or +deferred are used then for a given +address:port pair +a separate bind call will always be made. + + + +ipv6only=on|off— +this parameter (0.7.42) sets the value of the IPV6_V6ONLY +parameter for the listening socket. +This parameter can only be set once on start. + + + +ssl— +this parameter (0.7.14) does not relate to system calls +listen and bind, but allows to +specify that all connections accepted on this port should work in +the SSL mode. +This allows for a more compact configuration for the server operating +in both HTTP and HTTPS modes simultaneously. + +listen 80; +listen 443 default ssl; + + + + + + + +Example: + +listen 127.0.0.1 default accept_filter=dataready backlog=1024; + + + + + + + +location [ + = | + ~ | + ~* | + ^~ | + @ + ] uri +{ ... } + +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. + + + + + + + + +log_not_found on | off +log_not_found on +http +server +location + + +Enables or disables logging of errors about not found files into the +error_log. + + + + + + +log_subrequest on | off +log_subrequest off +http +server +location + + +Enables or disables logging of subrequests into the +access_log. + + + + + + +merge_slashes on | off +merge_slashes on +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. + + + + + + +msie_padding on | off +msie_padding on +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. + + + + + + +msie_refresh on | off +msie_refresh off +http +server +location + + +Enables or disables issuing refreshes instead of redirects, for MSIE clients. + + + + + + +open_file_cache +max=N +[inactive=time] | +off + +open_file_cache off +http +server +location + + +Configures a cache that can store: + + + +open file descriptors, their sizes and modification times; + + + +directory lookups; + + + +file lookup errors, such as "file not found", "no read permission", +and so on. +Caching of errors should be enabled separately by the +open_file_cache_errors +directive. + + + + + + +The directive has the following parameters: + + + +max— +sets the maximum number of elements in the cache; +on cache overflow the least recently used (LRU) elements get removed; + + + +inactive— +defines a time, after which the element gets removed from the cache +if there were no accesses to it during this time; +by default, it is 60 seconds; + + + +off—disables the cache. + + + + + + +Example: + +open_file_cache max=1000 inactive=20s; +open_file_cache_valid 30s; +open_file_cache_min_uses 2; +open_file_cache_errors on; + + + + + + + +open_file_cache_errors on | off +open_file_cache_errors off +http +server +location + + +Enables or disables caching of file lookup errors by the +open_file_cache. + + + + + + + + + +open_file_cache_min_uses number +open_file_cache_min_uses 1 +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. + + + + + + +open_file_cache_valid time +open_file_cache_valid 60 +http +server +location + + +Sets a time after which +open_file_cache +elements should be validated. + + + + + + + +optimize_server_names on | off +optimize_server_names on +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. + + + + + + +port_in_redirect on | off +port_in_redirect on +http +server +location + + +Enables or disables specifying the port in redirects issued by nginx. + + + + + + +read_ahead size +read_ahead 0 +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. + + + + + + +recursive_error_pages on | off +recursive_error_pages off +http +server +location + + +Enables or disables doing several redirects using the +error_page +directive. + + + + + + +reset_timedout_connection on | off +reset_timedout_connection off +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. + + + + + + +resolver address + +http +server +location + + +Sets the address of a name server, for example: + +resolver 127.0.0.1; + + + + + + + +resolver_timeout time +resolver_timeout 30s +http +server +location + + +Sets a timeout for name resolution, for example: + +resolver_timeout 5s; + + + + + + + +root path +root html +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. + + + + + + +satisfy all | any +satisfy all +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; +} + + + + + + + +satisfy_any on | off +satisfy_any off +location + + +This directive was renamed to the satisfy directive. + + + + + + +send_timeout time +send_timeout 60 +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. + + + + + -sendfile [on|off] +sendfile on | off sendfile off -http, server, location +http +server +location + + +Enables or disables the use of +sendfile. + + + + + + +server { ... } + +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. + + + + + + +server_name name ... +server_name hostname +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: + + + +full names + + + +names with the prefix mask—*.example.com + + + +names with the suffix mask—mail.* + + + +regular expressions + + + + + + + + + +server_name_in_redirect on | off +server_name_in_redirect on +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. + + + + + + +server_names_hash_max_size size +server_names_hash_max_size 512 +http -Directive enables or disables sendfile() usage. +Sets the maximum size of the server names hash tables. +For more information, please refer to +Setting Up Hashes. + + + + + + +server_names_hash_bucket_size size +server_names_hash_bucket_size 32/64/128 +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. + + + + + + +server_tokens on | off +server_tokens on +http +server +location + + +Enables or disables emitting of nginx version in error messages and in the +

Server

response header string. + + + + + + +tcp_nodelay on | off +tcp_nodelay on +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. + + + + + + +tcp_nopush on | off +tcp_nopush off +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 + + + +send the response header and the beginning of a file in one packet, +on Linux and FreeBSD 4.*; + + + +send a file in full packets. + + + + + + + + + +try_files file ... uri +try_files file ... =code + +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/xml/ngx_core_module.xml b/docs/xml/ngx_core_module.xml new file mode 100644 --- /dev/null +++ b/docs/xml/ngx_core_module.xml @@ -0,0 +1,293 @@ + + + + + + +

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

+ + +

+ + +daemon on | off +daemon on +main + + +Determines whether nginx should become a daemon. +Mainly used during development. + + + + + + +env VAR[=VALUE] +env TZ +main + + +Allows to limit a set of environment variables, change their values, +or create new environment variables, for the following cases: + + + +variable inheritance during a +live upgrade +of an executable file; + + + +use of variables by the +http_perl +module; + + + +use of variables by worker processes. +Please bear in mind that controlling system libraries in this way +isn't always possible as it's not uncommon for libraries to check +variables only during initialization, well before they can be set +using this directive. +An exception from this is an above mentioned +live upgrade +of an executable file. + + + + + + +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; + + + + + + +include file | mask + + + + +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; + + + + + + + +master_process on | off +master_process on +main + + +Determines whether worker processes are started. +This directive is intended for nginx developers. + + + + + + +pid file +pid nginx.pid +main + + +Defines a file which will store the process ID of the main process. + + + + + + +ssl_engine device + +main + + +Defines the name of the hardware SSL accelerator. + + + + + + +user user [group] +user nobody nobody +main + + +Defines user and group +credentials used by worker processes. +If group is omitted, a group whose name equals +that of user is used. + + + + + + +timer_resolution interval + +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: + + + +an EVFILT_TIMER filter if kqueue is used; + + + +timer_create if eventport is used; + + + +setitimer otherwise. + + + + + + + + + +worker_rlimit_core size + +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. + + + + + + +worker_rlimit_nofile number + +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. + + + + + + +worker_priority number +worker_priority 0 +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; + + + + + + + +worker_processes number +worker_processes 1 +main + + +Defines the number of worker processes. + + + + + + +working_directory directory + +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. + + + + +

+ +