= Name =
memc-nginx-module - An extended version of the standard memcached module that supports set, add, delete, and many more memcached commands.
This module is not distributed with the Nginx source. See the installation instructions.
This document describes memc-nginx-module v0.04 released on Dec 22, 2009.
<geshi lang="nginx"> # GET /foo?key=dog # # POST /foo?key=cat # Cat's value... # # PUT /foo?key=bird # Bird's value... # # DELETE /foo?key=Tiger location /foo { set $memc_key $arg_key; # $memc_cmd defaults to get for GET, # add for POST, set for PUT, and # delete for the DELETE request method. memc_pass 127.0.0.1:11211; } </geshi> <geshi lang="nginx"> # GET /bar?cmd=get&key=cat # # POST /bar?cmd=set&key=dog # My value for the "dog" key... # # DELETE /bar?cmd=delete&key=dog # GET /bar?cmd=delete&key=dog location /bar { set $memc_cmd $arg_cmd; set $memc_key $arg_key; set $memc_flags $arg_flags; # defaults to 0 set $memc_exptime $arg_exptime; # defaults to 0 memc_pass 127.0.0.1:11211; } </geshi> <geshi lang="nginx"> # GET /bar?cmd=get&key=cat # GET /bar?cmd=set&key=dog&val=animal&flags=1234&exptime=2 # GET /bar?cmd=delete&key=dog # GET /bar?cmd=flush_all location /bar { set $memc_cmd $arg_cmd; set $memc_key $arg_key; set $memc_value $arg_val; set $memc_flags $arg_flags; # defaults to 0 set $memc_exptime $arg_exptime; # defaults to 0 memc_cmds_allowed get set add delete flush_all; memc_pass 127.0.0.1:11211; } </geshi><geshi lang="nginx"> http { ... upstream backend { server 127.0.0.1:11984; server 127.0.0.1:11985; } server { location /stats { set $memc_cmd stats; memc_pass backend; } ... } } ... </geshi>
This module extends the standard memcached module to support almost the whole memcached TCP protocol.
It allows you to define a custom REST interface to your memcached servers or access memcached in a very efficient way from within the nginx server by means of subrequests or independent fake requests.
This module is not supposed to be merged into the Nginx core because I've used Ragel to generate the memcached response parsers (in C) for joy :)
You need Maxim Dounin's ngx_upstream_keepalive module together with this module for keep-alive TCP connections to your backend memcached servers.
Here's a sample configuration:
<geshi lang="nginx"> http { upstream backend { server 127.0.0.1:11211; # a pool with at most 1024 connections # and do not distinguish the servers keepalive 1024 single; } server { ... location /memc { set $memc_cmd get; set $memc_key $arg_key; memc_pass backend; } } } </geshi>It implements the memcached TCP protocol all by itself, based upon the upstream
mechansim. Everything involving I/O is non-blocking.
The module itself does not keep TCP connections to the upstream memcached servers across requests, just like other upstream modules. For a working solution, see section Keep-alive connections to memcached servers.
The memcached storage commands set, add, replace, prepend, and append uses the $memc_key
as the key, $memc_exptime
as the expiration time (or delay) (defaults to 0), $memc_flags
as the flags (defaults to 0), to build the corresponding memcached queries.
If $memc_value
is not defined at all, then the request body will be used as the value of the $memc_value
except for the incr and decr commands. Note that if $memc_value
is defined as an empty string (""
), that empty string will still be used as the value as is.
The following memcached commands have been implemented and tested (with their parameters marked by corresponding nginx variables defined by this module):
Retrieves the value using a key.
<geshi lang="nginx"> location /foo { set $memc_cmd 'get'; set $memc_key 'my_key'; memc_pass 127.0.0.1:11211; add_header X-Memc-Flags $memc_flags; } </geshi>Returns 200 OK
with the value put into the response body if the key is found, or 404 Not Found
otherwise. The flags
number will be set into the $memc_flags
variable so it's often desired to put that info into the response headers by means of the standard add_header directive.
It returns 502
for ERROR
, CLIENT_ERROR
, or SERVER_ERROR
.
To use the request body as the memcached value, just avoid setting the $memc_value
variable:
Or let the $memc_value
hold the value:
Returns 201 Created
if the upstream memcached server replies STORED
, 200
for NOT_STORED
, 404
for NOT_FOUND
, 502
for ERROR
, CLIENT_ERROR
, or SERVER_ERROR
.
The original memcached responses are returned as the response body except for 404 NOT FOUND
.
Similar to the set command.
Similar to the set command.
Similar to the set command.
Note that at least memcached version 1.2.2 does not support the "append" and "prepend" commands. At least 1.2.4 and later versions seem to supports these two commands.
Similar to the append command.
Deletes the memcached entry using a key.
<geshi lang="nginx"> location /foo set $memc_cmd delete; set $memc_key my_key; memc_pass 127.0.0.1:11211; } </geshi>Returns 200 OK
if deleted successfully, 404 Not Found
for NOT_FOUND
, or 502
for ERROR
, CLIENT_ERROR
, or SERVER_ERROR
.
The original memcached responses are returned as the response body except for 404 NOT FOUND
.
Similar to the delete $memc_key command except it accepts an optional expiration
time specified by the $memc_exptime
variable.
This command is no longer available in the latest memcached version 1.4.4.
Increments the existing value of $memc_key
by the amount specified by $memc_value
:
<geshi lang="nginx"> location /foo { set $memc_key my_key; set $memc_value 2; memc_pass 127.0.0.1:11211; } </geshi>
In the preceding example, every time we access /foo
will cause the value of my_key
increments by 2
.
Returns 200 OK
with the new value associated with that key as the response body if successful, or 404 Not Found
if the key is not found.
It returns 502
for ERROR
, CLIENT_ERROR
, or SERVER_ERROR
.
Similar to incr $memc_key $memc_value.
Mark all the keys on the memcached server as expired:
<geshi lang="nginx"> location /foo { set $memc_cmd flush_all; memc_pass 127.0.0.1:11211; } </geshi>
Just like flush_all but also accepts an expiration time specified by the $memc_exptime
variable.
Causes the memcached server to output general-purpose statistics and settings
<geshi lang="nginx"> location /foo { set $memc_cmd stats; memc_pass 127.0.0.1:11211; } </geshi>
Returns 200 OK
if the request succeeds, or 502 for ERROR
, CLIENT_ERROR
, or SERVER_ERROR
.
The raw stats
command output from the upstream memcached server will be put into the response body.
Queries the memcached server's version number:
<geshi lang="nginx"> location /foo { set $memc_cmd version; memc_pass 127.0.0.1:11211; } </geshi>
Returns 200 OK
if the request succeeds, or 502 for ERROR
, CLIENT_ERROR
, or SERVER_ERROR
.
The raw version
command output from the upstream memcached server will be put into the response body.
All the standard memcached module directives in nginx 0.8.28 are directly inherited, with the memcached_
prefixes replaced by memc_
. For example, the memcached_pass
directive is spelled memc_pass
. Consult the NginxHttpMemcachedModule documentation for more details.
Here we only document the most important two directives (the latter is a new directive introduced by this module).
syntax: memc_pass <memcached_server_ip></memcached_server_ip>:<memcached_server_port></memcached_server_port>
syntax (2): memc_pass <upstream_backend_name></upstream_backend_name>
default: none
context: http, server, location, if
Specify the memcached server backend.
syntax: memc_cmds_allowed <cmd></cmd>...
default: none
context: http, server, location, if
Lists memcached commands that are allowed to access. By default, all the memcached commands supported by this module are accessible. An example is
<geshi lang="nginx">
memc_pass 127.0.0.1:11211; memc_cmds_allowed get; }
</geshi>
Then /foo?cmd&amp;amp&#59;&amp;&#35;35&#59;61&amp;&#35;59&#59;set&amp;amp&#59;amp&amp;&#35;59&#59;key&amp;amp&#59;&amp;&#35;35&#59;61&amp;&#35;59&#59;foo&amp;amp&#59;amp&amp;&#35;59&#59;val&amp;amp&#59;&amp;&#35;35&#59;61&amp;&#35;59&#59;bar
and /foo?cmd&amp;amp&#59;&amp;&#35;35&#59;61&amp;&#35;59&#59;flush_all
will both fail and yield 403 Forbidden
.
Grab the nginx source code from nginx.net, for example, the version 0.8.29 (see nginx compatibility), and then build the source with this module:
<geshi lang="bash">
# Here we assume you would install you nginx under /opt/nginx/. $ ./configure --prefix=/opt/nginx \ --add-module=/path/to/memc-nginx-module $ make -j2 $ make install
</geshi>
Download the latest version of the release tarball of this module from memc-nginx-module file list.
The memached response parsers were generated by Ragel. If you want to regenerate the parser's C file, i.e., src/ngx_http_memc_response.c, use the following command from the root of the memc module's source tree:
<geshi lang="bash">
$ ragel -G2 src/ngx_http_memc_response.rl
</geshi>
The following versions of Nginx should work with this module:
- 0.8.x (last tested version is 0.8.30)
- 0.7.x >= 0.7.46 (last tested version is 0.7.64)
Earlier versions of Nginx like 0.6.x and 0.5.x will not work.
If you find that any particular version of Nginx above 0.7.46 does not work with this module, please consider reporting a bug.
Although a lot of effort has been put into testing and code tuning, there must be some serious bugs lurking somewhere in this module. So whenever you are bitten by any quirks, please don't hesitate to
- send a bug report or even patches to <agentzh@gmail.com></agentzh@gmail.com>,
- or create a ticket on the issue tracking interface provided by GitHub.
Available on github at agentzh/memc-nginx-module.
- to ensure Maxim's ngx_http_upstream_keepalive module caches our connections even if
u&amp;amp&#59;amp&amp;&#35;59&#59;&amp;amp&#59;&amp;&#35;35&#59;35&amp;&#35;59&#59;45&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;&amp;amp&#59;amp&amp;&#35;59&#59;gt&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;headers_in&amp;amp&#59;amp&amp;&#35;59&#59;&amp;amp&#59;&amp;&#35;35&#59;35&amp;&#35;59&#59;45&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;&amp;amp&#59;amp&amp;&#35;59&#59;gt&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;status
is 201 (Created). - updated docs to make it clear that this module can work with "upstream" multi-server backends. thanks Bernd Dorn for reporting it.
- fixed a connection leak caused by an extra
r&amp;amp&#59;amp&amp;&#35;59&#59;&amp;amp&#59;&amp;&#35;35&#59;35&amp;&#35;59&#59;45&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;&amp;amp&#59;amp&amp;&#35;59&#59;gt&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;main&amp;amp&#59;amp&amp;&#35;59&#59;&amp;amp&#59;&amp;&#35;35&#59;35&amp;&#35;59&#59;45&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;&amp;amp&#59;amp&amp;&#35;59&#59;gt&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;count++
operation: we should NOT dor&amp;amp&#59;amp&amp;&#35;59&#59;&amp;amp&#59;&amp;&#35;35&#59;35&amp;&#35;59&#59;45&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;&amp;amp&#59;amp&amp;&#35;59&#59;gt&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;main&amp;amp&#59;amp&amp;&#35;59&#59;&amp;amp&#59;&amp;&#35;35&#59;35&amp;&#35;59&#59;45&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;&amp;amp&#59;amp&amp;&#35;59&#59;gt&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;count++
after calling thengx_http_read_client_request_body
function in our content handler.
- applied the (minor) optimization trick suggested by Marcus Clyne: creating our variables and save their indexes at post-config phase when the memc_pass directive is actually used in the config file.
- initial release.
This module comes with a Perl-driven test suite. The test cases are declarative too. Thanks to the Test::Base module in the Perl world.
To run it on your side:
<geshi lang="bash">
$ cd test $ PATH=/path/to/your/nginx-with-memc-module:$PATH prove -r t
</geshi>
You need to terminate any Nginx processes before running the test suite if you have changed the Nginx server binary.
Either LWP::UserAgent or IO::Socket is used by the test scaffold.
Because a single nginx server (by default, localhost&amp;amp&#59;amp&amp;&#35;59&#59;&amp;amp&#59;&amp;&#35;35&#59;35&amp;&#35;59&#59;58&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;1984
) is used across all the test scripts (.t
files), it's meaningless to run the test suite in parallel by specifying &amp;amp&#59;amp&amp;&#35;59&#59;&amp;amp&#59;&amp;&#35;35&#59;35&amp;&#35;59&#59;45&amp;amp&#59;&amp;&#35;35&#59;59&amp;&#35;59&#59;jN
when invoking the prove
utility.
You should also keep a memcached server listening on the 11984
port at localhost before running the test suite.
Some parts of the test suite requires modules rewrite and echo to be enabled as well when building Nginx.
- add support for the memcached commands
cas
,gets
andstats $memc_value
. - add support for the
noreply
option.
You'll be very welcomed to submit patches to the author or just ask for a commit bit to the source repository on GitHub.
agentzh (章亦春) <agentzh@gmail.com></agentzh@gmail.com>
This wiki page is also maintained by the author himself, and everybody is encouraged to improve this page as well.
The code base is borrowed directly from the standard memcached module in the Nginx 0.8.28 core. This part of code is copyrighted by Igor Sysoev.
Copyright (c) 2009, Taobao Inc., Alibaba Group ( http://www.taobao.com ).
Copyright (c) 2009, agentzh <agentzh@gmail.com></agentzh@gmail.com>.
This module is licensed under the terms of the BSD license.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the Taobao Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
- The original announcement email on the nginx mailing list: ngx_memc: "an extended version of ngx_memcached that supports set, add, delete, and many more commands"
- The latest memcached TCP protocol.
- The standard memcached module.
- The echo module for Nginx module's automated testing.
- The standard headers module and the 3rd-parth headers-more module.