refinitiv / nginx-sticky-module-ng

Fork of https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng community

Nginx Sticky Module

modified and extended version; see Changelog.txt

Description

A nginx module to add a sticky cookie to be always forwarded to the same upstream server.

When dealing with several backend servers, it's sometimes useful that one client (browser) is always served by the same backend server (for session persistance for example).

Using a persistance by IP (with the ip_hash upstream module) is maybe not a good idea because there could be situations where a lot of different browsers are coming with the same IP address (behind proxies)and the load balancing system won't be fair.

Using a cookie to track the upstream server makes each browser unique.

When the sticky module can't apply, it switchs back to the classic Round Robin Upstream or returns a "Bad Gateway" (depending on the no_fallback flag).

Sticky module can't apply when cookies are not supported by the browser

Sticky module is based on a "best effort" algorithm. Its aim is not to handle security somehow. It's been made to ensure that normal users are always redirected to the same backend server: that's all!

Installation

You'll need to re-compile Nginx from source to include this module. Modify your compile of Nginx by adding the following directive (modified to suit your path of course):

./configure ... --add-module=/absolute/path/to/nginx-sticky-module-ng
make
make install

Usage

upstream {
  sticky;
  server 127.0.0.1:9000;
  server 127.0.0.1:9001;
  server 127.0.0.1:9002;
}

  sticky [hash=index|md5|sha1] [no_fallback] [transfer] [delimiter=.]
       [name=route] [domain=.foo.bar] [path=/] [expires=1h] [secure] [httponly];
   or
  sticky [hmac=md5|sha1 hmac_key=<foobar_key>] [no_fallback] [transfer] [delimiter=.]
       [name=route] [domain=.foo.bar] [path=/] [expires=1h] [secure] [httponly];
   or
  sticky [text=raw] [no_fallback] [transfer] [delimiter=.]
       [name=route] [domain=.foo.bar] [path=/] [expires=1h] [secure] [httponly];

Server selection algorithm:

• hash: the hash mechanism to encode upstream server. It can't be used with hmac or text.
  default: md5

  • md5|sha1: well known hash
  • index: it's not hashed, an in-memory index is used instead, it's quicker and the overhead is shorter
    Warning: the matching against upstream servers list is inconsistent. So, at reload, if upstreams servers has changed, index values are not guaranted to correspond to the same server as before!
    USE IT WITH CAUTION and only if you need to!

• 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 or text.
  md5|sha1: well known hash

• hmac_key: the key to use with hmac. It's mandatory when hmac is set

• no_fallback: when this flag is set, nginx will return a 502 (Bad Gateway or Proxy Error) if a request comes with a cookie and the corresponding backend is unavailable. You can set it to the upstream block, or set sticky_no_fallback in a server or location block.

• transfer: when this flag is set, nginx adds a cookie from the backend to the sticky cookie
  default: space

  Example for remove peer part from cookie before sand it to backend:

    server {
      # ...
      set $jsessionid $cookie_JSESSIONID;
      if ($cookie_JSESSIONID ~ "^[^\s]+\s(.*)$") {
        set $jsessionid $1;
      }
      location / {
        proxy_set_header Cookie "JSESSIONID=$jsessionid";
        proxy_pass http://backend;
      }
    }
  

• delimiter: delimiter to add a cookie from the backend

Cookie settings:

• name: the name of the cookie used to track the persistant upstream srv;
  default: route

• domain: the domain in which the cookie will be valid
  default: none. Let the browser handle this.

• path: the path in which the cookie will be valid
  default: /

• expires: the validity duration of the cookie
  default: nothing. It's a session cookie.
  restriction: must be a duration greater than one second

• secure: enable secure cookies; transferred only via https

• httponly: enable cookies not to be leaked via js

• hide_cookie: does not send cookies to the client side
  This is to use cookies exclusively for routing only.
  You can set it to the upstream block, or set sticky_hide_cookie in a server or location block.

Detail Mechanism

• see docs/sticky.{vsd,pdf}

Issues and Warnings:

• when using different upstream-configs with stickyness that use the same domain but refer to different location - configs it might be wise to set a different path / route -
  option on each of this upstream-configs like described here: https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng/issue/7/leaving-cookie-path-empty-in-module

• sticky module does not work with the "backup" option of the "server" configuration item.

• sticky module might work with the nginx_http_upstream_check_module (up from version 1.2.3)

• sticky module does not modify cookie from a client to the backend if "transfer" flag is set.

Contributing

• please send/suggest patches as diffs
• tickets and issues here: https://bitbucket.org/nginx-goodies/nginx-sticky-session-ng

Downloads

• tarballs are available via tags from the repo: https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng/downloads

TODO

see Todo.md

Authors & Credits

• Jerome Loyet, initial module
• Markus Linnala, httponly/secure-cookies-patch
• Peter Bowey, Nginx 1.5.8 API-Change
• Michael Chernyak for Max-Age-Patch
• anybody who suggested a patch, created an issue on bitbucket or helped improving this module

Copyright & License

This module is licenced under the BSD license.

Copyright (C) 2010 Jerome Loyet (jerome at loyet dot net)
Copyright (C) 2014 Markus Manzke (goodman at nginx-goodies dot com)


Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:

1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

nginx-sticky-module-ng's Issues

Build error with 1.23.0 version

ngx_http_sticky_module.c:218:54: error: ‘ngx_http_headers_in_t’ has no member named ‘cookies’
  if (ngx_http_parse_multi_header_lines(&r->headers_in.cookies, &iphp->sticky_conf->cookie_name, &route) != NGX_DECLINED) {
                                                      ^
ngx_http_sticky_module.c:218:2: error: passing argument 2 of ‘ngx_http_parse_multi_header_lines’ from incompatible pointer type [-Werror]
  if (ngx_http_parse_multi_header_lines(&r->headers_in.cookies, &iphp->sticky_conf->cookie_name, &route) != NGX_DECLINED) {
  ^
In file included from ngx_http_sticky_module.c:9:0:
src/http/ngx_http.h:106:18: note: expected ‘struct ngx_table_elt_t *’ but argument is of type ‘struct ngx_str_t *’
 ngx_table_elt_t *ngx_http_parse_multi_header_lines(ngx_http_request_t *r,
                  ^
ngx_http_sticky_module.c:218:2: error: too few arguments to function ‘ngx_http_parse_multi_header_lines’
  if (ngx_http_parse_multi_header_lines(&r->headers_in.cookies, &iphp->sticky_conf->cookie_name, &route) != NGX_DECLINED) {
  ^
In file included from ngx_http_sticky_module.c:9:0:
src/http/ngx_http.h:106:18: note: declared here
 ngx_table_elt_t *ngx_http_parse_multi_header_lines(ngx_http_request_t *r,
                  ^

Build error with 1.23.0

ngx_http_sticky_module.c:218:54: error: ‘ngx_http_headers_in_t’ has no member named ‘cookies’
  if (ngx_http_parse_multi_header_lines(&r->headers_in.cookies, &iphp->sticky_conf->cookie_name, &route) != NGX_DECLINED) {
                                                      ^
ngx_http_sticky_module.c:218:2: error: passing argument 2 of ‘ngx_http_parse_multi_header_lines’ from incompatible pointer type [-Werror]
  if (ngx_http_parse_multi_header_lines(&r->headers_in.cookies, &iphp->sticky_conf->cookie_name, &route) != NGX_DECLINED) {
  ^
In file included from ngx_http_sticky_module.c:9:0:
src/http/ngx_http.h:106:18: note: expected ‘struct ngx_table_elt_t *’ but argument is of type ‘struct ngx_str_t *’
 ngx_table_elt_t *ngx_http_parse_multi_header_lines(ngx_http_request_t *r,
                  ^
ngx_http_sticky_module.c:218:2: error: too few arguments to function ‘ngx_http_parse_multi_header_lines’
  if (ngx_http_parse_multi_header_lines(&r->headers_in.cookies, &iphp->sticky_conf->cookie_name, &route) != NGX_DECLINED) {
  ^
In file included from ngx_http_sticky_module.c:9:0:
src/http/ngx_http.h:106:18: note: declared here
 ngx_table_elt_t *ngx_http_parse_multi_header_lines(ngx_http_request_t *r,
                  ^

Error: comparison between signed and unsigned integer expressions

My steps are:

# ./configure --prefix=/usr/local/nginx --add-module=/root/app/nginx-sticky-module-ng-master/
# make
# make install

At last step, system raise a error:

/root/app/nginx-sticky-module-ng-master//ngx_http_sticky_module.c: In function ‘ngx_conf_set_noargs_slot’:
/root/app/nginx-sticky-module-ng-master//ngx_http_sticky_module.c:753:13: error: comparison between signed and unsigned integer expressions [-Werror=sign-compare]

Please help to check. Thank

Need new release version

I noticed that the last release was released in 2015. Getting the latest version from commit doesn't seem formal. Can a new release version be released based on the current code? If you're busy, can you give me permission to do it?

why you copy the project from other people?

origin source :
GitHub - Refinitiv/nginx-sticky-module-ng: Fork of https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng community

pls, tell me why ?

Feature Request: least_conn

It would be really good if an option for supporting least_conn as the secondary upstream handler could be implemented.

this module is not compatible with nginx v1-24-0

Hi,
I want to make nginx 1-24-0 using nginx-sticky-module-ng. but it has some errors:
1- error: ‘ngx_http_headers_in_t’ has no member named ‘cookies’; did you mean ‘cookie’?
243 | if (ngx_http_parse_multi_header_lines(&r->headers_in.cookies, &iphp->sticky_conf->cookie_name, &route) != NGX_DECLINED) {
2- error: passing argument 2 of ‘ngx_http_parse_multi_header_lines’ from incompatible pointer type [-Werror=incompatible-pointer-types]
243 | if (ngx_http_parse_multi_header_lines(&r->headers_in.cookies, &iphp->sticky_conf->cookie_name, &route) != NGX_DECLINED) {
3- error: too few arguments to function ‘ngx_http_parse_multi_header_lines’
243 | if (ngx_http_parse_multi_header_lines(&r->headers_in.cookies, &iphp->sticky_conf->cookie_name, &route) != NGX_DECLINED) {
4- error: ‘ngx_http_upstream_headers_in_t’ has no member named ‘cookies’
475 | if (ngx_http_parse_set_cookie_lines(&r->upstream->headers_in.cookies, &ctx->sticky_conf->cookie_name, &transfer_cookie) == NGX_DECLINED)
5- error: passing argument 2 of ‘ngx_http_parse_set_cookie_lines’ from incompatible pointer type [-Werror=incompatible-pointer-types]
475 | if (ngx_http_parse_set_cookie_lines(&r->upstream->headers_in.cookies, &ctx->sticky_conf->cookie_name, &transfer_cookie) == NGX_DECLINED)
6- error: too few arguments to function ‘ngx_http_parse_set_cookie_lines’
475 | if (ngx_http_parse_set_cookie_lines(&r->upstream->headers_in.cookies, &ctx->sticky_conf->cookie_name, &transfer_cookie) == NGX_DECLINED)

in https://trac.nginx.org/nginx/ticket/2358 an error like the errors that are mentioned here is investigated. ( This includes the explicitly mentioned change to use linked lists instead of arrays, as well as various renames to match the new approach to headers. For the details about the particular change causing the build failure, see ef6a3a99a81a. The 3rd party modules you are using need to be adjust to work with nginx 1.23.0.)

I need to have this module with nginx. if it is possible, please resolve it. thank you.

SHA_CBLOCK redefined in ngx_http_sticky_misc.c:23

When building, I encounter the error ngx_http_sticky_misc.c:23: error: "SHA_CBLOCK" redefined [-Werror]. This seems to be happening because of the redefinition in the line referenced:

nginx-sticky-module-ng/ngx_http_sticky_misc.c

Line 27 in 6fe17af

#define SHA_CBLOCK 64

I have a problem during the build on Windows. How should I fix it?

The error message is as follows:

C:/Users/supak/Downloads/nginx/objs/lib/nginx-goodies-nginx-sticky-module-ng/ngx_http_sticky_module.c(209): error C2220: warning treated as error - no 'object' file generated
C:/Users/supak/Downloads/nginx/objs/lib/nginx-goodies-nginx-sticky-module-ng/ngx_http_sticky_module.c(209): warning C4013: 'ngx_log_debug' undefined; assuming extern returning int
C:/Users/supak/Downloads/nginx/objs/lib/nginx-goodies-nginx-sticky-module-ng/ngx_http_sticky_module.c(418): warning C4152: nonstandard extension, function/data pointer conversion in expression
NMAKE : fatal error U1077: '"C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\BIN\amd64\cl.EXE"' : return code '0x2'
Stop.

nginx-1.23.3

I tried different builds like 1.22.0 - 1.23.3 showing the same result.