README.md
1# Nginx Sticky Module
2
3
4modified and extended version; see Changelog.txt
5
6# Description
7
8A nginx module to add a sticky cookie to be always forwarded to the same
9upstream server.
10
11When dealing with several backend servers, it's sometimes useful that one
12client (browser) is always served by the same backend server
13(for session persistance for example).
14
15Using a persistance by IP (with the ip_hash upstream module) is maybe not
16a good idea because there could be situations where a lot of different
17browsers are coming with the same IP address (behind proxies)and the load
18balancing system won't be fair.
19
20Using a cookie to track the upstream server makes each browser unique.
21
22When the sticky module can't apply, it switchs back to the classic Round Robin
23Upstream or returns a "Bad Gateway" (depending on the no_fallback flag).
24
25Sticky module can't apply when cookies are not supported by the browser
26
27> Sticky module is based on a "best effort" algorithm. Its aim is not to handle
28> security somehow. It's been made to ensure that normal users are always
29> redirected to the same backend server: that's all!
30
31# Installation
32
33You'll need to re-compile Nginx from source to include this module.
34Modify your compile of Nginx by adding the following directive
35(modified to suit your path of course):
36
37 ./configure ... --add-module=/absolute/path/to/nginx-sticky-module-ng
38 make
39 make install
40
41# Usage
42
43 upstream {
44 sticky;
45 server 127.0.0.1:9000;
46 server 127.0.0.1:9001;
47 server 127.0.0.1:9002;
48 }
49
50 sticky [hash=index|md5|sha1] [no_fallback]
51 [name=route] [domain=.foo.bar] [path=/] [expires=1h] [secure] [httponly];
52 or
53 sticky [hmac=md5|sha1 hmac_key=<foobar_key>] [no_fallback]
54 [name=route] [domain=.foo.bar] [path=/] [expires=1h] [secure] [httponly];
55 or
56 sticky [text=raw] [no_fallback]
57 [name=route] [domain=.foo.bar] [path=/] [expires=1h] [secure] [httponly];
58
59Server selection algorithm:
60- hash: the hash mechanism to encode upstream server. It can't be used with hmac or text.
61 default: md5
62
63 - md5|sha1: well known hash
64 - index: it's not hashed, an in-memory index is used instead, it's quicker and the overhead is shorter
65 Warning: the matching against upstream servers list
66 is inconsistent. So, at reload, if upstreams servers
67 has changed, index values are not guaranted to
68 correspond to the same server as before!
69 USE IT WITH CAUTION and only if you need to!
70
71- hmac: the HMAC hash mechanism to encode upstream server
72 It's like the hash mechanism but it uses hmac_key
73 to secure the hashing. It can't be used with hash or text.
74 md5|sha1: well known hash
75
76- hmac_key: the key to use with hmac. It's mandatory when hmac is set
77
78- no_fallback: when this flag is set, nginx will return a 502 (Bad Gateway or
79 Proxy Error) if a request comes with a cookie and the
80 corresponding backend is unavailable. You can set it to the
81 upstream block, or set "sticky_no_fallback" in a server or
82 location block.
83
84Cookie settings:
85- name: the name of the cookie used to track the persistant upstream srv;
86 default: route
87
88- domain: the domain in which the cookie will be valid
89 default: none. Let the browser handle this.
90
91- path: the path in which the cookie will be valid
92 default: /
93
94- expires: the validity duration of the cookie
95 default: nothing. It's a session cookie.
96 restriction: must be a duration greater than one second
97
98- secure enable secure cookies; transferred only via https
99- httponly enable cookies not to be leaked via js
100
101
102# Detail Mechanism
103
104- see docs/sticky.{vsd,pdf}
105
106# Issues and Warnings:
107
108- when using different upstream-configs with stickyness that use the same domain but
109 refer to different location - configs it might be wise to set a different path / route -
110 option on each of this upstream-configs like described here:
111 https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng/issue/7/leaving-cookie-path-empty-in-module
112
113- sticky module does not work with the "backup" option of the "server" configuration item.
114- sticky module might work with the nginx_http_upstream_check_module (up from version 1.2.3)
115
116
117
118# Contributing
119
120- please send/suggest patches as diffs
121- tickets and issues here: https://bitbucket.org/nginx-goodies/nginx-sticky-session-ng
122
123
124# Downloads
125
126- tarballs are available via tags from the repo: https://bitbucket.org/nginx-goodies/nginx-sticky-module-ng/downloads
127
128
129# TODO
130
131see Todo.md
132
133# Authors & Credits
134
135- Jerome Loyet, initial module
136- Markus Linnala, httponly/secure-cookies-patch
137- Peter Bowey, Nginx 1.5.8 API-Change
138- Michael Chernyak for Max-Age-Patch
139- anybody who suggested a patch, created an issue on bitbucket or helped improving this module
140
141
142
143# Copyright & License
144
145 This module is licenced under the BSD license.
146
147 Copyright (C) 2010 Jerome Loyet (jerome at loyet dot net)
148 Copyright (C) 2014 Markus Manzke (goodman at nginx-goodies dot com)
149
150
151 Redistribution and use in source and binary forms, with or without
152 modification, are permitted provided that the following conditions
153 are met:
154
155 1. Redistributions of source code must retain the above copyright
156 notice, this list of conditions and the following disclaimer.
157
158 2. Redistributions in binary form must reproduce the above copyright
159 notice, this list of conditions and the following disclaimer in the
160 documentation and/or other materials provided with the distribution.
161
162 THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
163 ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
164 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
165 ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
166 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
167 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
168 OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
169 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
170 LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
171 OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
172 SUCH DAMAGE.
173
174