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
Load Balancing: session binding overrides the method.
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#
| |
Default | — |
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;
}
This mode uses predefined route identifiers, which may come from URLs, cookies, or request arguments. It's less flexible but good when such identifiers already exist.
The backend server may return a route ID known to both client and server. This value must match the sid.
Subsequent requests should carry the route ID, e.g., via a cookie or query argument.
The directive takes a list of strings that may include variables to extract the route ID. The first non-empty result is matched against sid.
In this example, Angie checks the route cookie first,
then the route query argument:
upstream backend {
zone backend 1m;
server backend1.example.com:8080 "sid=server 1";
server backend2.example.com:8080 "sid=server 2";
sticky route $cookie_route $arg_route;
}
This mode uses a dynamically generated key to assign a client to a backend. It's flexible and supports session storage in shared memory and various identifier sources.
A session is created from the backend server's response.
create and lookup define how to generate and locate sessions,
and both accept multiple variables.
The session ID is the first non-empty variable from create.
For example, it may come from a response cookie.
Sessions are stored in shared memory,
defined with zone name:size.
If unused for timeout duration (default: 1 hour), the session expires.
By default, Angie refreshes sessions on each use.
To disable this, use norefresh.
The session ID from a client request is extracted via lookup,
using the first non-empty variable listed.
If none is found, it's a new request.
Use header to create the session upon receiving response headers
rather than after full response processing.
Example: session created using examplecookie:
upstream backend {
zone backend 1m;
server backend1.example.com:8080;
server backend2.example.com:8080;
sticky learn
create=$upstream_cookie_examplecookie
lookup=$cookie_examplecookie
zone=client_sessions:1m;
}
Use remote_action and remote_result
to manage session IDs with an external session store.
The shared memory zone acts as a cache;
the external store is authoritative.
create is not compatible with remote_action.
Sessions expire after timeout (default: 1 hour),
regardless of remote_action.
By default, Angie refreshes session TTL on each use.
Use norefresh to disable that.
zone is optional with remote_action.
Without it, Angie keeps no local session cache
and queries the external store for every request
whose lookup variables yield a session ID;
the store's responses can still be cached with proxy_cache.
Basic flow:
Extract session ID from the first non-empty
lookupvariable. If none, fall back to standard load balancing.If
zoneis set and session exists, use it and stop.If no session or no zone, pick a server and make an HTTP subrequest to the
remote_actionendpoint with:session ID ($sticky_sessid);
server ID ($sticky_sid): the pre-selected server's
sid=value, or its generated default (see server).
Send these as HTTP headers (via proxy_set_header).
The remote store responds:
200/201/204: with
zoneset, confirms the selected server, and Angie caches the session in the zone. Withoutzone, the store must return the ID of the server bound to the session, which may differ from$sticky_sid; Angie extracts it withremote_resultand routes the request to that server.409 signals conflict (if
zoneis set) — session linked to another server. Useremote_resultto extract the corrected server ID.Any other status code, a network error, or a timeout — fall back to the originally selected server.
An empty server ID from
remote_result, or one that matches no available server — log an error and pick a server by the load balancing method; with sticky_strict enabled, return a 502 error instead.
remote_result uses upstream_http_* variables
to read headers from the remote store's response.
Example: session ID comes from $cookie_bar,
confirmed via $upstream_http_x_sticky_sid:
http {
upstream u1 {
server srv1;
server srv2;
sticky learn zone=sz:1m
lookup=$cookie_bar
remote_action=/remote_session
remote_result=$upstream_http_x_sticky_sid;
zone z 1m;
}
server {
listen localhost;
location / {
proxy_pass http://u1/;
}
location /remote_session {
internal;
proxy_set_header X-Sticky-Sessid $sticky_sessid;
proxy_set_header X-Sticky-Sid $sticky_sid;
proxy_set_header X-Sticky-Last $msec;
proxy_pass http://remote;
}
}
}
The following is a simplified configuration example.
The remote store returns the session ID in the X-Sid header
and so confirms or overrides Angie's choice:
http {
proxy_cache_path c1 keys_zone=s1:1m;
upstream tc_0 {
server 10.0.0.1 sid=web-server-01;
server 10.0.0.2 sid=web-server-02;
sticky learn
lookup=$arg_id
remote_action=@create_session
remote_result=$upstream_http_x_sid;
}
server {
listen 127.0.0.1:8080;
location / {
proxy_pass http://tc_0/;
}
# Request to the remote session store
location @create_session {
internal;
proxy_set_header X-Sticky-Sessid $sticky_sessid;
proxy_set_header X-Sticky-Sid $sticky_sid;
proxy_set_header X-Sticky-Last $msec;
proxy_pass http://session_backend;
proxy_connect_timeout 1s;
proxy_read_timeout 1s;
proxy_cache s1;
proxy_cache_valid 200 1d;
proxy_cache_key "$scheme$proxy_host$request_uri$sticky_sessid";
}
}
}
Example response:
HTTP/1.1 200 OK
...
X-Sid: web-server-01
X-Session-Backend: backend-pool-1
Resulting Angie variables:
$upstream_http_x_sid→web-server-01$upstream_http_x_session_backend→backend-pool-1
remote_result will use web-server-01
to select the matching sid.
The sticky directive respects upstream server states:
Servers marked
downor failing are excluded.Servers over
max_connslimit are skipped.drainservers may still be selected for new sessions instickymode 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#
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#
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
Used with Used with http_upstream_sticky module itself supports the following built-in
variables:$sticky_sessid (PRO)#remote_action in sticky;
stores the initial session ID taken from lookup.$sticky_sid (PRO)#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).