[edit] ngx_http_upstream_consistent_hash

This module is a loadbalancer which uses an internal consistent hash ring to select the right backend node. It is designed to be compatible with the "consistent" hash_strategy of the php-memcache module. This means you can store values into a memcached cluster, using the php-memcache module, and later the nginx can find that value in the cluster to read it from there.

[edit] Directives

[edit] consistent_hash

"syntax:" "consistent_hash <string to hash>"

"default:" "none"

"context:" "upstream"

This parameter has to be inside the upstream definition. It turns on the consistent hash upstream module, and also defines the string which has to be hashed to find the right backend on the hash ring. As an example, you could do this:

[edit] Example

    upstream somestream {
      consistent_hash $request_uri;
      server 10.50.1.3:11211;
      server 10.50.1.4:11211;
      server 10.50.1.5:11211;
    }
 
...
 
server {
        listen       80;
        server_name  localhost;
 
        location / {
          default_type text/html;
          set $memcached_key $request_uri;
          memcached_pass somestream;
          error_page      500 404 405 = @fallback;
        }
 
        location @fallback {
          root /srv/www/whatever;
          fastcgi_intercept_errors on;
          error_page 404 = @404;
 
          set $script $uri;
          set $path_info "";
 
          include /usr/local/nginx/conf/fastcgi_params;
          fastcgi_param SCRIPT_FILENAME /srv/www/whatever/test.php;
          fastcgi_param SCRIPT_NAME $script;
          fastcgi_param REQUEST_URI $uri;
          fastcgi_pass   127.0.0.1:9000;
        }
    }

This example uses uses three backend servers. On initialization the nginx will create a hashring which contains each server (160 * weight) times in the same way as the php-memcache module with hash_strategy consistent does. Based on a hash of $request_uri it will decide which backend server has to be used. Now the test.php script from the above example could look like following:

$memcache = new Memcache;
 
$memcache->addServer('10.50.1.3', 11211);
$memcache->addServer('10.50.1.4', 11211);
$memcache->addServer('10.50.1.4', 11211);
 
$memcache->set($_SERVER["REQUEST_URI"], $_SERVER["REQUEST_URI"] . " from memcache");

[edit] Important to know

- I tested with the php memcache module version 1.2.8. It seems that the module in this version has a bug which causes it to completely ignore the weight if hash_strategy is set to consistent_hash. The nginx consistent hash upstream knows the weight parameter, but if you use it together with memcache module 1.2.8 you shouldn`t touch the weight for any backend server.

- I tested the module with nginx 0.7.61 and 0.6.34, no guarantee for other versions

[edit] Bugs/Feedback

In case you find any bugs, please write me a mail and I will try to help.

If you are using that module, i would appreciate every kind of feedback or problem reports.

Mail: mauro.stettler(A.T)gmail.com

[edit] Download

On github i have to branches "master" and "dns". The reason for this is that if you want to use dns entries on the php side, instead of ips, you will need to apply a patch to the nginx to make this work. So if your PHP does not use DNS names to connect to memcache, its nicer to download the "master" branch, because this is a clean module. If your PHP uses DNS names, you have to download the "dns" branch, which includes a patch for the nginx.

[Download from github]