Merge pull request #266 from natsys/ab-sticky-doc

Add Tempesta sticky cookie documentation to README. (#233)

README.md

@@ -82,6 +82,35 @@ By default, the `tempesta_fw.conf` from this directory is used.
 
 See `tempesta_fw.conf` for the list of available options and their descriptions.
 
+
+### Sticky Cookie
+
+**Sticky cookie** is a special HTTP cookie that is generated by Tempesta. It allows for unique identification of each client, and it is part of Tempesta code module.
+
+When used, Tempesta sticky cookie is expected in HTTP request. Otherwise, Tempesta demands in HTTP response that sticky cookie is present in each HTTP request from a client. Default behaviour is that Tempesta sticky cookies are not used.
+
+The use and behaviour of Tempesta sticky cookies is controlled by a single configuration option that can have several parameters. The full form of the option and parameters is as follows:
+`sticky [name=<COOKIE_NAME>] [enforce];`
+
+`name` parameter specifies a custom Tempesta sticky cookie name `COOKIE_NAME` for use in HTTP requests. It is expected that it is a single word without whitespaces. When not specified explicitly, a default name is used.
+
+`enforce` parameter demands that Tempesta sticky cookie is present in each HTTP request. If it is not present in a request, a client receives HTTP 302 response from Tempesta that redirects the client to the same URI, and prompts that Tempesta sticky cookie is set in requests from the client.
+
+
+Below are examples of Tempesta sticky cookie option.
+
+* **sticky;**
+Enable Tempesta sticky cookie. Default cookie name is used. Tempesta expects that Tempesta sticky cookie is present in each HTTP request. If it is not present, then Tempesta includes `Set-Cookie` header field in HTTP response, which prompts that Tempesta sticky cookie with default name is set in requests from the client.
+
+* **sticky enforce;**
+Enable Tempesta sticky cookie. Default cookie name is used. Tempesta expects that Tempesta sticky cookie is present in each HTTP request. If it is not present, Tempesta sends HTTP 302 response that redirects the client to the same URI and includes `Set-Cookie` header field, which prompts that Tempesta sticky cookie with default name is set in requests from the client.
+
+* **sticky name=`__cookie__`;**
+Enable Tempesta sticky cookie. The name of the cookie is `__cookie__`. Tempesta expects that Tempesta sticky cookie is present in each HTTP request. If it is not present, then Tempesta includes `Set-Cookie` header field in HTTP response, which prompts that Tempesta sticky cookie with the name `__cookie__` is set in requests from the client.
+
+* **sticky name=`__cookie__` enforce;**
+Enable Tempesta sticky cookie. The name of the cookie is `__cookie__`. Tempesta expects that Tempesta sticky cookie is present in each HTTP request. If it is not present, Tempesta sends HTTP 302 response that redirects the client to the same URI and includes `Set-Cookie` header field, which prompts that Tempesta sticky cookie with the name `__cookie__` is set in requests from the client.
+
 ### Frang
 
 **Frang** is a separate Tempesta module for HTTP DoS and DDoS attacks prevention.