HttpSplitClientsModule

WARNING: this article is obsoleted. Please refer to http://nginx.org/en/docs/ for the latest official documentation.

= Synopsis =

ngx_http_split_clients_module is used to split clients based on some conditions(e.g ip addresses, headers, cookies, etc).

= Examples =

Basic configuration:
http { split_clients "${remote_addr}AAA" $variant { 40.5% ".one"; 59.5% ".two"; }

server { location / { index index${variant}.html; [...]   }

On the sample configuration above, the input for calculating the percentage is the variable plus string ("${remote_addr}AAA"). The value of this string is hashed using MurmurHash2 (which will generate a 32bit integer). In the example given:
 * Hash values from 0 to 1739461754 (40.5%) will set the $variant variable with the value ".one" and will try to load the file "index.one.html";
 * Hash values from 1739461755 to 4294967295 (59.5%) will set the $variant variable with the value ".two" and will try to load the file "index.two.html";

Sending a query string variable to 51% of clients (to PHP scripts)
http { split_clients "${remote_addr}" $additionalQsVariable { 51% "coolVariable=1"; 49% "";	}

server { location ~ \.php$ { set $args "${query_string}&${additionalQsVariable}"; [...]       }    }

Redirecting 51% of the traffic to another URL
http { split_clients "${remote_addr}" $redirectSite { 51% "1";	   49% "0";	}

server { location / { if ($redirectSite = "1") { return 302 "http://www.website2.com/"; }           [...]        }    }
 * Although on nginx IF is evil, we can use it in this specific case.

Appendix
Instead of ${remote_addr}, one could use ${cookie}, ${args} or any other nginx variable. You may also add a salt (arbitrary string) if you wish.


 * Keep in mind that if you use a variable like ${remote_addr} (user IP), the hash (and percentage) will always be the same as long as the user/client keep the same IP. In other words, the $variant value will always be the same for the same IP.
 * Hashing algorithm is MurmurHash2 since version 1.0.1; Previously CRC32.

= Directives =

split_clients


= References =


 * Original Documentation
 * Naming convention discussion