Upstream Sticky#

Binds client sessions to servers in groups of the HTTP Upstream module, so that requests 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; it can be disabled with the build option --without-http_upstream_sticky_module.

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

Related guides

Configuration Example#

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

    sticky cookie srv_id max-age=3600;
}

Directives#

sticky#

Syntax

sticky cookie name [attr=value]...;

sticky route value...;

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

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

Default

—

Context

upstream

Configures session affinity to bind client sessions to proxied servers in the mode specified by the first parameter; to drain servers that have the sticky directive configured, you can use the drain option in the server block.

Warning

The sticky directive must be used after all directives that specify a particular load balancing method, otherwise it will not work. If it is used alongside the bind_conn (PRO) directive, then bind_conn must come after sticky.

This mode uses cookies to manage sessions. It's suitable when cookies are already used for session tracking.

The first client request, before any stickiness applies, is sent to a backend server according to the configured balancing method. Angie then sets a cookie identifying the chosen server.

The cookie name (name) is defined by the sticky directive, and its value corresponds to the sid from the server directive. This value is further hashed if sticky_secret is set.

Subsequent requests with this cookie are routed to the server specified by its sid. If the server is unavailable or can't process the request, another one is chosen via the configured balancing method.

You can assign cookie attributes in the directive; by default, only path=/ is set. Attribute values can contain variables. To remove an attribute, set it to an empty value: attr=. For example, sticky cookie path= omits the path attribute.

This example sets a cookie srv_id for 1 hour, using a domain from a variable:

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

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

The sticky directive respects upstream server states:

  • Servers marked down or failing are excluded.

  • Servers over max_conns limit are skipped.

  • drain servers may still be selected for new sessions in sticky mode when identifiers match.

  • Recovered servers are reused automatically.

You can further adjust behavior using sticky_secret and sticky_strict. If stickiness fails and sticky_strict is off, fallback balancing is used; if on, the request is rejected.

Each zone used in sticky must be exclusive to a single upstream. Zones cannot be shared across multiple upstream blocks.

sticky_secret#

Syntax

sticky_secret string;

Default

—

Context

upstream

Adds the string as the salt value to the MD5 hashing function for the sticky directive in cookie and route modes. The string may contain variables, for example, $remote_addr:

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

    sticky cookie cookie_name;
    sticky_secret my_secret.$remote_addr;
}

The salt is appended to the value being hashed; to verify the hashing mechanism independently:

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

sticky_strict#

Syntax

sticky_strict on | off;

Default

sticky_strict off;

Context

upstream

When enabled, Angie returns an HTTP 502 error to the client if the server ID 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 HTTP Upstream module shows whether a request carried session data and whether it reached the bound server. The http_upstream_sticky module itself supports the following built-in variables:

$sticky_sessid (PRO)#

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

$sticky_sid (PRO)#

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