{"id":19601261,"url":"https://github.com/refinitiv/nginx-sticky-module-ng","last_synced_at":"2025-06-23T19:38:35.080Z","repository":{"id":40775606,"uuid":"94258996","full_name":"Refinitiv/nginx-sticky-module-ng","owner":"Refinitiv","description":"Fork of https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng community","archived":false,"fork":false,"pushed_at":"2023-12-16T17:43:56.000Z","size":147,"stargazers_count":83,"open_issues_count":9,"forks_count":68,"subscribers_count":102,"default_branch":"master","last_synced_at":"2025-04-05T01:32:25.631Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Refinitiv.png","metadata":{"files":{"readme":"README.md","changelog":"Changelog.txt","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-06-13T21:19:58.000Z","updated_at":"2025-03-12T15:44:05.000Z","dependencies_parsed_at":"2023-01-21T06:45:17.791Z","dependency_job_id":null,"html_url":"https://github.com/Refinitiv/nginx-sticky-module-ng","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Refinitiv%2Fnginx-sticky-module-ng","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Refinitiv%2Fnginx-sticky-module-ng/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Refinitiv%2Fnginx-sticky-module-ng/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Refinitiv%2Fnginx-sticky-module-ng/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Refinitiv","download_url":"https://codeload.github.com/Refinitiv/nginx-sticky-module-ng/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251171753,"owners_count":21547155,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-11T09:17:45.064Z","updated_at":"2025-04-27T16:32:33.365Z","avatar_url":"https://github.com/Refinitiv.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nginx Sticky Module \n\n\nmodified and extended version; see Changelog.txt \n\n# Description\n\nA nginx module to add a sticky cookie to be always forwarded to the same\nupstream server.\n\nWhen dealing with several backend servers, it's sometimes useful that one\nclient (browser) is always served by the same backend server\n(for session persistance for example).\n\nUsing a persistance by IP (with the ip_hash upstream module) is maybe not\na good idea because there could be situations where a lot of different\nbrowsers are coming with the same IP address (behind proxies)and the load\nbalancing system won't be fair.\n\nUsing a cookie to track the upstream server makes each browser unique.\n\nWhen the sticky module can't apply, it switchs back to the classic Round Robin\nUpstream or returns a \"Bad Gateway\" (depending on the no_fallback flag).\n\nSticky module can't apply when cookies are not supported by the browser\n\n\u003e Sticky module is based on a \"best effort\" algorithm. Its aim is not to handle\n\u003e security somehow. It's been made to ensure that normal users are always\n\u003e redirected to the same  backend server: that's all!\n\n# Installation\n\nYou'll need to re-compile Nginx from source to include this module.\nModify your compile of Nginx by adding the following directive\n(modified to suit your path of course):\n\n    ./configure ... --add-module=/absolute/path/to/nginx-sticky-module-ng\n    make\n    make install\n\n# Usage\n\n    upstream {\n      sticky;\n      server 127.0.0.1:9000;\n      server 127.0.0.1:9001;\n      server 127.0.0.1:9002;\n    }\n\n\t  sticky [hash=index|md5|sha1] [no_fallback] [transfer] [delimiter=.]\n           [name=route] [domain=.foo.bar] [path=/] [expires=1h] [secure] [httponly];\n       or\n\t  sticky [hmac=md5|sha1 hmac_key=\u003cfoobar_key\u003e] [no_fallback] [transfer] [delimiter=.]\n           [name=route] [domain=.foo.bar] [path=/] [expires=1h] [secure] [httponly];\n       or\n\t  sticky [text=raw] [no_fallback] [transfer] [delimiter=.]\n           [name=route] [domain=.foo.bar] [path=/] [expires=1h] [secure] [httponly];\n\nServer selection algorithm:\n- `hash`: the hash mechanism to encode upstream server. It can't be used with hmac or text.  \n  default: `md5`\n\n  - `md5`|`sha1`: well known hash\n  - `index`: it's not hashed, an in-memory index is used instead, it's quicker and the overhead is shorter  \n    Warning: the matching against upstream servers list\n    is inconsistent. So, at reload, if upstreams servers\n    has changed, index values are not guaranted to\n    correspond to the same server as before!  \n    USE IT WITH CAUTION and only if you need to!\n\n- `hmac`: the HMAC hash mechanism to encode upstream server  \n  It's like the hash mechanism but it uses hmac_key\n  to secure the hashing. It can't be used with hash or text.  \n  `md5`|`sha1`: well known hash\n\n- `hmac_key`: the key to use with hmac. It's mandatory when hmac is set\n\n- `no_fallback`: when this flag is set, nginx will return a 502 (Bad Gateway or\n  Proxy Error) if a request comes with a cookie and the\n  corresponding backend is unavailable. You can set it to the\n  upstream block, or set `sticky_no_fallback` in a server or\n  location block.\n\n- `transfer`: when this flag is set, nginx adds a cookie from the backend to the sticky cookie  \n  default: space\n\n  Example for remove peer part from cookie before sand it to backend:\n  ```\n    server {\n      # ...\n      set $jsessionid $cookie_JSESSIONID;\n      if ($cookie_JSESSIONID ~ \"^[^\\s]+\\s(.*)$\") {\n        set $jsessionid $1;\n      }\n      location / {\n        proxy_set_header Cookie \"JSESSIONID=$jsessionid\";\n        proxy_pass http://backend;\n      }\n    }\n  ```\n\n- delimiter: delimiter to add a cookie from the backend  \n\nCookie settings:\n- `name`: the name of the cookie used to track the persistant upstream srv;  \n  default: `route`\n\n- `domain`: the domain in which the cookie will be valid  \n  default: none. Let the browser handle this.\n\n- `path`: the path in which the cookie will be valid  \n  default: `/`\n\n- `expires`: the validity duration of the cookie  \n  default: nothing. It's a session cookie.  \n  restriction: must be a duration greater than one second\n\n- `secure`: enable secure cookies; transferred only via https\n- `httponly`: enable cookies not to be leaked via js\n- `hide_cookie`: does not send cookies to the client side  \n  This is to use cookies exclusively for routing only.  \n  You can set it to the upstream block, or set `sticky_hide_cookie` in a server or\n  location block.\n\n# Detail Mechanism\n\n- see docs/sticky.{vsd,pdf}\t\n\n# Issues and Warnings:\n\n- when using different upstream-configs with stickyness that use the same domain but \n  refer to different location - configs it might be wise to set a different path / route -  \n  option on each of this upstream-configs like described here:\n  https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng/issue/7/leaving-cookie-path-empty-in-module\n\n- sticky module does not work with the \"backup\" option of the \"server\" configuration item.\n- sticky module might work with the nginx_http_upstream_check_module (up from version 1.2.3)\n- sticky module does not modify cookie from a client to the backend if \"transfer\" flag is set.\n\n\n# Contributing\n\n- please send/suggest patches as diffs\n- tickets and issues here: https://bitbucket.org/nginx-goodies/nginx-sticky-session-ng\n\n\n# Downloads\n\n- tarballs are available via tags from the repo: https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng/downloads\n\n\n# TODO\n\nsee Todo.md\n  \n# Authors \u0026 Credits\n\n- Jerome Loyet, initial module\n- Markus Linnala, httponly/secure-cookies-patch\n- Peter Bowey, Nginx 1.5.8 API-Change \n- Michael Chernyak for Max-Age-Patch \n- anybody who suggested a patch, created an issue on bitbucket or helped improving this module \n\n\n\n# Copyright \u0026 License\n\n    This module is licenced under the BSD license.\n  \n    Copyright (C) 2010 Jerome Loyet (jerome at loyet dot net)\n    Copyright (C) 2014 Markus Manzke (goodman at nginx-goodies dot com)\n\n  \n    Redistribution and use in source and binary forms, with or without\n    modification, are permitted provided that the following conditions\n    are met:\n  \n    1. Redistributions of source code must retain the above copyright\n    notice, this list of conditions and the following disclaimer.\n  \n    2. Redistributions in binary form must reproduce the above copyright\n    notice, this list of conditions and the following disclaimer in the\n    documentation and/or other materials provided with the distribution.\n  \n    THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND\n    ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\n    IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\n    ARE DISCLAIMED.  IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE\n    FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL\n    DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS\n    OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)\n    HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT\n    LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY\n    OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF\n    SUCH DAMAGE.\n  \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefinitiv%2Fnginx-sticky-module-ng","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frefinitiv%2Fnginx-sticky-module-ng","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frefinitiv%2Fnginx-sticky-module-ng/lists"}