+ + +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. +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. +The module +is an example of an independent module, extending upstream functionality. + + + +The +ngx_http_upstream_module +may 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. +The upstream module configuration has its own directive context +NGX_HTTP_UPS_CONF. +The structure is defined as follows: + +struct ngx_http_upstream_srv_conf_s { + ngx_http_upstream_peer_t peer; + void **srv_conf; + + ngx_array_t *servers; /* ngx_http_upstream_server_t */ + + ngx_uint_t flags; + ngx_str_t host; + u_char *file_name; + ngx_uint_t line; + in_port_t port; + ngx_uint_t no_port; /* unsigned no_port:1 */ + +#if (NGX_HTTP_UPSTREAM_ZONE) + ngx_shm_zone_t *shm_zone; +#endif +}; + + + + + +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. + + + + +NGX_HTTP_UPSTREAM_CREATE — used to distinguish explicitly +defined upstreams from automatically created by + and “friends” +(FastCGI, SCGI, etc.) + + + +NGX_HTTP_UPSTREAM_WEIGHT — “weight” +is supported + + + +NGX_HTTP_UPSTREAM_MAX_FAILS — “max_fails” +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 + + + + + + + +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 +initializing upstream configuration: + + +typedef struct { + ngx_http_upstream_init_pt init_upstream; + ngx_http_upstream_init_peer_pt init; + void *data; +} ngx_http_upstream_peer_t; + +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. + + + +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 +configuration to the data field. + + + +init(r, us) — initializes per-request +ngx_http_upstream_peer_t.peer (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 +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 +ngx_http_upstream_peer_t.peer object +of type ngx_peer_connection_t: + +struct ngx_peer_connection_s { + [...] + + struct sockaddr *sockaddr; + socklen_t socklen; + ngx_str_t *name; + + ngx_uint_t tries; + + ngx_event_get_peer_pt get; + ngx_event_free_peer_pt free; + ngx_event_notify_peer_pt notify; + void *data; + +#if (NGX_SSL || NGX_COMPAT) + ngx_event_set_peer_session_pt set_session; + ngx_event_save_peer_session_pt save_session; +#endif + + [..] +}; + + +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 +number +of attempts to connect to an upstream. + + + +get, free, notify, +set_session, and save_session +- methods of the load balancing module, see description below + + + + + + + +All methods accept at least two arguments: 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. + + + + + + +get(pc, data) — the method is 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, +socklen, and name fields of +ngx_peer_connection_t structure. +The return value may be 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, +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. + + + + + + + + + +free(pc, data, state) — the method is 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 +in the OSS version. + + + +set_session(pc, data) and +save_session(pc, data) +— SSL-specific methods that allow to cache sessions to upstream +servers. +The implementation is provided by the round-robin balancing method. + + + + + +