# HG changeset patch # User Roman Arutyunyan # Date 1499255918 -10800 # Node ID c559be34257b6b4395df0d0a304d6dc81acda4d9 # Parent b13d6412b335a02a6c98cb91db246b8571c9d522 DevGuide: language and style fixes, second part. diff --git a/xml/en/docs/dev/development_guide.xml b/xml/en/docs/dev/development_guide.xml --- a/xml/en/docs/dev/development_guide.xml +++ b/xml/en/docs/dev/development_guide.xml @@ -2736,8 +2736,8 @@ Signal handlers only set global variable There are several types of processes in nginx. -The type of current process is kept in the ngx_process -global variable: +The type of a process is kept in the ngx_process +global variable, and is one of the following: @@ -2745,56 +2745,57 @@ global variable: -NGX_PROCESS_MASTER — the master process runs the -ngx_master_process_cycle() function. -Master process does not have any I/O and responds only to signals. -It reads configuration, creates cycles, starts and controls child processes - - - - - - - - -NGX_PROCESS_WORKER — the worker process runs the -ngx_worker_process_cycle() function. -Worker processes are started by master and handle client connections. -They also respond to signals and channel commands, sent from master - - - - - - - - -NGX_PROCESS_SINGLE — single process is the only type -of processes which exist in the master_process off mode. -The cycle function for this process is -ngx_single_process_cycle(). -This process creates cycles and handles client connections - - - - - - - - -NGX_PROCESS_HELPER — currently, there are two types of -helper processes: cache manager and cache loader. -Both of them share the same cycle function +NGX_PROCESS_MASTER — The master process, which reads the +NGINX configuration, creates cycles, and starts and controls child processes. +It does not perform any I/O and responds only to signals. +Its cycle function is ngx_master_process_cycle(). + + + + + + + + +NGX_PROCESS_WORKER — The worker process, which handles client +connections. +It is started by the master process and responds to its signals and channel +commands as well. +Its cycle function is ngx_worker_process_cycle(). +There can be multiple worker processes, as configured by the +worker_processes directive. + + + + + + + +NGX_PROCESS_SINGLE — The single process, which exists only in +master_process off mode, and is the only process running in +that mode. +It creates cycles (like the master process does) and handles client connections +(like the worker process does). +Its cycle function is ngx_single_process_cycle(). + + + + + + + +NGX_PROCESS_HELPER — The helper process, of which currently +there are two types: cache manager and cache loader. +The cycle function for both is ngx_cache_manager_process_cycle(). - -All nginx processes handle the following signals: +The nginx processes handle the following signals: @@ -2802,96 +2803,100 @@ All nginx processes handle the following -NGX_SHUTDOWN_SIGNAL (SIGQUIT) — graceful -shutdown. -Upon receiving this signal master process sends shutdown signal to all child -processes. -When no child processes are left, master destroys cycle pool and exits. -A worker process which received this signal, closes all listening sockets and -waits until timeout tree becomes empty, then destroys cycle pool and exits. -A cache manager process exits right after receiving this signal. -The variable ngx_quit is set to one after receiving this -signal and immediately reset after being processed. -The variable ngx_exiting is set to one when worker process -is in shutdown state - - - - - - - - -NGX_TERMINATE_SIGNAL (SIGTERM) - -terminate. -Upon receiving this signal master process sends terminate signal to all child -processes. -If child processes do not exit in 1 second, they are killed with the -SIGKILL signal. -When no child processes are left, master process destroys cycle pool and exits. -A worker or cache manager process which received this signal destroys cycle -pool and exits. -The variable ngx_terminate is set to one after receiving -this signal - - - - - - - - -NGX_NOACCEPT_SIGNAL (SIGWINCH) -- gracefully shut down worker processes - - - - - - - - -NGX_RECONFIGURE_SIGNAL (SIGHUP) - -reconfigure. -Upon receiving this signal master process creates a new cycle from -configuration file. -If the new cycle was created successfully, the old cycle is deleted and new +NGX_SHUTDOWN_SIGNAL (SIGQUIT on most +systems) — Gracefully shutdown. +Upon receiving this signal, the master process sends a shutdown signal to all +child processes. +When no child processes are left, the master destroys the cycle pool and exits. +When a worker process receives this signal, it closes all listening sockets and +waits until there are no non-cancelable events scheduled, then destroys the +cycle pool and exits. +When the cache manager or the cache loader process receives this signal, it +exits immediately. +The ngx_quit variable is set to 1 when a +process receives this signal, and is immediately reset after being processed. +The ngx_exiting variable is set to 1 while +a worker process is in the shutdown state. + + + + + + + +NGX_TERMINATE_SIGNAL (SIGTERM on most +systems) — Terminate. +Upon receiving this signal, the master process sends a terminate signal to all +child processes. +If a child process does not exit within 1 second, the master process sends the +SIGKILL signal to kill it. +When no child processes are left, the master process destroys the cycle pool and +exits. +When a worker process, the cache manager process or the cache loader process +receives this signal, it destroys the cycle pool and exits. +The variable ngx_terminate is set to 1 +when this signal is received. + + + + + + + +NGX_NOACCEPT_SIGNAL (SIGWINCH on most +systems) - Shut down all worker and helper processes. +Upon receiving this signal, the master process shuts down its child processes. +If a previously started new nginx binary exits, the child processes of the old +master are started again. +When a worker process receives this signal, it shuts down in debug mode +set by the debug_points directive. + + + + + + + + +NGX_RECONFIGURE_SIGNAL (SIGHUP on most +systems) - Reconfigure. +Upon receiving this signal, the master process re-reads the configuration and +creates a new cycle based on it. +If the new cycle is created successfully, the old cycle is deleted and new child processes are started. -Meanwhile, the old processes receive the shutdown signal. -In single-process mode, nginx creates a new cycle as well, but keeps the old -one until all clients, tied to the old cycle, are gone. -Worker and helper processes ignore this signal - - - - - - - - -NGX_REOPEN_SIGNAL (SIGUSR1) — reopen -files. -Master process passes this signal to workers. -Worker processes reopen all open_files from the cycle - - - - - - - - -NGX_CHANGEBIN_SIGNAL (SIGUSR2) — change -nginx binary. -Master process starts a new nginx binary and passes there a list of all listen +Meanwhile, the old child processes receive the +NGX_SHUTDOWN_SIGNAL signal. +In single-process mode, nginx creates a new cycle, but keeps the old one until +there are no longer clients with active connections tied to it. +The worker and helper processes ignore this signal. + + + + + + + +NGX_REOPEN_SIGNAL (SIGUSR1 on most +systems) — Reopen files. +The master process sends this signal to workers, which reopen all +open_files related to the cycle. + + + + + + + +NGX_CHANGEBIN_SIGNAL (SIGUSR2 on most +systems) — Change the nginx binary. +The master process starts a new nginx binary and passes in a list of all listen sockets. -The list is passed in the environment variable “NGINX” in -text format, where descriptor numbers separated with semicolons. -A new nginx instance reads that variable and adds the sockets to its init -cycle. -Other processes ignore this signal - - +The text-format list, passed in the “NGINX” environment +variable, consists of descriptor numbers separated with semicolons. +The new nginx binary reads the “NGINX” variable and adds the +sockets to its init cycle. +Other processes ignore this signal. + @@ -2899,24 +2904,12 @@ Other processes ignore this signal While all nginx worker processes are able to receive and properly handle POSIX -signals, master process normally does not pass any signals to workers and -helpers with the standard kill() syscall. -Instead, nginx uses inter-process channels which allow sending messages between -all nginx processes. -Currently, however, messages are only sent from master to its children. -Those messages carry the same signals. -The channels are socketpairs with their ends in different processes. - - - -When running nginx binary, several values can be specified next to --s parameter. -Those values are stop, quit, -reopen, reload. -They are converted to signals NGX_TERMINATE_SIGNAL, -NGX_SHUTDOWN_SIGNAL, NGX_REOPEN_SIGNAL -and NGX_RECONFIGURE_SIGNAL and sent to the nginx master -process, whose pid is read from nginx pid file. +signals, the master process does not use the standard kill() +syscall to pass signals to workers and helpers. +Instead, nginx uses inter-process socket pairs which allow sending messages +between all nginx processes. +Currently, however, messages are only sent from the master to its children. +The messages carry the standard signals. @@ -2924,50 +2917,99 @@ process, whose pid is read from nginx pi
-It is possible to offload tasks that would otherwise block nginx worker process -into a separate thread. -For example, nginx may be configured to use threads to perform +It is possible to offload into a separate thread tasks that would otherwise +block the nginx worker process. +For example, nginx can be configured to use threads to perform file I/O. -Another example is using a library that doesn't have asynchronous interface +Another use case is a library that doesn't have asynchronous interface and thus cannot be normally used with nginx. -Keep in mind that threads interface is a helper for existing asynchronous -approach in processing client connections, and by no means a replacement. - - - -To deal with synchronization the following wrappers over pthreads primitives -are available: - -typedef pthread_mutex_t ngx_thread_mutex_t; - -ngx_int_t ngx_thread_mutex_create(ngx_thread_mutex_t *mtx, ngx_log_t *log); -ngx_int_t ngx_thread_mutex_destroy(ngx_thread_mutex_t *mtx, ngx_log_t *log); -ngx_int_t ngx_thread_mutex_lock(ngx_thread_mutex_t *mtx, ngx_log_t *log); -ngx_int_t ngx_thread_mutex_unlock(ngx_thread_mutex_t *mtx, ngx_log_t *log); - -typedef pthread_cond_t ngx_thread_cond_t; - -ngx_int_t ngx_thread_cond_create(ngx_thread_cond_t *cond, ngx_log_t *log); -ngx_int_t ngx_thread_cond_destroy(ngx_thread_cond_t *cond, ngx_log_t *log); -ngx_int_t ngx_thread_cond_signal(ngx_thread_cond_t *cond, ngx_log_t *log); -ngx_int_t ngx_thread_cond_wait(ngx_thread_cond_t *cond, ngx_thread_mutex_t *mtx, - ngx_log_t *log); - +Keep in mind that the threads interface is a helper for the existing +asynchronous approach to processing client connections, and by no means +intended as a replacement. + + + +To deal with synchronization, the following wrappers over +pthreads primitives are available: + + + + +typedef pthread_mutex_t ngx_thread_mutex_t; + + + + +ngx_int_t +ngx_thread_mutex_create(ngx_thread_mutex_t *mtx, ngx_log_t *log); + + + +ngx_int_t +ngx_thread_mutex_destroy(ngx_thread_mutex_t *mtx, ngx_log_t *log); + + + +ngx_int_t +ngx_thread_mutex_lock(ngx_thread_mutex_t *mtx, ngx_log_t *log); + + + +ngx_int_t +ngx_thread_mutex_unlock(ngx_thread_mutex_t *mtx, ngx_log_t *log); + + + + + + + +typedef pthread_cond_t ngx_thread_cond_t; + + + + +ngx_int_t +ngx_thread_cond_create(ngx_thread_cond_t *cond, ngx_log_t *log); + + + +ngx_int_t +ngx_thread_cond_destroy(ngx_thread_cond_t *cond, ngx_log_t *log); + + + +ngx_int_t +ngx_thread_cond_signal(ngx_thread_cond_t *cond, ngx_log_t *log); + + + +ngx_int_t +ngx_thread_cond_wait(ngx_thread_cond_t *cond, ngx_thread_mutex_t *mtx, +ngx_log_t *log); + + + + + + + + Instead of creating a new thread for each task, nginx implements a strategy. -Multiple thread pools may be configured intended for different purposes +Multiple thread pools may be configured for different purposes (for example, performing I/O on different sets of disks). -Each thread pool is created on start and contains a limited number of threads +Each thread pool is created at startup and contains a limited number of threads that process a queue of tasks. When a task is completed, a predefined completion handler is called. The src/core/ngx_thread_pool.h header file contains -corresponding definitions: +relevant definitions: struct ngx_thread_task_s { ngx_thread_task_t *next; @@ -2987,20 +3029,19 @@ ngx_int_t ngx_thread_task_post(ngx_threa At configuration time, a module willing to use threads has to obtain a -reference to thread pool by calling -ngx_thread_pool_add(cf, name) which will either create a -new thread pool with given name or return a reference -to an existing one if a pool with such name already exists. - - - -At runtime, the ngx_thread_task_post(tp, task) function -is used to add a task into a queue of a thread pool -tp. - -The ngx_thread_task_t structure contains all necessary -to execute user function in thread, pass parameters and setup completion -handler: +reference to a thread pool by calling +ngx_thread_pool_add(cf, name), which either creates a +new thread pool with the given name or returns a reference +to the pool with that name if it already exists. + + + +To add a task into a queue of a specified thread pool +tp at runtime, use the +ngx_thread_task_post(tp, task) function. + +To execute a function in a thread, pass parameters and setup a completion +handler using the ngx_thread_task_t structure: typedef struct { int foo; @@ -3061,11 +3102,11 @@ my_task_offload(my_conf_t *conf)
-The standalone nginx module resides in a separate directory that contains +Each standalone nginx module resides in a separate directory that contains at least two files: -config and a file with the module source. -The first file contains all information needed for nginx to integrate -the module, for example: +config and a file with the module source code. +The config file contains all information needed for nginx to +integrate the module, for example: ngx_module_type=CORE ngx_module_name=ngx_foo_module @@ -3075,113 +3116,114 @@ ngx_module_srcs="$ngx_addon_dir/ngx_foo_ ngx_addon_name=$ngx_module_name -The file is a POSIX shell script and it can set (or access) the -following variables: +The config file is a POSIX shell script that can set +and access the following variables: -ngx_module_type — the type of module to build. -Possible options are CORE, HTTP, +ngx_module_type — Type of module to build. +Possible values are CORE, HTTP, HTTP_FILTER, HTTP_INIT_FILTER, HTTP_AUX_FILTER, MAIL, -STREAM, or MISC - - - -ngx_module_name — the name of the module. -A whitespace separated values list is accepted and may be used to build -multiple modules from a single set of source files. -The first name indicates the name of the output binary for a dynamic module. -The names in this list should match the names used in the module. - - - -ngx_addon_name — supplies the name of the module in the -console output text of the configure script. - - - -ngx_module_srcs — a whitespace separated list of source +STREAM, or MISC. + + + +ngx_module_name — Module names. +To build multiple modules from a set of source files, specify a +whitespace-separated list of names. +The first name indicates the name of the output binary for the dynamic module. +The names in the list must match the names used in the source code. + + + +ngx_addon_name — Name of the module as it appears in output +on the console from the configure script. + + + +ngx_module_srcs — Whitespace-separated list of source files used to compile the module. -The $ngx_addon_dir variable can be used as a placeholder for the path of the -module source. - - - -ngx_module_incs — include paths required to build the module - - - -ngx_module_deps — a list of module's header files. - - - -ngx_module_libs — a list of libraries to link with the -module. -For example, libpthread would be linked using -ngx_module_libs=-lpthread. +The $ngx_addon_dir variable can be used to represent the path +to the module directory. + + + +ngx_module_incs — Include paths required to build the module + + + +ngx_module_deps — Whitespace-separated list of the module's +dependencies. +Usually, it is the list of header files. + + + +ngx_module_libs — Whitespace-separated list of libraries to +link with the module. +For example, use ngx_module_libs=-lpthread to link +libpthread library. The following macros can be used to link against the same libraries as nginx: LIBXSLT, LIBGD, GEOIP, PCRE, OPENSSL, MD5, -SHA1, ZLIB, and PERL - - - -ngx_module_link — set by the build system to +SHA1, ZLIB, and PERL. + + + +ngx_module_link — Variable set by the build system to DYNAMIC for a dynamic module or ADDON -for a static module and used to perform different actions depending on -linking type. - - - -ngx_module_order — sets the load order for the module which -is useful for HTTP_FILTER and +for a static module and used to determine different actions to perform +depending on linking type. + + + +ngx_module_order — Load order for the module; +useful for the HTTP_FILTER and HTTP_AUX_FILTER module types. -The order is stored in a reverse list. - - -The ngx_http_copy_filter_module is near the bottom of the -list so is one of the first to be executed. -This reads the data for other filters. -Near the top of the list is ngx_http_write_filter_module -which writes the data out and is one of the last to be executed. - - - -The format for this option is typically the current module’s name followed by -a whitespace separated list of modules to insert before, and therefore execute -after. -The module will be inserted before the last module in the list that is found -to be currently loaded. - - - -By default for filter modules this is set to -“ngx_http_copy_filter” which will insert the module before -the copy filter in the list and therefore will execute after the copy filter. -For other module types the default is empty. +The format for this option is a whitespace-separated list of modules. +All modules in the list following the current module's name end up after it in +the global list of modules, which sets up the order for modules initialization. +For filter modules later initialization means earlier execution. + + +The following modules are typically used as references. +The ngx_http_copy_filter_module reads the data for other +filter modules and is placed near the bottom of the list so that it is one of +the first to be executed. +The ngx_http_write_filter_module writes the data to the +client socket and is placed near the top of the list, and is the last to be +executed. + + + +By default, filter modules are placed before the +ngx_http_copy_filter in the module list so that the filter +handler is executed after the copy filter handler. +For other module types the default is the empty string. -A module can be added to nginx by means of the configure script using ---add-module=/path/to/module for static compilation and ---add-dynamic-module=/path/to/module for dynamic compilation. +To compile a module into nginx statically, use the +--add-module=/path/to/module argument to the configure +script. +To compile a module for later dynamic loading into nginx, use the +--add-dynamic-module=/path/to/module argument.
-
- - -Modules are building blocks of nginx, and most of its functionality is +
+ + +Modules are the building blocks of nginx, and most of its functionality is implemented as modules. -The module source file must contain a global variable of -ngx_module_t type which is defined as follows: +The module source file must contain a global variable of type +ngx_module_t, which is defined as follows: struct ngx_module_s { @@ -3205,14 +3247,14 @@ struct ngx_module_s { /* stubs for future extensions are omitted */ }; -The omitted private part includes module version, signature and is filled -using the predefined macro NGX_MODULE_V1. +The omitted private part includes the module version and a signature and is +filled using the predefined macro NGX_MODULE_V1. Each module keeps its private data in the ctx field, -recognizes specific configuration directives, specified in the -commands array, and may be invoked at certain stages of +recognizes the configuration directives, specified in the +commands array, and can be invoked at certain stages of nginx lifecycle. The module lifecycle consists of the following events: @@ -3220,22 +3262,24 @@ The module lifecycle consists of the fol Configuration directive handlers are called as they appear -in configuration files in the context of the master process - - - -The init_module handler is called in the context of -the master process after the configuration is parsed successfully - - - -The master process creates worker process(es) and -init_process handler is called in each of them - - - -When a worker process receives the shutdown command from master, it invokes -the exit_process handler +in configuration files in the context of the master process. + + + +After the configuration is parsed successfully, init_module +handler is called in the context of the master process. +The init_module handler is called in the master process each +time a configuration is loaded. + + + +The master process creates one or more worker processes and the +init_process handler is called in each of them. + + + +When a worker process receives the shutdown or terminate command from the +master, it invokes the exit_process handler. @@ -3245,21 +3289,17 @@ exiting. - -init_module handler may be called multiple times -in the master process if the configuration reload is requested. - - -The init_master, init_thread and -exit_thread handlers are not implemented at the moment; -Threads in nginx are only used as supplementary I/O facility with its own -API and init_master handler looks unnecessary. - - - -The module type defines what exactly is stored in the +Because threads are used in nginx only as a supplementary I/O facility with its +own API, init_thread and exit_thread +handlers are not currently called. +There is also no init_master handler, because it would be +unnecessary overhead. + + + +The module type defines exactly what is stored in the ctx field. -There are several types of modules: +Its value is one of the following types: NGX_CORE_MODULE NGX_EVENT_MODULE @@ -3268,17 +3308,19 @@ There are several types of modules: NGX_STREAM_MODULE The NGX_CORE_MODULE is the most basic and thus the most -generic and most low-level type of module. Other module types are implemented -on top of it and provide more convenient way to deal with corresponding -problem domains, like handling events or http requests. - - - -The examples of core modules are ngx_core_module, +generic and most low-level type of module. +The other module types are implemented on top of it and provide a more +convenient way to deal with corresponding domains, like handling events or HTTP +requests. + + + +The set of core modules includes ngx_core_module, ngx_errlog_module, ngx_regex_module, -ngx_thread_pool_module, -ngx_openssl_module -modules and, of course, http, stream, mail and event modules itself. +ngx_thread_pool_module and +ngx_openssl_module modules. +The HTTP module, the stream module, the mail module and event modules are core +modules too. The context of a core module is defined as: typedef struct { @@ -3287,22 +3329,20 @@ typedef struct { char *(*init_conf)(ngx_cycle_t *cycle, void *conf); } ngx_core_module_t; -where the name is a string with a module name for -convenience, create_conf and init_conf +where the name is a module name string, +create_conf and init_conf are pointers to functions that create and initialize module configuration -correspondingly. -For core modules, nginx will call create_conf before parsing +respectively. +For core modules, nginx calls create_conf before parsing a new configuration and init_conf after all configuration -was parsed successfully. +is parsed successfully. The typical create_conf function allocates memory for the configuration and sets default values. -The init_conf deals with known configuration and thus may -perform sanity checks and complete initialization. - - - -For example, the simplistic ngx_foo_module can look like -this: + + + +For example, a simplistic module called ngx_foo_module might +look like this: /* * Copyright (C) Author. @@ -3407,13 +3447,16 @@ ngx_foo_enable(ngx_conf_t *cf, void *pos
-
- - -The ngx_command_t describes single configuration directive. -Each module, supporting configuration, provides an array of such specifications +
+ + +The ngx_command_t type defines a single configuration +directive. +Each module that supports configuration provides an array of such structures that describe how to process arguments and what handlers to call: +typedef struct ngx_command_s ngx_command_t; + struct ngx_command_s { ngx_str_t name; ngx_uint_t type; @@ -3423,221 +3466,243 @@ struct ngx_command_s { void *post; }; -The array should be terminated by a special value -“ngx_null_command”. -The name is the literal name of a directive, as it appears -in configuration file, for example “worker_processes” or -“listen”. -The type is a bitfield that controls number of arguments, -command type and other properties using corresponding flags. -Arguments flags: +Terminate the array with the special value ngx_null_command. +The name is the name of a directive as it appears +in the configuration file, for example "worker_processes" or "listen". +The type is a bit-field of flags that specify the number of +arguments the directive takes, its type, and the context in which it appears. +The flags are: -NGX_CONF_NOARGS — directive without arguments - - -NGX_CONF_1MORE — one required argument - -NGX_CONF_2MORE — two required arguments - - -NGX_CONF_TAKE1..7 — exactly 1..7 arguments - - - -NGX_CONF_TAKE12, 13, 23, 123, 1234 — one or two arguments, -or other combinations +NGX_CONF_NOARGS — Directive takes no arguments. + + + +NGX_CONF_1MORE — Directive takes one or more arguments. + + + +NGX_CONF_2MORE — Directive takes two or more arguments. + + + +NGX_CONF_TAKE1..NGX_CONF_TAKE7 — +Directive takes exactly the indicated number of arguments. + + + +NGX_CONF_TAKE12, NGX_CONF_TAKE13, +NGX_CONF_TAKE23, NGX_CONF_TAKE123, +NGX_CONF_TAKE1234 — Directive may take different number of +arguments. +Options are limited to the given numbers. +For example, NGX_CONF_TAKE12 means it takes one or two +arguments. + + + + +The flags for directive types are: + + + + +NGX_CONF_BLOCK — Directive is a block, that is, it can +contain other directives within its opening and closing curly braces, or even +implement its own parser to handle contents inside. + + + +NGX_CONF_FLAG — Directive takes a boolean value, either +on or off. -Directive types: +A directive's context defines where it may appear in the configuration: -NGX_CONF_BLOCK — the directive is a block, i.e. it may -contain other directives in curly braces, or even implement its own parser -to handle contents inside. - - - -NGX_CONF_FLAG — the directive value is a flag, a boolean -value represented by “on” or “off” -strings. +NGX_MAIN_CONF — In the top level context. + + + +NGX_HTTP_MAIN_CONF — In the http block. + + + +NGX_HTTP_SRV_CONF — In a server block +within the http block. + + + +NGX_HTTP_LOC_CONF — In a location block +within the http block. + + + +NGX_HTTP_UPS_CONF — In an upstream block +within the http block. + + + +NGX_HTTP_SIF_CONF — In an if block within +a server block in the http block. + + + +NGX_HTTP_LIF_CONF — In an if block within +a location block in the http block. + + + +NGX_HTTP_LMT_CONF — In a limit_except +block within the http block. + + + +NGX_STREAM_MAIN_CONF — In the stream +block. + + + +NGX_STREAM_SRV_CONF — In a server block +within the stream block. + + + +NGX_STREAM_UPS_CONF — In an upstream block +within the stream block. + + + +NGX_MAIL_MAIN_CONF — In the mail block. + + + +NGX_MAIL_SRV_CONF — In a server block +within the mail block. + + + +NGX_EVENT_CONF — In the event block. + + + +NGX_DIRECT_CONF — Used by modules that don't +create a hierarchy of contexts and only have one global configuration. +This configuration is passed to the handler as the conf +argument. -Context of a directive defines where in the configuration it may appear -and how to access module context to store corresponding values: - - - -NGX_MAIN_CONF — top level configuration - - - -NGX_HTTP_MAIN_CONF — in the http block - - - -NGX_HTTP_SRV_CONF — in the http server block - - - -NGX_HTTP_LOC_CONF — in the http location - - - -NGX_HTTP_UPS_CONF — in the http upstream block - - - -NGX_HTTP_SIF_CONF — in the http server “if” - - - -NGX_HTTP_LIF_CONF — in the http location “if” - - - -NGX_HTTP_LMT_CONF — in the http “limit_except” - - - -NGX_STREAM_MAIN_CONF — in the stream block - - - -NGX_STREAM_SRV_CONF — in the stream server block - - - -NGX_STREAM_UPS_CONF — in the stream upstream block - - - -NGX_MAIL_MAIN_CONF — in the the mail block - - - -NGX_MAIL_SRV_CONF — in the mail server block - - - -NGX_EVENT_CONF — in the event block - - - -NGX_DIRECT_CONF — used by modules that don't -create a hierarchy of contexts and store module configuration directly in ctx - - -The configuration parser uses this flags to throw an error in case of +The configuration parser uses these flags to throw an error in case of a misplaced directive and calls directive handlers supplied with a proper -configuration pointer, so that same directives in different locations could +configuration pointer, so that the same directives in different locations can store their values in distinct places. The set field defines a handler that processes a directive -and stores parsed values into corresponding configuration. -Nginx offers a convenient set of functions that perform common conversions: +and stores parsed values into the corresponding configuration. +There's a number of functions that perform common conversions: -ngx_conf_set_flag_slot — converts literal -“on” or “off” strings into -ngx_flag_t type with values 1 or 0 - - - -ngx_conf_set_str_slot — stores string as a value of the -ngx_str_t type - - - -ngx_conf_set_str_array_slot — appends -ngx_array_t of ngx_str_t with a new value. -The array is created if not yet exists - - - -ngx_conf_set_keyval_slot — appends -ngx_array_t of ngx_keyval_t with -a new value, where key is the first string and value is second. -The array is created if not yet exists - - - -ngx_conf_set_num_slot — converts directive argument -to a ngx_int_t value - - - -ngx_conf_set_size_slot — converts -size to size_t value -in bytes - - - -ngx_conf_set_off_slot — converts -offset to off_t value -in bytes - - - -ngx_conf_set_msec_slot — converts -time to ngx_msec_t value -in milliseconds - - - -ngx_conf_set_sec_slot — converts -time to time_t value -in seconds - - - -ngx_conf_set_bufs_slot — converts two arguments -into ngx_bufs_t that holds ngx_int_t -number and size of buffers - - - -ngx_conf_set_enum_slot — converts argument -into ngx_uint_t value. +ngx_conf_set_flag_slot — Converts the literal strings +on and off into an +ngx_flag_t value with values 1 or 0, respectively. + + + +ngx_conf_set_str_slot — Stores a string as a value of the +ngx_str_t type. + + + +ngx_conf_set_str_array_slot — Appends a value to an array +ngx_array_t of strings ngx_str_t. +The array is created if does not already exist. + + + +ngx_conf_set_keyval_slot — Appends a key-value pair to an +array ngx_array_t of key-value pairs +ngx_keyval_t. +The first string becomes the key and the second the value. +The array is created if it does not already exist. + + + +ngx_conf_set_num_slot — Converts a directive's argument +to an ngx_int_t value. + + + +ngx_conf_set_size_slot — Converts a +size to a size_t value +expressed in bytes. + + + +ngx_conf_set_off_slot — Converts an +offset to an off_t value +expressed in bytes. + + + +ngx_conf_set_msec_slot — Converts a +time to an ngx_msec_t value +expressed in milliseconds. + + + +ngx_conf_set_sec_slot — Converts a +time to a time_t value +expressed in in seconds. + + + +ngx_conf_set_bufs_slot — Converts the two supplied arguments +into an ngx_bufs_t object that holds the number and +size of buffers. + + + +ngx_conf_set_enum_slot — Converts the supplied argument +into an ngx_uint_t value. The null-terminated array of ngx_conf_enum_t passed in the -post field defines acceptable strings and corresponding -integer values - - - -ngx_conf_set_bitmask_slot — arguments are converted to -ngx_uint_t value and OR'ed with the resulting value, -forming a bitmask. -The null-terminated array of ngx_conf_bitmask_t passed in -the post field defines acceptable strings and corresponding -mask values - - - -set_path_slot — converts arguments to -ngx_path_t type and performs all required initializations. -See the -proxy_temp_path -directive description for details - - - -set_access_slot — converts arguments to file permissions -mask. -See the -proxy_store_access -directive description for details +post field defines the acceptable strings and corresponding +integer values. + + + +ngx_conf_set_bitmask_slot — Converts the supplied arguments +into an ngx_uint_t value. +The mask values for each argument are ORed producing the result. +The null-terminated array of ngx_conf_bitmask_t passed in the +post field defines the acceptable strings and corresponding +mask values. + + + +set_path_slot — Converts the supplied arguments to an +ngx_path_t value and performs all required initializations. +For details, see the documentation for the + +proxy_temp_path directive. + + + +set_access_slot — Converts the supplied arguments to a file +permissions mask. +For details, see the documentation for the + +proxy_store_access directive. @@ -3645,45 +3710,48 @@ directive description for details -The conf field defines which context is used to store -the value of the directive, or zero if contexts are not used. -Only simple core modules use configuration without context and set -NGX_DIRECT_CONF flag. -In real life, such modules like http or stream require more sophisticated -configuration that can be applied per-server or per-location, or even more -precisely, in the context of the “if” directive or -some limit. -In this modules, configuration structure is more complex. -Please refer to corresponding modules description to understand how -they manage their configuration. +The conf field defines which configuration structure is +passed to the directory handler. +Core modules only have the global configuration and set +NGX_DIRECT_CONF flag to access it. +Modules like HTTP, Stream or Mail create hierarchies of configurations. +For example, a module's configuration is created for server, +location and if scopes. -NGX_HTTP_MAIN_CONF_OFFSET — http block configuration - - - -NGX_HTTP_SRV_CONF_OFFSET — http server configuration - - - -NGX_HTTP_LOC_CONF_OFFSET — http location configuration - - - -NGX_STREAM_MAIN_CONF_OFFSET — stream block configuration - - - -NGX_STREAM_SRV_CONF_OFFSET — stream server configuration - - - -NGX_MAIL_MAIN_CONF_OFFSET — mail block configuration - - - -NGX_MAIL_SRV_CONF_OFFSET — mail server configuration +NGX_HTTP_MAIN_CONF_OFFSET — Configuration for the +http block. + + + +NGX_HTTP_SRV_CONF_OFFSET — Configuration for a +server block within the http block. + + + +NGX_HTTP_LOC_CONF_OFFSET — Configuration for a +location block within the http. + + + +NGX_STREAM_MAIN_CONF_OFFSET — Configuration for the +stream block. + + + +NGX_STREAM_SRV_CONF_OFFSET — Configuration for a +server block within the stream block. + + + +NGX_MAIL_MAIN_CONF_OFFSET — Configuration for the +mail block. + + + +NGX_MAIL_SRV_CONF_OFFSET — Configuration for a +server block within the mail block. @@ -3691,23 +3759,23 @@ they manage their configuration. -The offset defines an offset of a field in a module -configuration structure that holds values of this particular directive. -The typical use is to employ offsetof() macro. - - - -The post is a twofold field: it may be used to define -a handler to be called after main handler completed or to pass additional -data to the main handler. -In the first case, ngx_conf_post_t structure needs to -be initialized with a pointer to handler, for example: +The offset defines the offset of a field in a module +configuration structure that holds values for this particular directive. +The typical use is to employ the offsetof() macro. + + + +The post field has two purposes: it may be used to define +a handler to be called after the main handler has completed, or to pass +additional data to the main handler. +In the first case, the ngx_conf_post_t structure needs to +be initialized with a pointer to the handler, for example: static char *ngx_do_foo(ngx_conf_t *cf, void *post, void *data); static ngx_conf_post_t ngx_foo_post = { ngx_do_foo }; The post argument is the ngx_conf_post_t -object itself, and the data is a pointer to value, +object itself, and the data is a pointer to the value, converted from arguments by the main handler with the appropriate type. @@ -3722,7 +3790,7 @@ converted from arguments by the main han
-Each client HTTP connection runs through the following stages: +Each HTTP client connection runs through the following stages: @@ -3730,45 +3798,47 @@ Each client HTTP connection runs through ngx_event_accept() accepts a client TCP connection. This handler is called in response to a read notification on a listen socket. -A new ngx_connecton_t object is created at this stage. -The object wraps the newly accepted client socket. +A new ngx_connecton_t object is created at this stage +to wrap the newly accepted client socket. Each nginx listener provides a handler to pass the new connection object to. -For HTTP connections it's ngx_http_init_connection(c) +For HTTP connections it's ngx_http_init_connection(c). ngx_http_init_connection() performs early initialization of -an HTTP connection. +the HTTP connection. At this stage an ngx_http_connection_t object is created for -the connection and its reference is stored in connection's +the connection and its reference is stored in the connection's data field. -Later it will be substituted with an HTTP request object. -PROXY protocol parser and SSL handshake are started at this stage as well - - - -ngx_http_wait_request_handler() is a read event handler, that -is called when data is available in the client socket. +Later it will be replaced by an HTTP request object. +A PROXY protocol parser and the SSL handshake are started at +this stage as well. + + + +ngx_http_wait_request_handler() read event handler +is called when data is available on the client socket. At this stage an HTTP request object ngx_http_request_t is -created and set to connection's data field - - - -ngx_http_process_request_line() is a read event handler, -which reads client request line. +created and set to the connection's data field. + + + +ngx_http_process_request_line() read event handler +reads client request line. The handler is set by ngx_http_wait_request_handler(). -Reading is done into connection's buffer. +The data is read into connection's buffer. The size of the buffer is initially set by the directive . -The entire client header is supposed to fit the buffer. -If the initial size is not enough, a bigger buffer is allocated, whose size is -set by the large_client_header_buffers directive - - - -ngx_http_process_request_headers() is a read event handler, -which is set after ngx_http_process_request_line() to read -client request header +The entire client header is supposed to fit in the buffer. +If the initial size is not sufficient, a bigger buffer is allocated, +with the capacity set by the large_client_header_buffers +directive. + + + +ngx_http_process_request_headers() read event handler, +is set after ngx_http_process_request_line() to read +the client request header. @@ -3777,10 +3847,10 @@ is completely read and parsed. This function runs request phases from NGX_HTTP_POST_READ_PHASE to NGX_HTTP_CONTENT_PHASE. -The last phase is supposed to generate response and pass it along the filter +The last phase is intended to generate a response and pass it along the filter chain. The response is not necessarily sent to the client at this phase. -It may remain buffered and will be sent at the finalization stage +It might remain buffered and be sent at the finalization stage. @@ -3790,17 +3860,17 @@ In the latter case an appropriate error response. If the response is not completely sent to the client by this point, an HTTP writer ngx_http_writer() is activated to finish -sending outstanding data - - - -ngx_http_finalize_connection() is called when the response is -completely sent to the client and the request can be destroyed. -If client connection keepalive feature is enabled, -ngx_http_set_keepalive() is called, which destroys current -request and waits for the next request on the connection. +sending outstanding data. + + + +ngx_http_finalize_connection() is called when the complete +response has been sent to the client and the request can be destroyed. +If the client connection keepalive feature is enabled, +ngx_http_set_keepalive() is called, which destroys the +current request and waits for the next request on the connection. Otherwise, ngx_http_close_request() destroys both the -request and the connection +request and the connection. @@ -3812,7 +3882,7 @@ request and the connection For each client HTTP request the ngx_http_request_t object is -created. Some of the fields of this object: +created. Some of the fields of this object are: @@ -3820,30 +3890,30 @@ created. Some of the fields of this obj -connection — pointer to a ngx_connection_t +connection — Pointer to a ngx_connection_t client connection object. -Several requests may reference the same connection object at the same time - +Several requests can reference the same connection object at the same time - one main request and its subrequests. -After a request is deleted, a new request may be created on the same connection. +After a request is deleted, a new request can be created on the same connection. Note that for HTTP connections ngx_connection_t's data field points back to the request. -Such request is called active, as opposed to the other requests tied with the +Such requests are called active, as opposed to the other requests tied to the connection. -Active request is used to handle client connection events and is allowed to +An active request is used to handle client connection events and is allowed to output its response to the client. -Normally, each request becomes active at some point to be able to send its -output - - - - - - - -ctx — array of HTTP module contexts. +Normally, each request becomes active at some point so that it can send its +output. + + + + + + + +ctx — Array of HTTP module contexts. Each module of type NGX_HTTP_MODULE can store any value (normally, a pointer to a structure) in the request. The value is stored in the ctx array at the module's @@ -3854,13 +3924,13 @@ The following macros provide a convenien -ngx_http_get_module_ctx(r, module) — returns -module's context - - - -ngx_http_set_ctx(r, c, module) — sets c -as module's context +ngx_http_get_module_ctx(r, module) — Returns +the module's context + + + +ngx_http_set_ctx(r, c, module) — Sets c +as the module's context @@ -3868,119 +3938,132 @@ as module's context -main_conf, srv_conf, loc_conf — arrays of current request +main_conf, srv_conf, +loc_conf — Arrays of current request configurations. -Configurations are stored at module's ctx_index positions +Configurations are stored at the module's ctx_index +positions. read_event_handler, write_event_handler - -read and write event handlers for the request. -Normally, an HTTP connection has ngx_http_request_handler() -set as both read and write event handlers. -This function calls read_event_handler and -write_event_handler handlers of the currently active request - - - -cache — request cache object for caching upstream response - - - -upstream — request upstream object for proxying - - - -pool — request pool. -This pool is destroyed when the request is deleted. -The request object itself is allocated in this pool. -For allocations which should be available throughout the client connection's -lifetime, ngx_connection_t's pool should be used instead - - - -header_in — buffer where client HTTP request header in read - - - -headers_in, headers_out — input and output HTTP headers -objects. +Read and write event handlers for the request. +Normally, both the read and write event handlers for an HTTP connection +are set to ngx_http_request_handler(). +This function calls the read_event_handler and +write_event_handler handlers for the currently +active request. + + + +cache — Request cache object for caching the +upstream response. + + + +upstream — Request upstream object for proxying. + + + +pool — Request pool. +The request object itself is allocated in this pool, which is destroyed when +the request is deleted. +For allocations that need to be available throughout the client connection's +lifetime, use ngx_connection_t's pool instead. + + + +header_in — Buffer into which the client HTTP request +header is read. + + + +headers_in, headers_out — Input and +output HTTP headers objects. Both objects contain the headers field of type -ngx_list_t keeping the raw list of headers. +ngx_list_t for keeping the raw list of headers. In addition to that, specific headers are available for getting and setting as separate fields, for example content_length_n, -status etc - - - -request_body — client request body object - - - -start_sec, start_msec — time point when the request was -created. -Used for tracking request duration - - - -method, method_name — numeric and textual representation of -client HTTP request method. +status etc. + + + +request_body — Client request body object. + + + +start_sec, start_msec — Time point when +the request was created, used for tracking request duration. + + + +method, method_name — Numeric and text +representation of the client HTTP request method. Numeric values for methods are defined in -src/http/ngx_http_request.h with macros -NGX_HTTP_GET, NGX_HTTP_HEAD, NGX_HTTP_POST etc - - - -http_protocol, http_version, http_major, http_minor - -client HTTP protocol version in its original textual form (“HTTP/1.0”, -“HTTP/1.1” etc), numeric form (NGX_HTTP_VERSION_10, -NGX_HTTP_VERSION_11 etc) and separate major and minor -versions - - - -request_line, unparsed_uri — client original request line -and URI - - - -uri, args, exten — current request URI, arguments and file -extention. +src/http/ngx_http_request.h with the macros +NGX_HTTP_GET, NGX_HTTP_HEAD, +NGX_HTTP_POST, etc. + + + +http_protocol  — Client HTTP protocol version in its +original text form (“HTTP/1.0”, “HTTP/1.1” etc). + + + +http_version  — Client HTTP protocol version in +numeric form (NGX_HTTP_VERSION_10, +NGX_HTTP_VERSION_11, etc.). + + + +http_major, http_minor  — Client HTTP +protocol version in numeric form split into major and minor parts. + + + +request_line, unparsed_uri — Request line +and URI in the original client request. + + + +uri, args, exten — +URI, arguments and file extension for the current request. The URI value here might differ from the original URI sent by the client due to normalization. -Throughout request processing, these value can change while performing internal -redirects - - - -main — pointer to a main request object. -This object is created to process client HTTP request, as opposed to -subrequests, created to perform a specific sub-task within the main request - - - -parent — pointer to a parent request of a subrequest - - - -postponed — list of output buffers and subrequests in the -order they are sent and created. -The list is used by the postpone filter to provide consistent request output, -when parts of it are created by subrequests - - - -post_subrequest — pointer to a handler with context to be -called when a subrequest gets finalized. -Unused for main requests - - - - - -posted_requests — list of requests to be started or -resumed. -Starting or resuming is done by calling the request's +Throughout request processing, these values can change as internal redirects +are performed. + + + +main — Pointer to a main request object. +This object is created to process a client HTTP request, as opposed to +subrequests, which are created to perform a specific subtask within the main +request. + + + +parent — Pointer to the parent request of a subrequest. + + + +postponed — List of output buffers and subrequests, in the +order in which they are sent and created. +The list is used by the postpone filter to provide consistent request output +when parts of it are created by subrequests. + + + +post_subrequest — Pointer to a handler with the context +to be called when a subrequest gets finalized. +Unused for main requests. + + + + + +posted_requests — List of requests to be started or +resumed, which is done by calling the request's write_event_handler. Normally, this handler holds the request main function, which at first runs request phases and then produces the output. @@ -3991,140 +4074,147 @@ A request is usually posted by the ngx_http_post_request(r, NULL) call. It is always posted to the main request posted_requests list. The function ngx_http_run_posted_requests(c) runs all -requests, posted in the main request of the passed connection's active request. -This function should be called in all event handlers, which can lead to new -posted requests. -Normally, it's called always after invoking a request's read or write handler - - - - - -phase_handler — index of current request phase - - - -ncaptures, captures, captures_data — regex captures produced +requests that are posted in the main request of the passed +connection's active request. +All event handlers call ngx_http_run_posted_requests, +which can lead to new posted requests. +Normally, it is called after invoking a request's read or write handler. + + + + + +phase_handler — Index of current request phase. + + + +ncaptures, captures, +captures_data — Regex captures produced by the last regex match of the request. -While processing a request, there's a number of places where a regex match can -happen: map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect -etc. +A regex match can occur at a number of places during request processing: +map lookup, server lookup by SNI or HTTP Host, rewrite, proxy_redirect, etc. Captures produced by a lookup are stored in the above mentioned fields. The field ncaptures holds the number of captures, -captures holds captures boundaries, -captures_data holds a string, against which the regex was -matched and which should be used to extract captures. -After each new regex match request captures are reset to hold new values - - - -count — request reference counter. +captures holds captures boundaries and +captures_data holds the string against which the regex was +matched and which is used to extract captures. +After each new regex match, request captures are reset to hold new values. + + + +count — Request reference counter. The field only makes sense for the main request. Increasing the counter is done by simple r->main->count++. -To decrease the counter ngx_http_finalize_request(r, rc) -should be called. -Creation of a subrequest or running request body read process increase the -counter - - - -subrequests — current subrequest nesting level. -Each subrequest gets the nesting level of its parent decreased by one. -Once the value reaches zero an error is generated. +To decrease the counter, call +ngx_http_finalize_request(r, rc). +Creating of a subrequest and running the request body read process both +increment the counter. + + + +subrequests — Current subrequest nesting level. +Each subrequest inherits its parent's nesting level, decreased by one. +An error is generated if the value reaches zero. The value for the main request is defined by the -NGX_HTTP_MAX_SUBREQUESTS constant - - - -uri_changes — number of URI changes left for the request. +NGX_HTTP_MAX_SUBREQUESTS constant. + + + +uri_changes — Number of URI changes remaining for +the request. The total number of times a request can change its URI is limited by the NGX_HTTP_MAX_URI_CHANGES constant. -With each change the value is decreased until it reaches zero. -In the latter case an error is generated. -The actions considered as URI changes are rewrites and internal redirects to -normal or named locations - - - -blocked — counter of blocks held on the request. -While this value is non-zero, request cannot be terminated. +With each change the value is decremented until it reaches zero, at which time +an error is generated. +Rewrites and internal redirects to normal or named locations are considered URI +changes. + + + +blocked — Counter of blocks held on the request. +While this value is non-zero, the request cannot be terminated. Currently, this value is increased by pending AIO operations (POSIX AIO and -thread operations) and active cache lock - - - -buffered — bitmask showing which modules have buffered the +thread operations) and active cache lock. + + + +buffered — Bitmask showing which modules have buffered the output produced by the request. -A number of filters can buffer output, for example sub_filter can buffer data -due to a partial string match, copy filter can buffer data because of the lack -of free output_buffers etc. -As long as this value is non-zero, request is not finalized, expecting the flush - - - -header_only — flag showing that output does not require body. -For example, this flag is used by HTTP HEAD requests - - - - -keepalive — flag showing if client connection keepalive is -supported. -The value is inferred from HTTP version and
Connection
header -value -
-
- - -header_sent — flag showing that output header has already -been sent by the request - - - -internal — flag showing that current request is internal. -To enter the internal state, a request should pass through an internal +A number of filters can buffer output; for example, sub_filter can buffer data +because of a partial string match, copy filter can buffer data because of the +lack of free output buffers etc. +As long as this value is non-zero, the request is not finalized +pending the flush. + + + +header_only — Flag indicating that the output does not +require a body. +For example, this flag is used by HTTP HEAD requests. + + + + +keepalive — Flag indicating whether client connection +keepalive is supported. +The value is inferred from the HTTP version and the value of the +
Connection
header. +
+
+ + +header_sent — Flag indicating that the output header +has already been sent by the request. + + + +internal — Flag indicating that the current request +is internal. +To enter the internal state, a request must pass through an internal redirect or be a subrequest. -Internal requests are allowed to enter internal locations - - - -allow_ranges — flag showing that partial response can be -sent to client, if requested by the HTTP Range header - - - -subrequest_ranges — flag showing that a partial response is -allowed to be sent while processing a subrequest - - - -single_range — flag showing that only a single continuous +Internal requests are allowed to enter internal locations. + + + +allow_ranges — Flag indicating that a partial response +can be sent to the client, as requested by the HTTP Range header. + + + +subrequest_ranges — Flag indicating that a partial response +can be sent while a subrequest is being processed. + + + +single_range — Flag indicating that only a single continuous range of output data can be sent to the client. This flag is usually set when sending a stream of data, for example from a -proxied server, and the entire response is not available at once - - - -main_filter_need_in_memory, filter_need_in_memory — flags -showing that the output should be produced in memory buffers but not in files. +proxied server, and the entire response is not available in one buffer. + + + +main_filter_need_in_memory, +filter_need_in_memory — Flags +requesting that the output produced in memory buffers rather than files. This is a signal to the copy filter to read data from file buffers even if sendfile is enabled. -The difference between these two flags is the location of filter modules which +The difference between the two flags is the location of the filter modules that set them. -Filters called before the postpone filter in filter chain, set -filter_need_in_memory requesting that only the current -request output should come in memory buffers. -Filters called later in filter chain set -main_filter_need_in_memory requiring that both the main -request and all the subrequest read files in memory while sending output - - - -filter_need_temporary — flag showing that the request output -should be produced in temporary buffers, but not in readonly memory buffers or +Filters called before the postpone filter in the filter chain set +filter_need_in_memory, requesting that only the current +request output come in memory buffers. +Filters called later in the filter chain set +main_filter_need_in_memory, requesting that +both the main request and all subrequests read files in memory +while sending output. + + + +filter_need_temporary — Flag requesting that the request +output be produced in temporary buffers, but not in readonly memory buffers or file buffers. -This is used by filters which may change output directly in the buffers, where -it's sent +This is used by filters which may change output directly in the buffers where +it's sent.
@@ -4134,39 +4224,37 @@ it's sent
-Each HTTP module may have three types of configuration: +Each HTTP module can have three types of configuration: -Main configuration. -This configuration applies to the entire nginx http{} block. This is global -configuration. -It stores global settings for a module - - - -Server configuration. -This configuration applies to a single nginx server{}. -It stores server-specific settings for a module - - - -Location configuration. -This configuration applies to a single location{}, if{} or limit_except() block. -This configuration stores settings specific to a location +Main configuration — Applies to the entire http block. +Functions as global settings for a module. + + + +Server configuration — Applies to a single server block. +Functions as server-specific settings for a module. + + + +Location configuration — Applies to a single location, +if or limit_except block. +Functions as location-specific settings for a module. -Configuration structures are created at nginx configuration stage by calling -functions, which allocate these structures, initialize them and merge. -The following example shows how to create a simple module location -configuration. -The configuration has one setting foo of unsiged integer -type. +Configuration structures are created at the nginx configuration stage by +calling functions, which allocate the structures, initialize them +and merge them. +The following example shows how to create a simple location +configuration for a module. +The configuration has one setting, foo, of type +unsigned integer. @@ -4217,32 +4305,32 @@ ngx_http_foo_merge_loc_conf(ngx_conf_t * -As seen in the example, ngx_http_foo_create_loc_conf() -function creates a new configuration structure and +As seen in the example, the ngx_http_foo_create_loc_conf() +function creates a new configuration structure, and ngx_http_foo_merge_loc_conf() merges a configuration with -another configuration from a higher level. -In fact, server and location configuration do not only exist at server and -location levels, but also created for all the levels above. -Specifically, a server configuration is created at the main level as well and -location configurations are created for main, server and location levels. -These configurations make it possible to specify server and location-specific -settings at any level of nginx configuration file. +configuration from a higher level. +In fact, server and location configuration do not exist only at the server and +location levels, but are also created for all levels above them. +Specifically, a server configuration is also created at the main level and +location configurations are created at the main, server, and location levels. +These configurations make it possible to specify server- and location-specific +settings at any level of an nginx configuration file. Eventually configurations are merged down. -To indicate a missing setting and ignore it while merging, nginx provides a -number of macros like NGX_CONF_UNSET and -NGX_CONF_UNSET_UINT. +A number of macros like NGX_CONF_UNSET and +NGX_CONF_UNSET_UINT are provided +for indicating a missing setting and ignoring it while merging. Standard nginx merge macros like ngx_conf_merge_value() and ngx_conf_merge_uint_value() provide a convenient way to -merge a setting and set the default value if none of configurations provided an -explicit value. -For complete list of macros for different types see +merge a setting and set the default value if none of the configurations +provided an explicit value. +For complete list of macros for different types, see src/core/ngx_conf_file.h. -To access configuration of any HTTP module at configuration time, the following -macros are available. -They receive ngx_conf_t reference as the first argument. +The following macros are available. +for accessing configuration for HTTP modules at configuration time. +They all take ngx_conf_t reference as the first argument. @@ -4265,9 +4353,8 @@ They receive ngx_conf_tngx_http_core_module -and changes -location content handler kept in the handler field of the -structure. +and replaces the location content handler kept +in the handler field of the structure. @@ -4300,8 +4387,8 @@ ngx_http_foo(ngx_conf_t *cf, ngx_command -In runtime the following macros are available to get configurations of HTTP -modules. +The following macros are available for accessing configuration for HTTP +modules at runtime. @@ -4323,12 +4410,13 @@ modules. These macros receive a reference to an HTTP request ngx_http_request_t. -Main configuration of a request never changes. -Server configuration may change from a default one after choosing a virtual -server for a request. -Request location configuration may change multiple times as a result of a -rewrite or internal redirect. -The following example shows how to access HTTP configuration in runtime. +The main configuration of a request never changes. +Server configuration can change from the default after +the virtual server for the request is chosen. +Location configuration selected for processing a request can change multiple +times as a result of a rewrite operation or internal redirect. +The following example shows how to access a module's HTTP configuration at +runtime. @@ -4349,119 +4437,125 @@ ngx_http_foo_handler(ngx_http_request_t
-Each HTTP request passes through a list of HTTP phases. -Each phase is specialized in a particular type of processing. -Most phases allow installing handlers. -The phase handlers are called successively once the request reaches the phase. -Many standard nginx modules install their phase handlers as a way to get called -at a specific request processing stage. +Each HTTP request passes through a sequence of phases. +In each phase a distinct type of processing is performed on the request. +Module-specific handlers can be registered in most phases, +and many standard nginx modules register their phase handlers as a way +to get called at a specific stage of request processing. +Phases are processed successively and the phase handlers are called +once the request reaches the phase. Following is the list of nginx HTTP phases. -NGX_HTTP_POST_READ_PHASE is the earliest phase. +NGX_HTTP_POST_READ_PHASE — First phase. The ngx_http_realip_module -installs its handler at this phase. -This allows to substitute client address before any other module is invoked - - - -NGX_HTTP_SERVER_REWRITE_PHASE is used to run rewrite script, -defined at the server level, that is out of any location block. +registers its handler at this phase to enable +substitution of client addresses before any other module is invoked. + + + +NGX_HTTP_SERVER_REWRITE_PHASE — Phase where +rewrite directives defined in a server block +(but outside a location block) are processed. The ngx_http_rewrite_module -installs its handler at this phase - - - -NGX_HTTP_FIND_CONFIG_PHASE — a special phase used to choose a -location based on request URI. -This phase does not allow installing any handlers. -It only performs the default action of choosing a location. -Before this phase, the server default location is assigned to the request. -Any module requesting a location configuration, will receive the default server -location configuration. -After this phase a new location is assigned to the request - - - -NGX_HTTP_REWRITE_PHASE — same as -NGX_HTTP_SERVER_REWRITE_PHASE, but for a new location, -chosen at the previous phase - - - -NGX_HTTP_POST_REWRITE_PHASE — a special phase, used to -redirect the request to a new location, if the URI was changed during rewrite. -The redirect is done by going back to -NGX_HTTP_FIND_CONFIG_PHASE. -No handlers are allowed at this phase - - - -NGX_HTTP_PREACCESS_PHASE — a common phase for different -types of handlers, not associated with access check. -Standard nginx modules +installs its handler at this phase. + + + +NGX_HTTP_FIND_CONFIG_PHASE — Special phase +where a location is chosen based on the request URI. +Before this phase, the default location for the relevant virtual server +is assigned to the request, and any module requesting a location configuration +receives the configuration for the default server location. +This phase a assigns a new location to the request. +No additional handlers can be registered at this phase. + + + +NGX_HTTP_REWRITE_PHASE — Same as +NGX_HTTP_SERVER_REWRITE_PHASE, but for +rewrite rules defined in the location, chosen in the previous phase. + + + +NGX_HTTP_POST_REWRITE_PHASE — Special phase +where the request is redirected to a new location if its URI changed +during a rewrite. +This is implemented by the request going through +the NGX_HTTP_FIND_CONFIG_PHASE again. +No additional handlers can be registered at this phase. + + + +NGX_HTTP_PREACCESS_PHASE — A common phase for different +types of handlers, not associated with access control. +The standard nginx modules ngx_http_limit_conn_module and -ngx_http_limit_req_module register their handlers at this phase - - - -NGX_HTTP_ACCESS_PHASE — used to check access permissions -for the request. +ngx_http_limit_req_module register their handlers at this phase. + + + +NGX_HTTP_ACCESS_PHASE — Phase where it is verified +that the client is authorized to make the request. Standard nginx modules such as ngx_http_access_module and ngx_http_auth_basic_module register their handlers at this phase. -If configured so by the - directive, only one -of access phase handlers may allow access to the request in order to continue -processing - - - -NGX_HTTP_POST_ACCESS_PHASE — a special phase for the +By default the client must pass the authorization check of all handlers +registered at this phase for the request to continue to the next phase. +The directive, +can be used to permit processing to continue if any of the phase handlers +authorizes the client. + + + +NGX_HTTP_POST_ACCESS_PHASE — Special phase where the satisfy any -case. -If some access phase handlers denied the access and none of them allowed, the +directive is processed. +If some access phase handlers denied access and none explictly allowed it, the request is finalized. -No handlers are supported at this phase - - - -NGX_HTTP_TRY_FILES_PHASE — a special phase, for the - feature. -No handlers are allowed at this phase - - - -NGX_HTTP_CONTENT_PHASE — a phase, at which the response -is supposed to be generated. -Multiple nginx standard modules register their handers at this phase, for -example +No additional handlers can be registered at this phase. + + + +NGX_HTTP_TRY_FILES_PHASE — Special phase where +the directive +is processed. +No additional handlers can be registered at this phase. + + + +NGX_HTTP_CONTENT_PHASE — Phase where the response +is normally generated. +Multiple nginx standard modules register their handlers at this phase, +including ngx_http_index_module or ngx_http_static_module. -All these handlers are called sequentially until one of them finally produces +They are called sequentially until one of them produces the output. It's also possible to set content handlers on a per-location basis. If the ngx_http_core_module's -location configuration has handler set, this handler is -called as the content handler and content phase handlers are ignored - - - -NGX_HTTP_LOG_PHASE is used to perform request logging. +location configuration has handler set, it is +called as the content handler and the handlers installed at this phase +are ignored. + + + +NGX_HTTP_LOG_PHASE — Phase where request logging +is performed. Currently, only the ngx_http_log_module registers its handler at this stage for access logging. Log phase handlers are called at the very end of request processing, right -before freeing the request +before freeing the request. @@ -4532,43 +4626,45 @@ Phase handlers are expected to return sp -NGX_OK — proceed to the next phase - - - -NGX_DECLINED — proceed to the next handler of the current +NGX_OK — Proceed to the next phase. + + + +NGX_DECLINED — Proceed to the next handler of the current phase. -If current handler is the last in current phase, move to the next phase - - - -NGX_AGAIN, NGX_DONE — suspend phase handling until some -future event. -This can be for example asynchronous I/O operation or just a delay. -It is supposed, that phase handling will be resumed later by calling -ngx_http_core_run_phases() +If the current handler is the last in the current phase, +move to the next phase. + + + +NGX_AGAIN, NGX_DONE — Suspend +phase handling until some future event which can be +an asynchronous I/O operation or just a delay, for example. +It is assumed, that phase handling will be resumed later by calling +ngx_http_core_run_phases(). Any other value returned by the phase handler is treated as a request -finalization code, in particular, HTTP response code. -The request is finalized with the code provided +finalization code, in particular, an HTTP response code. +The request is finalized with the code provided. -Some phases treat return codes in a slightly different way. -At content phase, any return code other that NGX_DECLINED -is considered a finalization code. -As for the location content handlers, any return from them is considered a +For some phases, return codes are treated in a slightly different way. +At the content phase, any return code other that +NGX_DECLINED is considered a finalization code. +Any return code from the location content handlers is considered a finalization code. -At access phase, in +At the access phase, in satisfy any -mode, returning a code other -than NGX_OK, NGX_DECLINED, NGX_AGAIN, NGX_DONE is considered -a denial. -If none of future access handlers allow access or deny with a new +mode, +any return code other than NGX_OK, +NGX_DECLINED, NGX_AGAIN, +NGX_DONE is considered a denial. +If no subsequent access handlers allow or deny access with a different code, the denial code will become the finalization code. @@ -4580,11 +4676,11 @@ code, the denial code will become the fi
-Variables may be referenced using index (this is the most common method) -or names (see below in the section about creating variables). -Index is created at configuration stage, when a variable is added -to configuration. -The variable index can be obtained using +Variables can be referenced by index (this is the most common method) +or name (see below). +The index is created at configuration stage, when a variable is added +to the configuration. +To obtain the variable index, use ngx_http_get_variable_index(): ngx_str_t name; /* ngx_string("foo") */ @@ -4592,17 +4688,17 @@ ngx_int_t index; index = ngx_http_get_variable_index(cf, &name); -Here, the cf is a pointer to nginx configuration and the -name points to a string with the variable name. -The function returns NGX_ERROR on error or valid index -otherwise, which is typically stored somewhere in a module configuration for -future use. - - - -All HTTP variables are evaluated in the context of HTTP request and results -are specific to and cached in HTTP request. -All functions that evaluate variables return +Here, cf is a pointer to nginx configuration and +name points to a string containing the variable name. +The function returns NGX_ERROR on error or a valid index +otherwise, which is typically stored somewhere in the module's +configuration for future use. + + + +All HTTP variables are evaluated in the context of a given HTTP request, +and results are specific to and cached in that HTTP request. +All functions that evaluate variables return the ngx_http_variable_value_t type, representing the variable value: @@ -4623,31 +4719,31 @@ where: -len — length of a value - - - -data — value itself - - - -valid — value is valid - - - -not_found — variable was not found and thus +len — The length of the value + + + +data — The value itself + + + +valid — The value is valid + + + +not_found — The variable was not found and thus the data and len fields are irrelevant; -this may happen, for example, with such variables as $arg_foo +this can happen, for example, with variables like $arg_foo when a corresponding argument was not passed in a request -no_cacheable — do not cache result - - - -escape — used internally by the logging module to mark -values that require escaping on output +no_cacheable — Do not cache result + + + +escape — Used internally by the logging module to mark +values that require escaping on output. @@ -4656,11 +4752,11 @@ values that require escaping on output The ngx_http_get_flushed_variable() and ngx_http_get_indexed_variable() functions -are used to obtain the variable value. -They have the same interface - accepting a HTTP request r -as a context for evaluating the variable and an index, -identifying it. -Example of typical usage: +are used to obtain the value of a variable. +They have the same interface - accepting an HTTP request r +as a context for evaluating the variable and an index +that identifies it. +An example of typical usage: ngx_http_variable_value_t *v; @@ -4674,19 +4770,20 @@ if (v == NULL || v->not_found) { /* some meaningful value is found */ The difference between functions is that the -ngx_http_get_indexed_variable() returns cached value -and ngx_http_get_flushed_variable() flushes cache for +ngx_http_get_indexed_variable() returns a cached value +and ngx_http_get_flushed_variable() flushes the cache for non-cacheable variables. -There are cases when it is required to deal with variables which names are -not known at configuration time and thus they cannot be accessed using indexes, -for example in modules like SSI or Perl. -The ngx_http_get_variable(r, name, key) function may be -used in such cases. -It searches for the variable with a given -name and its hash key. +Some modules, such as SSI and Perl, need to deal with variables for which the +name is not known at configuration time. +An index therefore cannot be used to access them, but the +ngx_http_get_variable(r, name, key) function +is available. +It searches for a variable with a given +name and its hash key derived +from the name.
@@ -4695,42 +4792,43 @@ It searches for the variable -To create a variable ngx_http_add_variable() function -is used. -It takes configuration (where variable is registered), variable name and -flags that control its behaviour: +To create a variable, use the ngx_http_add_variable() +function. +It takes as arguments a configuration (where the variable is registered), +the variable name and flags that control the function's behaviour: -NGX_HTTP_VAR_CHANGEABLE — allows redefining -the variable; If another module will define a variable with such name, -no conflict will happen. -For example, this allows user to override variables using the - directive. - - -NGX_HTTP_VAR_NOCACHEABLE — disables caching, -is useful for such variables as $time_local - - -NGX_HTTP_VAR_NOHASH — indicates that +NGX_HTTP_VAR_CHANGEABLE — Enables redefinition of +the variable: there is no conflict if another module defines a variable with +the same name. +This allows the + directive +to override variables. + + +NGX_HTTP_VAR_NOCACHEABLE — Disables caching, +which is useful for variables such as $time_local. + + +NGX_HTTP_VAR_NOHASH — Indicates that this variable is only accessible by index, not by name. -This is a small optimization which may be used when it is known that the +This is a small optimization for use when it is known that the variable is not needed in modules like SSI or Perl. -NGX_HTTP_VAR_PREFIX — the name of this +NGX_HTTP_VAR_PREFIX — The name of the variable is a prefix. -A handler must implement additional logic to obtain value of specific -variable. +In this case, a handler must implement additional logic to obtain the value +of a specific variable. For example, all “arg_” variables are processed by the -same handler which performs lookup in request arguments and returns value -of specific argument. +same handler, which performs lookup in request arguments and returns the value +of a specific argument. The function returns NULL in case of error or a pointer to -ngx_http_variable_t: +ngx_http_variable_t otherwise: struct ngx_http_variable_s { ngx_str_t name; @@ -4744,15 +4842,16 @@ struct ngx_http_variable_s { The get and set handlers are called to obtain or set the variable value, -data will be passed to variable handlers, -index will hold assigned variable index, used to reference +data is passed to variable handlers, and +index holds assigned variable index used to reference the variable. -Usually, a null-terminated static array of such structures is created +Usually, a null-terminated static array of +ngx_http_variable_t structures is created by a module and processed at the preconfiguration stage to add variables -into configuration: +into the configuration, for example: static ngx_http_variable_t ngx_http_foo_vars[] = { @@ -4779,14 +4878,15 @@ ngx_http_foo_add_variables(ngx_conf_t *c return NGX_OK; } -This function is used to initialize the preconfiguration -field of the HTTP module context and is called before parsing HTTP configuration, -so it could refer to these variables. - - - -The get handler is responsible for evaluating the variable -in a context of specific request, for example: +This function in the example is used to initialize +the preconfiguration +field of the HTTP module context and is called before the parsing of HTTP +configuration, so that the parser can refer to these variables. + + + +The get handler is responsible for evaluating a variable +in the context of a specific request, for example: static ngx_int_t ngx_http_variable_connection(ngx_http_request_t *r, @@ -4810,14 +4910,15 @@ ngx_http_variable_connection(ngx_http_re It returns NGX_ERROR in case of internal error (for example, failed memory allocation) or NGX_OK otherwise. -The status of variable evaluation may be understood by inspecting flags -of the ngx_http_variable_value_t (see description above). +To learn the status of variable evaluation, inspect the flags +in ngx_http_variable_value_t (see the description +above). The set handler allows setting the property -referred by the variable. -For example, the $limit_rate variable set handler +referenced by the variable. +For example, the set handler of the $limit_rate variable modifies the request's limit_rate field: ... @@ -4864,14 +4965,14 @@ ngx_http_variable_request_set_size(ngx_h A complex value, despite its name, provides an easy way to evaluate -expressions that may contain text, variables, and their combination. +expressions which can contain text, variables, and their combination. The complex value description in ngx_http_compile_complex_value is compiled at the configuration stage into ngx_http_complex_value_t -which is used at runtime to obtain evaluated expression results. +which is used at runtime to obtain results of expression evaluation. ngx_str_t *value; @@ -4899,54 +5000,54 @@ initialize the complex value cv -cf — configuration pointer - - - -value — string for parsing (input) - - - -complex_value — compiled value (output) - - - -zero — flag that enables zero-terminating value - - - -conf_prefix — prefixes result with configuration prefix -(the directory where nginx is currently looking for configuration) - - - -root_prefix — prefixes result with root prefix -(this is the normal nginx installation prefix) +cf — Configuration pointer + + + +value — String to be parsed (input) + + + +complex_value — Compiled value (output) + + + +zero — Flag that enables zero-terminating value + + + +conf_prefix — Prefixes the result with the +configuration prefix (the directory where nginx is currently looking for +configuration) + + + +root_prefix — Prefixes the result with the root prefix +(the normal nginx installation prefix) -The zero flag is usable when results are to be passed to +The zero flag is useful when results are to be passed to libraries that require zero-terminated strings, and prefixes are handy when dealing with filenames. -Upon successful compilation, cv.lengths may -be inspected to get information about the presence of variables +Upon successful compilation, cv.lengths +contains information about the presence of variables in the expression. The NULL value means that the expression contained static text only, -and there is no need in storing it as a complex value, -so a simple string can be used. +and so can be stored in a simple string rather than as a complex value. The ngx_http_set_complex_value_slot() is a convenient -function used to initialize complex value completely right in the directive -declaration. - - - -At runtime, a complex value may be calculated using the +function used to initialize a complex value completely in the directive +declaration itself. + + + +At runtime, a complex value can be calculated using the ngx_http_complex_value() function: ngx_str_t res; @@ -4956,8 +5057,8 @@ if (ngx_http_complex_value(r, &cv, & } Given the request r and previously compiled -value cv the function will evaluate -expression and put result into res. +value cv, the function evaluates the +expression and writes the result to res.
@@ -4972,10 +5073,10 @@ 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. +Request location can change several times during the request's 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 +If the 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 @@ -4984,22 +5085,23 @@ At this phase a location is chosen by re configured for the server. The ngx_http_rewrite_module -may change the request URI at the +can 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 +the rewrite +directive and send the request back +to the NGX_HTTP_FIND_CONFIG_PHASE phase for selection of 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 +calling one of 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 ngx_http_internal_redirect(r, uri, args) function changes the request URI and returns the request to the NGX_HTTP_SERVER_REWRITE_PHASE phase. The request proceeds with a server default location. @@ -5051,18 +5153,28 @@ ngx_http_foo_named_redirect(ngx_http_req
-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 +Both functions - ngx_http_internal_redirect(r, uri, args) +and ngx_http_named_location(r, name) can be called when +nginx modules have already stored some contexts in a request's +ctx field. +It's possible for these contexts to 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 +Calling ngx_http_internal_redirect(r, uri, args) +or ngx_http_named_location(r, name) increases the request +count. +For consistent request reference counting, call +ngx_http_finalize_request(r, NGX_DONE) after redirecting the +request. +This will finalize current request code path and decrease the counter. + + + +Redirected and rewritten requests become internal and can access the internal locations. Internal requests have the internal flag set. @@ -5074,28 +5186,29 @@ Internal requests have the inte
-Subrequests are primarily used to include output of one request into another, +Subrequests are primarily used to insert output of one request into another, possibly mixed with other data. A subrequest looks like a normal request, but shares some data with its parent. -Particularly, all fields related to client input are shared since a subrequest -does not receive any other input from client. -The request field parent for a subrequest keeps a link to its -parent request and is NULL for the main request. -The field main keeps a link to the main request in a group of -requests. - - - -A subrequest starts with NGX_HTTP_SERVER_REWRITE_PHASE phase. -It passes through the same phases as a normal request and is assigned a location -based on its own URI. - - - -Subrequest output header is always ignored. -Subrequest output body is placed by the -ngx_http_postpone_filter into the right position in relation -to other data produced by the parent request. +In particular, all fields related to client input are shared +because a subrequest does not receive any other input from the client. +The request field parent for a subrequest contains a link +to its parent request and is NULL for the main request. +The field main contains a link to the main request in +a group of requests. + + + +A subrequest starts in the NGX_HTTP_SERVER_REWRITE_PHASE +phase. +It passes through the same subsequent phases as a normal request and is +assigned a location based on its own URI. + + + +The output header in a subrequest is always ignored. +The ngx_http_postpone_filter places the subrequest's +output body in the right position relative to other data produced +by the parent request. @@ -5103,76 +5216,78 @@ Subrequests are related to the concept o A request r is considered active if c->data == r, where c is the client connection object. -At any point, only the active request in a request group is allowed to output -its buffers to the client. -A non-active request can still send its data to the filter chain, but they -will not pass beyond the ngx_http_postpone_filter and will -remain buffered by that filter until the request becomes active. +At any given point, only the active request in a request group is allowed +to output its buffers to the client. +An inactive request can still send its output to the filter chain, but it +does not pass beyond the ngx_http_postpone_filter and +remains buffered by that filter until the request becomes active. Here are some rules of request activation: -Initially, the main request is active - - - -The first subrequest of an active request becomes active right after creation +Initially, the main request is active. + + + +The first subrequest of an active request becomes active right after creation. The ngx_http_postpone_filter activates the next request -in active request's subrequest list, once all data prior to that request are -sent - - - -When a request is finalized, its parent is activated +in the active request's subrequest list, once all data prior to that request +are sent. + + + +When a request is finalized, its parent is activated. -A subrequest is created by calling the function +Create a subrequest by calling the function ngx_http_subrequest(r, uri, args, psr, ps, flags), where r is the parent request, uri and -args are URI and arguments of the -subrequest, psr is the output parameter, receiving the +args are the URI and arguments of the +subrequest, psr is the output parameter, which receives the newly created subrequest reference, ps is a callback object -for notifying the parent request that the subrequest is being finalized, -flags is subrequest creation flags bitmask. +for notifying the parent request that the subrequest is being finalized, and +flags is bitmask of flags. The following flags are available: -NGX_HTTP_SUBREQUEST_IN_MEMORY - subrequest output should not -be sent to the client, but rather stored in memory. -This only works for proxying subrequests. -After subrequest finalization its output is available in -r->upstream->buffer buffer of type -ngx_buf_t - - - -NGX_HTTP_SUBREQUEST_WAITED - the subrequest -done flag is set even if it is finalized being non-active. -This subrequest flag is used by the SSI filter - - - -NGX_HTTP_SUBREQUEST_CLONE - the subrequest is created as a +NGX_HTTP_SUBREQUEST_IN_MEMORY - Output is not +sent to the client, but rather stored in memory. +The flag only affects subrequests which are processed by one of the proxying +modules. +After a subrequest is finalized its output is available in +a r->upstream->buffer of type ngx_buf_t. + + + +NGX_HTTP_SUBREQUEST_WAITED - The subrequest's +done flag is set even if the subrequest is not active when +it is finalized. +This subrequest flag is used by the SSI filter. + + + +NGX_HTTP_SUBREQUEST_CLONE - The subrequest is created as a clone of its parent. It is started at the same location and proceeds from the same phase as the -parent request +parent request. -The following example creates a subrequest with the URI of "/foo". +The following example creates a subrequest with the URI +of /foo. @@ -5228,14 +5343,13 @@ ngx_http_foo_subrequest_done(ngx_http_re -Subrequests are normally created in a body filter. -In this case subrequest output can be treated as any other explicit request -output. -This means that eventually the output of a subrequest is sent to the client -after all explicit buffers passed prior to subrequest creation and before any -buffers passed later. +Subrequests are normally created in a body filter, in which case their output +can be treated like the output from any explicit request. +This means that eventually the output of a subrequest is sent to the client, +after all explicit buffers that are passed before subrequest creation and +before any buffers that are passed after creation. This ordering is preserved even for large hierarchies of subrequests. -The following example inserts a subrequest output after all request data +The following example inserts output from a subrequest after all request data buffers, but before the final buffer with the last_buf flag. @@ -5286,7 +5400,6 @@ ngx_http_foo_body_filter(ngx_http_reques ngx_http_set_ctx(r, NULL, ngx_http_foo_filter_module); - /* Output the final buffer with the last_buf flag */ b = ngx_calloc_buf(r->pool); @@ -5304,14 +5417,14 @@ ngx_http_foo_body_filter(ngx_http_reques -A subrequest may also be created for other purposes than data output. +A subrequest can also be created for other purposes than data output. For example, the -ngx_http_auth_request_module -creates a subrequest at NGX_HTTP_ACCESS_PHASE phase. -To disable any output at this point, the subrequest -header_only flag is set. -This prevents subrequest body from being sent to the client. -Its header is ignored anyway. +ngx_http_auth_request_module module +creates a subrequest at the NGX_HTTP_ACCESS_PHASE phase. +To disable output at this point, the +header_only flag is set on the subrequest. +This prevents the subrequest body from being sent to the client. +Note that the subrequest's header is never sent to the client. The result of the subrequest can be analyzed in the callback handler. @@ -5323,12 +5436,12 @@ The result of the subrequest can be anal An HTTP request is finalized by calling the function ngx_http_finalize_request(r, rc). -It is usually finalized by the content handler after sending all output buffers -to the filter chain. -At this point the output may not be completely sent to the client, but remain -buffered somewhere along the filter chain. -If it is, the ngx_http_finalize_request(r, rc) function will -automatically install a special handler ngx_http_writer(r) +It is usually finalized by the content handler after all output buffers +are sent to the filter chain. +At this point all of the output might not be sent to the client, +with some of it remaining buffered somewhere along the filter chain. +If it is, the ngx_http_finalize_request(r, rc) function +automatically installs a special handler ngx_http_writer(r) to finish sending the output. A request is also finalized in case of an error or if a standard HTTP response code needs to be returned to the client. @@ -5342,35 +5455,37 @@ following rc values: -NGX_DONE - fast finalization. -Decrement request count and destroy the request if it +NGX_DONE - Fast finalization. +Decrement the request count and destroy the request if it reaches zero. -The client connection may still be used for more requests after that +The client connection can be used for more requests after the current request +is destroyed. NGX_ERROR, NGX_HTTP_REQUEST_TIME_OUT -(408), NGX_HTTP_CLIENT_CLOSED_REQUEST (499) - error -finalization. +(408), NGX_HTTP_CLIENT_CLOSED_REQUEST +(499) - Error finalization. Terminate the request as soon as possible and close the client connection. -NGX_HTTP_CREATED (201), -NGX_HTTP_NO_CONTENT (204), codes greater than or equal to -NGX_HTTP_SPECIAL_RESPONSE (300) - special response -finalization. -For these values nginx either sends a default code response page to the client -or performs the internal redirect to an - location if it's -configured for the code - - - -Other codes are considered success finalization codes and may activate the +NGX_HTTP_CREATED (201), +NGX_HTTP_NO_CONTENT (204), codes greater +than or equal to NGX_HTTP_SPECIAL_RESPONSE +(300) - Special response finalization. +For these values nginx either sends to the client a default response page for +the code or performs the internal redirect to an + location if that +is configured for the code. + + + +Other codes are considered successful finalization codes and might activate the request writer to finish sending the response body. -Once body is completely sent, request count is decremented. -If it reaches zero, the request is destroyed, but the client connection may +Once the body is completely sent, the request count +is decremented. +If it reaches zero, the request is destroyed, but the client connection can still be used for other requests. If count is positive, there are unfinished activities within the request, which will be finalized at a later point. @@ -5384,21 +5499,21 @@ within the request, which will be finali
-For dealing with client request body, nginx provides the following functions: +For dealing with the body of a client request, nginx provides the ngx_http_read_client_request_body(r, post_handler) and -ngx_http_discard_request_body(r). +ngx_http_discard_request_body(r) functions. The first function reads the request body and makes it available via the request_body request field. The second function instructs nginx to discard (read and ignore) the request body. One of these functions must be called for every request. -Normally, it is done in the content handler. - - - -Reading or discarding client request body from a subrequest is not allowed. -It should always be done in the main request. -When a subrequest is created, it inherits the parent +Normally, the content handler makes the call. + + + +Reading or discarding the client request body from a subrequest is not allowed. +It must always be done in the main request. +When a subrequest is created, it inherits the parent's request_body object which can be used by the subrequest if the main request has previously read the request body. @@ -5409,20 +5524,22 @@ The function the process of reading the request body. When the body is completely read, the post_handler callback is called to continue processing the request. -If request body is missing or already read, the callback is called immediately. +If the request body is missing or has already been read, the callback is called +immediately. The function ngx_http_read_client_request_body(r, post_handler) allocates the request_body request field of type ngx_http_request_body_t. The field bufs of this object keeps the result as a buffer chain. -The body can be saved in memory buffers or file buffers, if +The body can be saved in memory buffers or file buffers, if the capacity +specified by the -is not enough to fit the entire body in memory. - - - -The following example reads client request body and returns its size. +directive is not enough to fit the entire body in memory. + + + +The following example reads a client request body and returns its size. @@ -5491,62 +5608,60 @@ ngx_http_foo_init(ngx_http_request_t *r) -The following fields of the request affect the way request body is read: +The following fields of the request determine how the request body is read: -request_body_in_single_buf - read body to a single memory -buffer - - - -request_body_in_file_only - always read body to a file, -even if fits the memory buffer - - - -request_body_in_persistent_file - do not unlink the file -right after creation. -Such a file can be moved to another directory - - - -request_body_in_clean_file - unlink the file the when the +request_body_in_single_buf - Read the body to a single memory +buffer. + + + +request_body_in_file_only - Always read the body to a file, +even if fits in the memory buffer. + + + +request_body_in_persistent_file - Do not unlink the file +immediately after creation. +A file with this flag can be moved to another directory. + + + +request_body_in_clean_file - Unlink the file when the request is finalized. This can be useful when a file was supposed to be moved to another directory -but eventually was not moved for some reason - - - -request_body_file_group_access - enable file group access. -By default a file is created with 0600 access mask. -When the flag is set, 0660 access mask is used - - - -request_body_file_log_level - log file errors with this -log level - - - -request_body_no_buffering - read request body without -buffering +but was not moved for some reason. + + + +request_body_file_group_access - Enable group access to the +file by replacing the default 0600 access mask with 0660. + + + +request_body_file_log_level - Severity level at which to +log file errors. + + + +request_body_no_buffering - Read the request body without +buffering. -When the request_body_no_buffering flag is set, the -unbuffered mode of reading the request body is enabled. +The request_body_no_buffering flag enables the +unbuffered mode of reading a request body. In this mode, after calling ngx_http_read_client_request_body(), the -bufs chain may keep only a part of the body. -To read the next part, the -ngx_http_read_unbuffered_request_body(r) function should be -called. -The return value of NGX_AGAIN and the request flag +bufs chain might keep only a part of the body. +To read the next part, call the +ngx_http_read_unbuffered_request_body(r) function. +The return value NGX_AGAIN and the request flag reading_body indicate that more data is available. If bufs is NULL after calling this function, there is nothing to read at the moment. @@ -5560,7 +5675,7 @@ the next part of request body is availab
-An HTTP response in nginx is produced by sending the response header followed by +In nginx an HTTP response is produced by sending the response header followed by the optional response body. Both header and body are passed through a chain of filters and eventually get written to the client socket. @@ -5572,19 +5687,18 @@ and process the output coming from the p
-Output header is sent by the function -ngx_http_send_header(r). -Prior to calling this function, r->headers_out should contain -all the data required to produce the HTTP response header. -It's always required to set the status field of -r->headers_out. -If the response status suggests that a response body follows the header, +The ngx_http_send_header(r) +function sends the output header. +Do not call this function until r->headers_out +contains all of the data required to produce the HTTP response header. +The status field in r->headers_out +must always be set. +If the response status indicates that a response body follows the header, content_length_n can be set as well. -The default value for this field is -1, which means that the body size is -unknown. +The default value for this field is -1, +which means that the body size is unknown. In this case, chunked transfer encoding is used. -To output an arbitrary header, headers list should be -appended. +To output an arbitrary header, append the headers list. @@ -5629,26 +5743,27 @@ ngx_http_foo_content_handler(ngx_http_re The ngx_http_send_header(r) function invokes the header -filter chain by calling the top header filter handler -ngx_http_top_header_filter. -It's assumed that every header handler calls the next handler in chain until -the final handler ngx_http_header_filter(r) is called. +filter chain by calling the first header filter handler stored in +the ngx_http_top_header_filter variable. +It's assumed that every header handler calls the next handler in the chain +until the final handler ngx_http_header_filter(r) is called. The final header handler constructs the HTTP response based on r->headers_out and passes it to the ngx_http_writer_filter for output. -To add a handler to the header filter chain, one should store its address in -ngx_http_top_header_filter global variable at configuration -time. -The previous handler address is normally stored in a module's static variable +To add a handler to the header filter chain, store its address in +the global variable ngx_http_top_header_filter +at configuration time. +The previous handler address is normally stored in a static variable in a module and is called by the newly added handler before exiting. -The following is an example header filter module, adding the HTTP header -"X-Foo: foo" to every output with the status 200. +The following example of a header filter module adds the HTTP header +"X-Foo: foo" to every response with status +200. @@ -5740,20 +5855,20 @@ ngx_http_foo_header_filter_init(ngx_conf
-Response body is sent by calling the function -ngx_http_output_filter(r, cl). +To send the response body, call the +ngx_http_output_filter(r, cl) function. The function can be called multiple times. -Each time it sends a part of the response body passed as a buffer chain. -The last body buffer should have the last_buf flag set. - - - -The following example produces a complete HTTP output with "foo" as its body. -In order for the example to work not only as a main request but as a subrequest -as well, the last_in_chain flag is set in the last buffer +Each time, it sends a part of the response body in the form of a buffer chain. +Set the last_buf flag in the last body buffer. + + + +The following example produces a complete HTTP response with "foo" as its body. +For the example to work as subrequest as well as a main request, +the last_in_chain flag is set in the last buffer of the output. -The last_buf flag is set only for the main request since -a subrequest's last buffers does not end the entire output. +The last_buf flag is set only for the main request because +the last buffer for a subrequest does not end the entire output. @@ -5804,9 +5919,9 @@ ngx_http_bar_content_handler(ngx_http_re The function ngx_http_output_filter(r, cl) invokes the -body filter chain by calling the top body filter handler -ngx_http_top_body_filter. -It's assumed that every body handler calls the next handler in chain until +body filter chain by calling the first body filter handler stored in +the ngx_http_top_body_filter variable. +It's assumed that every body handler calls the next handler in the chain until the final handler ngx_http_write_filter(r, cl) is called. @@ -5815,17 +5930,16 @@ A body filter handler receives a chain o The handler is supposed to process the buffers and pass a possibly new chain to the next handler. It's worth noting that the chain links ngx_chain_t of the -incoming chain belong to the caller. -They should never be reused or changed. +incoming chain belong to the caller, and must not be reused or changed. Right after the handler completes, the caller can use its output chain links to keep track of the buffers it has sent. -To save the buffer chain or to substitute some buffers before sending further, -a handler should allocate its own chain links. - - - -Following is the example of a simple body filter counting the number of -body bytes. +To save the buffer chain or to substitute some buffers before passing to the +next filter, a handler needs to allocate its own chain links. + + + +Following is an example of a simple body filter that counts the number of +bytes in the body. The result is available as the $counter variable which can be used in the access log. @@ -5969,28 +6083,30 @@ ngx_http_counter_filter_init(ngx_conf_t
-When writing a body or header filter, a special care should be taken of the -filters order. +When writing a body or header filter, pay special attention to the filter's +position in the filter order. There's a number of header and body filters registered by nginx standard modules. -It's important to register a filter module in the right place in respect to -other filters. -Normally, filters are registered by modules in their postconfiguration handlers. -The order in which filters are called is obviously the reverse of when they are -registered. - - - -A special slot HTTP_AUX_FILTER_MODULES for third-party filter -modules is provided by nginx. -To register a filter module in this slot, the ngx_module_type -variable should be set to the value of HTTP_AUX_FILTER in -module's configuration. - - - -The following example shows a filter module config file assuming it only has -one source file ngx_http_foo_filter_module.c +The nginx standard modules register a number of head and body filters and it's +important to register a new filter module in the right place with respect to +them. +Normally, modules register filters in their postconfiguration handlers. +The order in which filters are called during processing is obviously the +reverse of the order in which they are registered. + + + +For third-party filter modules nginx provides a special slot +HTTP_AUX_FILTER_MODULES. +To register a filter module in this slot, set +the ngx_module_type variable to +HTTP_AUX_FILTER in the module's configuration. + + + +The following example shows a filter module config file assuming +for a module with just +one source file, ngx_http_foo_filter_module.c. @@ -6009,37 +6125,38 @@ ngx_module_srcs="$ngx_addon_dir/ngx_http When issuing or altering a stream of buffers, it's often desirable to reuse the allocated buffers. -A standard approach widely adopted in nginx code is to keep two buffer chains -for this purpose: free and busy. -The free chain keeps all free buffers. -These buffers can be reused. +A standard and widely adopted approach in nginx code is to keep +two buffer chains for this purpose: +free and busy. +The free chain keeps all free buffers, +which can be reused. The busy chain keeps all buffers sent by the current -module which are still in use by some other filter handler. +module that are still in use by some other filter handler. A buffer is considered in use if its size is greater than zero. Normally, when a buffer is consumed by a filter, its pos (or file_pos for a file buffer) is moved towards last (file_last for a file buffer). Once a buffer is completely consumed, it's ready to be reused. -To update the free chain with newly freed buffers, +To add newly freed buffers to the free chain it's enough to iterate over the busy chain and move the zero size buffers at the head of it to free. -This operation is so common that there is a special function -ngx_chain_update_chains(free, busy, out, tag) which does -this. +This operation is so common that there is a special function for it, +ngx_chain_update_chains(free, busy, out, tag). The function appends the output chain out to busy and moves free buffers from the top of busy to free. -Only the buffers with the given tag are reused. -This lets a module reuse only the buffers allocated by itself. - - - -The following example is a body filter inserting the “foo” string before each +Only the buffers with the specified tag are reused. +This lets a module reuse only the buffers that it allocated itself. + + + +The following example is a body filter that inserts the string “foo” before each incoming buffer. The new buffers allocated by the module are reused if possible. -Note that for this example to work properly, it's also required to set up a -header filter and reset content_length_n to -1, which is -beyond the scope of this section. +Note that for this example to work properly, setting up a +header filter +and resetting content_length_n to -1 +is also required, but the relevant code is not provided here. @@ -6124,33 +6241,34 @@ ngx_http_foo_body_filter(ngx_http_reques The ngx_http_upstream_module -provides basic functionality to pass requests to remote servers. -This functionality is used by modules that implement specific protocols, -such as HTTP or FastCGI. +provides the basic functionality needed to pass requests to remote servers. +Modules that implement specific protocols, such as HTTP or FastCGI, use +this functionality. The module also provides an interface for creating custom -load balancing modules and implements a default round-robin balancing method. - - - -Examples of modules that implement alternative load balancing methods are - -and . -Note that these modules are actually implemented as extensions of the upstream -module and share a lot of code, such as representation of a server group. +load-balancing modules and implements a default round-robin method. + + + +The +and +modules implement alternative load-balancing methods, but +are actually implemented as extensions of the upstream round-robin +module and share a lot of code with it, such as the representation +of a server group. The module -is an example of an independent module, extending upstream functionality. +is an independent module that extends upstream functionality. The ngx_http_upstream_module -may be configured explicitly by placing the corresponding +can be configured explicitly by placing the corresponding block into the configuration file, or implicitly by using directives -that accept a URL evaluated at some point to the list of servers, -for example, -. -Only explicit configurations may use an alternative load balancing method. +such as +that accept a URL that gets evaluated at some point into a list of servers. +The alternative load-balancing methods are available only with an explicit +upstream configuration. The upstream module configuration has its own directive context NGX_HTTP_UPS_CONF. The structure is defined as follows: @@ -6177,59 +6295,61 @@ struct ngx_http_upstream_srv_conf_s { -srv_conf — configuration context of upstream modules - - - -servers — array of +srv_conf — Configuration context of upstream modules. + + + +servers — Array of ngx_http_upstream_server_t, the result of parsing a set of directives -in the upstream block - - - -flags — flags that mostly mark which features -(configured as parameters of -the directive) -are supported by the particular load balancing method. +in the upstream block. + + + +flags — Flags that mostly mark which features +are supported by the load-balancing method. +The features are configured as parameters of +the directive: + -NGX_HTTP_UPSTREAM_CREATE — used to distinguish explicitly -defined upstreams from automatically created by - and “friends” +NGX_HTTP_UPSTREAM_CREATE — Distinguishes explicitly +defined upstreams from those that are automatically created by the + directive +and “friends” (FastCGI, SCGI, etc.) -NGX_HTTP_UPSTREAM_WEIGHT — “weight” -is supported - - - -NGX_HTTP_UPSTREAM_MAX_FAILS — “max_fails” -is supported +NGX_HTTP_UPSTREAM_WEIGHT — The “weight” +parameter is supported + + + +NGX_HTTP_UPSTREAM_MAX_FAILS — The +“max_fails” parameter is supported NGX_HTTP_UPSTREAM_FAIL_TIMEOUT — -“fail_timeout” is supported - - - -NGX_HTTP_UPSTREAM_DOWN — “down” -is supported - - - -NGX_HTTP_UPSTREAM_BACKUP — “backup” -is supported - - - -NGX_HTTP_UPSTREAM_MAX_CONNS — “max_conns” -is supported +The “fail_timeout” parameter is supported + + + +NGX_HTTP_UPSTREAM_DOWN — The “down” +parameter is supported + + + +NGX_HTTP_UPSTREAM_BACKUP — The “backup” +parameter is supported + + + +NGX_HTTP_UPSTREAM_MAX_CONNS — The +“max_conns” parameter is supported @@ -6237,25 +6357,26 @@ is supported -host — the name of an upstream - - - -file_name, line — the name of the configuration file -and the line where the upstream block is located - - - -port and no_port — unused by explicit -upstreams - - - -shm_zone — a shared memory zone used by this upstream, if any - - - -peer — an object that holds generic methods for +host — Name of the upstream. + + + +file_name, line — Name of the configuration file +and the line where the upstream block is located. + + + +port and no_port — Not used for +explicitly defined upstream groups. + + + +shm_zone — Shared memory zone used by this upstream group, +if any. + + + +peer — object that holds generic methods for initializing upstream configuration: @@ -6265,28 +6386,30 @@ typedef struct { void *data; } ngx_http_upstream_peer_t; -A module that implements a load balancing algorithm must set these +A module that implements a load-balancing algorithm must set these methods and initialize private data. If init_upstream was not initialized during configuration -parsing, ngx_http_upstream_module sets it to default -ngx_http_upstream_init_round_robin. +parsing, ngx_http_upstream_module sets it to the default +ngx_http_upstream_init_round_robin algorithm. -init_upstream(cf, us) — configuration-time +init_upstream(cf, us) — Configuration-time method responsible for initializing a group of servers and initializing the init() method in case of success. -A typical load balancing module uses a list of servers in the upstream block -to create some efficient data structure that it uses and saves own +A typical load-balancing module uses a list of servers in the +upstream block +to create an efficient data structure that it uses and saves its own configuration to the data field. -init(r, us) — initializes per-request -ngx_http_upstream_peer_t.peer (not to be confused with the +init(r, us) — Initializes a per-request +ngx_http_upstream_peer_t.peer structure that is used for +load balancing (not to be confused with the ngx_http_upstream_srv_conf_t.peer described above which -is per-upstream) structure that is used for load balancing. -It will be passed as data argument to all callbacks that +is per-upstream). +It is passed as the data argument to all callbacks that deal with server selection. @@ -6297,13 +6420,13 @@ deal with server selection. When nginx has to pass a request to another host for processing, it uses -a configured load balancing method to obtain an address to connect to. -The method is taken from the +the configured load-balancing method to obtain an address to connect to. +The method is obtained from the ngx_http_upstream_t.peer object of type ngx_peer_connection_t: struct ngx_peer_connection_s { - [...] + ... struct sockaddr *sockaddr; socklen_t socklen; @@ -6321,7 +6444,7 @@ struct ngx_peer_connection_s { ngx_event_save_peer_session_pt save_session; #endif - [..] + ... }; @@ -6330,28 +6453,28 @@ The structure has the following fields: sockaddr, socklen, -name — address of an upstream server to connect to; -this is the output parameter of a load balancing method - - - -data — per-request load balancing method data; keeps the -state of selection algorithm and usually includes the link to upstream -configuration. -It will be passed as an argument to all methods that deal with server selection -(see below) - - - -tries — allowed +name — Address of the upstream server to connect to; +this is the output parameter of a load-balancing method. + + + +data — The per-request data of a load-balancing method; +keeps the state of the selection algorithm and usually includes the link +to the upstream configuration. +It is passed as an argument to all methods that deal with server selection +(see below). + + + +tries — Allowed number -of attempts to connect to an upstream. +of attempts to connect to an upstream server. get, free, notify, set_session, and save_session -- methods of the load balancing module, see description below +- Methods of the load-balancing module, described below. @@ -6359,54 +6482,54 @@ of attempts to connect to an upstream. -All methods accept at least two arguments: peer connection object +All methods accept at least two arguments: a peer connection object pc and the data created by ngx_http_upstream_srv_conf_t.peer.init(). -Note that in general case it may differ from pc.data due -to “chaining” of load balancing modules. +Note that it might differ from pc.data due +to “chaining” of load-balancing modules. - -get(pc, data) — the method is called when the upstream + +get(pc, data) — The method called when the upstream module is ready to pass a request to an upstream server and needs to know its address. -The method is responsible to fill in the sockaddr, +The method has to fill the sockaddr, socklen, and name fields of ngx_peer_connection_t structure. -The return value may be one of: +The return is one of: -NGX_OK — server was selected - - - -NGX_ERROR — internal error occurred - - - -NGX_BUSY — there are no available servers at the moment. -This can happen due to many reasons, such as: dynamic server group is empty, -all servers in the group are in the failed state, +NGX_OK — Server was selected. + + + +NGX_ERROR — Internal error occurred. + + + +NGX_BUSY — no servers are currently available. +This can happen due to many reasons, including: the dynamic server group is +empty, all servers in the group are in the failed state, or all servers in the group are already -handling the maximum number of connections or similar. - - - -NGX_DONE — this is set by the keepalive -module to indicate that the underlying connection was reused and there is no -need to create a new connection to the upstream server. +handling the maximum number of connections. + + + +NGX_DONE — the underlying connection was reused and there +is no need to create a new connection to the upstream server. +This value is set by the keepalive module. @@ -6415,28 +6538,44 @@ of this request should be postponed. -free(pc, data, state) — the method is called when an +free(pc, data, state) — The method called when an upstream module has finished work with a particular server. -The state argument is the status of upstream connection -completion. -This is a bitmask, the following values may be set: -NGX_PEER_FAILED — this attempt is considered -unsuccessful, -NGX_PEER_NEXT — a special case with codes 403 and 404 -(see link above), which are not considered a failure. -NGX_PEER_KEEPALIVE. -Also, tries counter is decremented by this method. - - - -notify(pc, data, type) — currently unused +The state argument is the completion status of the upstream +connection, a bitmask with the following possible values: + + + + +NGX_PEER_FAILED — Attempt was +unsuccessful + + + +NGX_PEER_NEXT — A special case when upstream server +returns codes 403 or 404, +which are not considered a +failure. + + + +NGX_PEER_KEEPALIVE — Currently unused + + + + +This method also decrements the tries counter. + + + + +notify(pc, data, type) — Currently unused in the OSS version. set_session(pc, data) and save_session(pc, data) -— SSL-specific methods that allow to cache sessions to upstream +— SSL-specific methods that enable caching sessions to upstream servers. The implementation is provided by the round-robin balancing method.