http_upstream_sticky module

New in version 1.2.0.

Provides session persistence functionality, ensuring all requests in the client session are passed to the same backend server in upstream group.

This module is enabled by default, it could be disabled with ‑‑without‑http_upstream_sticky_module configuration parameter.

Example Configuration

upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie cookie_name domain=example.com secure;
}

server {
    location / {
        proxy_pass http://backend;
    }
}

Directives

sticky

Syntax:

sticky cookie name [attr1=value] [attr2=value] [attr3] …;
sticky route $variable [$variable2] [$variable3] …;

Default:

—

Context:

upstream

Session persistence can be configured using either cookie or route method, specified as first argument.

cookie: information about the designated server is passed in an HTTP cookie generated by Angie.

A request that comes from a client not yet bound to a particular server is passed to the server selected by the configured balancing method. Further requests with this cookie will be passed to the designated server. If the designated server cannot process a request, the new server is selected as if the client has not been bound yet.

It’s allowed to set an arbitrary attribute for the cookie, the only one set by default is path=/. Attribute can be set using text, variables and their combination. Also, it’s possible to reset any cookie attribute by configuring it empty: attr=. For instance, with sticky cookie path= Angie will set the cookie with no path attribute.

upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie example domain=$my_domain max-age=3600;
}

The cookie value is a hexadecimal representation of the MD5 hash of the IP address and port, or of the UNIX-domain socket path. However,

• if the sid parameter of the server directive is specified, the cookie value will be the value of the sid parameter;

• if sticky_secret is specified, then the value will be hashed with provided salt.

route: proxied server assigns client a route on receipt when a session starts.

When the route method is used, proxied server assigns client a route on receipt of the first request. All subsequent requests from this client will carry routing information in a cookie or URI. This information is compared with the sid parameter of the server directive to identify the server to which the request should be proxied. If the sid parameter is not specified, the route name will be a hexadecimal representation of the MD5 hash of the IP address and port, or of the UNIX-domain socket path. If the designated server cannot process a request, the new server is selected by the configured balancing method as if there is no routing information in the request.

upstream backend {
    server backend1.example.com:8080 sid="server1";
    server backend2.example.com:8080 sid="server2";

    sticky route $cookie_route $arg_route;
}

Configured as above, Angie searches for sid in cookie 'route' first, then in request argument (URI) 'route'.

sticky_strict

Syntax:

sticky_strict on | off;

Default:

sticky_strict off;

Context:

upstream

When enabled, makes Angie to return http 502 error to the client if desired server is not available instead of using any other available, as in case when no server in upstream is available.

sticky_secret

Syntax:

sticky_secret $complex_value;

Default:

—

Context:

upstream

Makes Angie to protect cookie value by hashing it with salt. Salt may contain variables, for example, client address:

upstream backend {
    server backend1.example.com:8080;
    server backend2.example.com:8080;

    sticky cookie cookie_name;
    sticky_secret my_secret.$remote_addr;
}

Embedded Variables

The http_upstream_sticky module supports the following embedded variables:

$upstream_sticky_status

Status of sticky request.

''	the request to the upstream with no sticky enabled
NEW	request without sticky information
HIT	request with sticky information was routed to desired backend
MISS	request with sticky information was routed to backend selected by balancing algorithm

Values from several connections are separated by commas and colons like addresses in the $upstream_addr variable.