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. Angie binds each client address to the server of its first session and passes
later connections from that address to the same server. Default — upstream Configures sticky sessions between clients and upstream servers,
depending on the mode specified in the first parameter.
To gradually take servers with Warning The 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 In this mode, a dynamically generated key is used
to bind a client to a specific upstream server;
this mode is more flexible
as it assigns servers on the fly,
stores sessions in a shared memory zone,
and supports various ways of passing session identifiers. Here, a session is created
based on connection properties coming from the upstream server.
The The session identifier is the value of the first non-empty variable
specified with Sessions are stored in a shared memory zone;
its name and size are specified by the By default, Angie extends the session lifetime
by updating the last access timestamp each time it is used.
The Subsequent connections from clients wishing to use a session
must contain its identifier.
The The In the example, Angie creates and looks up sessions
using the $rdp_cookie variable: The The The The general operating principle of this mode is as follows:
if a session identifier is not found locally,
Angie sends a synchronous subrequest to a remote store
specified by the When a new connection arrives, Angie performs the following actions: First, the session identifier is extracted from the first non-empty variable
in the If If the session is not found locally or the session identifier from the the identifier of the pre-selected server
(in the configuration, this is the
$sticky_sid variable):
the server's The The remote store processes the request and returns an HTTP response: With With When receiving any other HTTP code from the store,
or on a network error or a timeout,
Angie uses the originally selected server. If The server identifier is extracted from the remote store response
via the Below is a simplified configuration example.
The remote store returns the server identifier in the Here, with the following response from the remote store: Two variables become available: Since the The Servers marked as Servers that have reached the maximum number of connections
(when using Servers with the If a previously unavailable server recovers,
The behavior of Shared memory zones
specified in the Adds string as salt to the MD5 hash function
for the sticky directive in The salt is added after the hashed value;
to independently verify the hashing mechanism: 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). 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
Used with Used with 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;
}
Directives#
sticky#
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)sticky out of rotation,
you can use the drain option in the server block.sticky directive must appear after all load balancing method directives,
otherwise it won't work.$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;
}
}
create and lookup parameters list variables
that specify how new sessions are created and existing ones are found.
Both parameters can be used multiple times.create;
for example, this could be
the upstream server name.zone parameter.
If a session has not been accessed within the time
specified by timeout, it is deleted.
The default value is 1 hour.norefresh parameter changes this behavior:
the session expires strictly by timeout, even if it is being used.lookup parameter searches for the session identifier in the connection
using the specified list of variables,
stopping at the first non-empty one.
If nothing is found, the request is considered new.
The value of the found identifier
is matched against sessions in shared memory.
If server selection fails
or the selected server cannot handle the connection,
another server will be selected
according to the configured load balancing method.connect parameter allows creating a session
immediately after establishing a connection with the upstream server.
Without it, the session is created only after connection processing is complete.
(In the case of UDP connections, sessions are created immediately after server selection.)stream {
upstream backend {
zone backend 1m;
server 127.0.0.1:3390;
server 127.0.0.1:3391;
sticky learn lookup=$rdp_cookie create=$rdp_cookie zone=sessions:1m;
}
server {
listen 127.0.0.1:3389;
rdp_preread on;
proxy_pass backend;
}
}
remote_action and remote_result parameters
allow dynamically assigning and managing session identifiers
using a remote session store (PRO).zone parameter is optional in this mode.
With it, the shared memory zone acts as a local session cache,
and timeout and norefresh work
as in learn mode with create;
the remote store remains authoritative.
Without it, Angie keeps no local session cache
and queries the remote store for every connection
whose lookup variables yield a session identifier.remote_action parameter must point to a location
in the client context.
The remote_uri parameter specifies the URI of the client HTTP request
to the specified location.
By default, it is /.
The remote_uri value can contain variables.remote_action parameter.lookup list.
If all variables are empty,
the normal load balancing algorithm is used without sticky sessions.zone is set,
Angie looks up the session in the shared memory zone.
If the session is found, Angie uses its server and stops.zone is not set,
Angie selects a server by the configured load balancing method.
Then it sends a synchronous HTTP subrequest to the remote store
specified by the remote_action parameter, which should contain
in a format understood by the store:lookup parameter
(in the configuration, this is the
$sticky_sessid variable);sid= value
or its generated default (see server).$sticky_sessid and $sticky_sid variables are automatically
exported to the HTTP context with the stream_ prefix:
$stream_sticky_sessid, $stream_sticky_sid.
This allows using them directly in HTTP directives,
for example via HTTP headers using proxy_set_header.zone set,
a response with code 200, 201, or 204 confirms the selected server,
and the session is saved in the shared memory zone.
Without zone, the store must return in such a response
the identifier of the server bound to the session,
which may differ from $sticky_sid;
Angie extracts it with remote_result
and routes the connection to that server.zone set, a response with code 409 signals a conflict:
the session identifier already exists but is bound to another server.
The remote store must return the correct server identifier
in the same response; it can be extracted via remote_result.remote_result yields an empty server identifier
or one that matches no available server,
Angie logs an error and selects a server by the load balancing method;
with sticky_strict enabled,
the client gets a connection error instead.remote_result parameter:
it can specify variables
with the upstream_http_ prefix,
which are created automatically by Angie to access
HTTP response headers from the remote store,
or $sent_body to use the response body.
For example, the X-Sid: server1 header in such a response
becomes accessible in the $upstream_http_x_sid variable
with the value server1.X-Sticky-Sid header
and thus confirms or overrides Angie's selection:http {
client {
location @sticky_client1 {
# use variables from the stream upstream;
# it adds these variables to the HTTP context with the stream_* prefix
proxy_set_header X-Sticky-Sessid $stream_sticky_sessid;
proxy_set_header X-Sticky-Sid $stream_sticky_sid;
proxy_set_header X-Sticky-Last $msec;
proxy_pass http://127.0.0.1:8080;
proxy_cache remote;
proxy_cache_valid 200 1d;
proxy_cache_key $scheme$proxy_host$request_uri$stream_sticky_sessid;
}
}
}
stream {
upstream u {
zone u 1m;
server 127.0.0.1:8081 sid=backend-01;
server 127.0.0.1:8082 sid=backend-02;
sticky learn lookup=$remote_addr # stream variable
remote_action=@sticky_client1 # location from client block
remote_result=$upstream_http_x_sticky_sid # HTTP variable
remote_uri=/foo; # default is /
}
server {
listen 127.0.0.1:8080;
proxy_pass u;
}
}
HTTP/1.1 200 OK
...
X-Sticky-Sid: backend-01
X-Session-Info: active
$upstream_http_x_sticky_sid,
with the value backend-01;$upstream_http_x_session_info,
with the value active.$upstream_http_x_sticky_sid variable
is specified in the remote_result parameter,
its value will be used
to select the server with sid=backend-01.sticky directive takes into account the state of servers in upstream:down or temporarily unavailable due to failures
are excluded from selection.max_conns) are temporarily skipped.drain option
can be selected for creating new sessions in sticky mode
when identifiers match.sticky automatically resumes using it.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.zone parameter of the sticky directive
cannot be shared between different upstream groups;
each group must use its own zone.sticky_secret#
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;
}
$ echo -n "<VALUE><SALT>" | md5sum
sticky_strict#
Built-in Variables#
stream_upstream_sticky module itself supports the following built-in
variables:$sticky_sessid (PRO)#remote_action in sticky;
stores the initial session identifier taken from lookup.$sticky_sid (PRO)#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).