My favorites | Sign in
Project Home Downloads Wiki Source
Updated Sep 20, 2011 by


The nginx sticky module has to be compiled into nginx as every other nginx modules:

cd /path/to/nginx-sources
tar -xzf /path/to/nginx-sticky-module-$version.tar.gz
./configure ... --add-module=nginx-sticky-module-$version
make && make install


The sticky module has only one command: "sticky".



The "sticky" command can only be used in a upstream block:

upstream {


The "sticky" command can take several arguments to control its behaviour:

  sticky [name=route] [] [path=/] [expires=1h] [hash=index|md5|sha1] [no_fallback];

Configuration Description Parameters Default Value
name the name of the cookie used to track the persistant upstream srv can be any string "route"
domain the domain in which the cookie will be valid can be any string nothing. Let the browser handle this.
path the path in which the cookie will be valid can be any path nothing. Let the browser handle this.
expires the validity duration of the cookie must be a duration greater than one second nothing. It's a session cookie
hash the hash mechanism to encode upstream server. It cant' be used with hmac md5|sha1 md5
hmac The HMAC hash mechanism to encode upstream server. It's like the hash mechanism but it uses hmac_key to secure the hashing. It can't be used with hash. md5|sha1 none
hmac_key The key to use with hmac. It's mandatory when hmac is set. can be any string none
no_fallback When this flag is set, nginx will return a 502 (Bad Gateway orProxy Error) if a request comes with a cookie and the corresponding backend is unavailable. no arguments none


The nginx sticky module CAN'T be used with ip_hash in the same upstream block, behaviour is unknown !

Comment by, Nov 14, 2011

Great module, thanks!

Comment by, Apr 19, 2012

Is it possible to resolve following situation:

- there are several servers balanced with sticky module - we want to stop one server gradually, when old sessions routed to this server are sticked to it until expired but new sessions are routed to other servers

It there such option? Is it planned to support such feature in the future?

Comment by, May 20, 2012

How about this solution for gradually server switching:

  1. user session normally tracked by cookie, so check the cookie to identify old/new session
2.route new session to specific server, route old session to its sticked server


upstream app_pool {
sticky; server a; server b;
} upstream upgrade_pool {
sticky; server a; server b down;

server {
location xxxx {
set $poolname "app_pool"; if ($cookie_XXXSESSIONID = "") {
set $poolname "upgrade_pool";
} proxy_pass http://$poolname;
Comment by, Sep 21, 2012

Hi, Thank you for this module!

Is the sticky cookie changing to redirect (in a sticky fashion) to another upstream server if the original upstream server is down? If not, what's the best way to accomplish this?

Comment by, Oct 9, 2012

Great work. I built a Redhat Enterprise Linux 6.x RPM for x86 to fix a problem in one of my servers.




Comment by, Feb 15, 2013

I see this can't be used with ip_hash but is it possible to use it with least_conn so it will fall back to passing users to the server with the least load unless they already have a session on one of the backend servers?

Comment by, Sep 3, 2013

Great work! Thanx!

Comment by, Oct 21, 2013

Hi, thank you!

But I am getting an error when trying to add the module:

src/http/modules -I src/mail \

-o objs/addon/nginx-sticky-module-1.1/ngx_http_sticky_misc.o \ ../nginx-sticky-module-1.1/ngx_http_sticky_misc.c
In file included from ../nginx-sticky-module-1.1/ngx_http_sticky_misc.c:11:0: src/core/ngx_sha1.h:19:17: fatal error: sha.h: No such file or directory compilation terminated. make1?: [objs/addon/nginx-sticky-module-1.1/ngx_http_sticky_misc.o] Error 1 make1?: Leaving directory `/etc/nginx/nginx-1.4.1' make: build? Error 2

I have executed:

./configure --add-module=../nginx-sticky-module-1.1 --without-http_rewrite_module --without-http_gzip_module


make && make install

Could you please help me?


Comment by, Oct 21, 2013

Solved! Thanks People, i just install "yum -y install openssl-devel" before all.

Sign in to add a comment
Powered by Google Project Hosting