Upstream Sticky#

Binds client sessions to servers in groups of the Stream Upstream module, so that connections from one session are passed to the same server. The module's directives are set in the upstream block.

When building from the source code, the module is built by default together with the Stream module (enabled with --with-stream); it can be disabled with the build option --without-stream_upstream_sticky_module.

In packages and images from our repositories, the module is included in the build.

Configuration Example#

upstream backend {
    zone backend 1m;
    server backend1.example.com:1935;
    server backend2.example.com:1935;

    sticky learn zone=clients:1m create=$remote_addr lookup=$remote_addr;
}

Angie binds each client address to the server of its first session and passes later connections from that address to the same server.

Directives#

sticky#

Syntax

sticky route value...;

sticky learn zone=zone create=$create_var1... lookup=$lookup_var1... [connect] [norefresh] [timeout=time];

sticky learn [zone=zone] lookup=$lookup_var1... remote_action=uri remote_result=$remote_var [remote_uri=uri] [norefresh] [timeout=time]; (PRO)

Default

—

Context

upstream

Configures sticky sessions between clients and upstream servers, depending on the mode specified in the first parameter. To gradually take servers with sticky out of rotation, you can use the drain option in the server block.

Warning

The sticky directive must appear after all load balancing method directives, otherwise it won't work.

This mode uses predefined route identifiers that can be embedded in connection properties accessible to Angie. It is less flexible as it depends on predefined values, but is better suited if such identifiers are already in use.

Here, when establishing a connection, the upstream server can assign a route to the client and return its identifier in a way known to both parties. The route identifier should use the value of the sid parameter of the server directive. Note that the parameter is additionally hashed if the sticky_secret directive is specified.

Subsequent connections from clients wishing to use this route must contain the identifier issued by the server, in such a way that it ends up in Angie variables.

The directive parameters specify strings that may include variables for routing. To select the server where the incoming connection is directed, the first non-empty value is used; it is then compared with the sid parameter of the server directive. If server selection fails or the selected server cannot accept the connection, another server will be selected according to the configured load balancing method.

Here Angie looks for the route identifier in the $route variable, which receives its value based on $ssl_preread_server_name (note that ssl_preread must be enabled):

stream {

    map $ssl_preread_server_name $route {

        a.example.com            a;
        b.example.com            b;
        default                  "";
    }

    upstream backend {

        zone backend 1m;

        server 127.0.0.1:8081 sid=a;
        server 127.0.0.1:8082 sid=b;

        sticky route $route;
    }

    server {

        listen 127.0.0.1:8080;

        ssl_preread on;

        proxy_pass backend;
    }
}

The sticky directive takes into account the state of servers in upstream:

  • Servers marked as down or temporarily unavailable due to failures are excluded from selection.

  • Servers that have reached the maximum number of connections (when using max_conns) are temporarily skipped.

  • Servers with the drain option can be selected for creating new sessions in sticky mode when identifiers match.

  • If a previously unavailable server recovers, sticky automatically resumes using it.

The behavior of sticky can be further configured with the sticky_secret and sticky_strict directives. If sticky fails to select a server or it is unavailable, the request will be handled according to the selected load balancing method, unless the sticky_strict directive is enabled. In sticky_strict on; mode, the request is rejected with an error.

Shared memory zones specified in the zone parameter of the sticky directive cannot be shared between different upstream groups; each group must use its own zone.

sticky_secret#

Syntax

sticky_secret string;

Default

—

Context

upstream

Adds string as salt to the MD5 hash function for the sticky directive in route mode. String can contain variables, for example $remote_addr:

upstream backend {
    zone backend 1m;
    server 127.0.0.1:8081 sid=a;
    server 127.0.0.1:8082 sid=b;

    sticky route $route;
    sticky_secret my_secret.$remote_addr;
}

The salt is added after the hashed value; to independently verify the hashing mechanism:

$ echo -n "<VALUE><SALT>" | md5sum

sticky_strict#

Syntax

sticky_strict on | off;

Default

sticky_strict off;

Context

upstream

When enabled, Angie returns a connection error to the client if the server identifier bound to the session matches no server in the group or that server is unavailable, instead of falling back to load balancing (the default behavior).

Built-in Variables#

The $upstream_sticky_status variable of the Stream Upstream module shows whether a connection carried session data and whether it reached the bound server. The stream_upstream_sticky module itself supports the following built-in variables:

$sticky_sessid (PRO)#

Used with remote_action in sticky; stores the initial session identifier taken from lookup.

$sticky_sid (PRO)#

Used with remote_action in sticky; stores the identifier of the server pre-selected by the load balancing method: the server's sid= value or its generated default (see server).