FAQ

Page Discussion History

Difference between revisions of "HttpSplitClientsModule"

(References: Added link to the original documentation)
 
(9 intermediate revisions by 3 users not shown)
Line 1: Line 1:
 +
__NOINDEX__
 +
 +
<span style="color:red">WARNING: this article is obsoleted. Please refer to http://nginx.org/en/docs/ for the latest official documentation.</span>
 +
 
= Synopsis =
 
= Synopsis =
  
 
ngx_http_split_clients_module is used to split clients based on some conditions(e.g ip addresses, headers, cookies, etc).
 
ngx_http_split_clients_module is used to split clients based on some conditions(e.g ip addresses, headers, cookies, etc).
  
Example configuration:
+
= Examples =
 +
 
 +
== Basic configuration: ==
 
<geshi lang="nginx">
 
<geshi lang="nginx">
 
http {
 
http {
 
     split_clients "${remote_addr}AAA" $variant {
 
     split_clients "${remote_addr}AAA" $variant {
         0.5% .one;
+
         40.5% ".one";
         2.0% .two;
+
         59.5% ".two";
        - "";
+
 
     }
 
     }
  
Line 15: Line 20:
 
         location / {
 
         location / {
 
             index index${variant}.html;
 
             index index${variant}.html;
 +
        [...]
 +
    }
 
</geshi>
 
</geshi>
  
$cookie_..., etc, may be used as a source for splitting. The source string is hashed using MurmurHash2 (as of 1.0.1; previously CRC32) and the percent of the hash is used as source value.
+
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";
  
= Directives =
+
== Sending a query string variable to 51% of clients (to PHP scripts) ==
 +
<geshi lang="nginx">
 +
http {
 +
    split_clients "${remote_addr}" $additionalQsVariable {
 +
    51% "coolVariable=1";
 +
    49% "";
 +
}
  
== split_clients ==
+
    server {
'''syntax:''' ''split_clients  $variable { ... } ''
+
        location ~ \.php$ {
 +
            set $args "${query_string}&${additionalQsVariable}";
 +
            [...]
 +
        }
 +
    }
 +
</geshi>
  
'''default:''' ''none''
+
== Redirecting 51% of the traffic to another URL ==
 +
<geshi lang="nginx">
 +
http {
 +
    split_clients "${remote_addr}" $redirectSite {
 +
    51% "1";
 +
    49% "0";
 +
}
  
'''context:''' ''http''
+
    server {
 +
        location / {
 +
            if ($redirectSite = "1") {
 +
                return 302 "http://www.website2.com/";
 +
            }
 +
            [...]
 +
        }
 +
    }
 +
</geshi>
 +
* Although on nginx [http://wiki.nginx.org/IfIsEvil IF is evil], we can use it in this specific case.
 +
 
 +
== Appendix ==
 +
 
 +
Instead of '''${remote_addr}''', one could use '''${cookie}''', '''${args}''' or any other [http://wiki.nginx.org/HttpCoreModule#Variables 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 ==
 +
<include wikitext nopre src="http://wiki.nginx.org/nginx.org/http/ngx_http_split_clients_module/split_clients.txt" />
  
 
= References =
 
= References =

Latest revision as of 11:13, 10 April 2014


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

Contents

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

Syntax: split_clients string $variable { ... }
Default:
Context: http
Reference:split_clients


References