Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Fetching latest commit…

Cannot retrieve the latest commit at this time

..
Failed to load latest commit information.
readme.wiki

readme.wiki

= 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 [[#Installation|the installation instructions]].

= Version =

This document describes memc-nginx-module [http://github.com/agentzh/memc-nginx-module/tarball/v0.11 v0.11] released on Oct 28, 2010.

= Synopsis =

<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>

<geshi lang="nginx">
    # read the memcached flags into the Last-Modified header
    # to respond 304 to conditional GET
    location /memc {
        set $memc_key $arg_key;

        memc_pass 127.0.0.1:11984;

        memc_flags_to_last_modified on;
    }
</geshi>

= Description =

This module extends the standard [[NginxHttpMemcachedModule|memcached module]] to support almost the whole [http://code.sixapart.com/svn/memcached/trunk/server/doc/protocol.txt memcached TCP protocol].

It allows you to define a custom [http://en.wikipedia.org/wiki/REST REST] interface to your memcached servers or access memcached in a very efficient way from within the nginx server by means of subrequests or [http://github.com/srlindsay/nginx-independent-subrequest independent fake requests].

This module is not supposed to be merged into the Nginx core because I've used [http://www.complang.org/ragel/ Ragel] to generate the memcached response parsers (in C) for joy :)

If you are going to use this module to cache location responses out of the box, try my ngx_srcache module with this module to achieve that:

    http://github.com/agentzh/srcache-nginx-module

== Keep-alive connections to memcached servers ==

You need Maxim Dounin's [http://mdounin.ru/hg/ngx_http_upstream_keepalive/ 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>

== How it works ==

It implements the memcached TCP protocol all by itself, based upon the <code>upstream</code> 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|Keep-alive connections to memcached servers]].

= Memcached commands supported =

The memcached storage commands [[#set $memc_key $memc_flags $memc_exptime $memc_value|set]], [[#add $memc_key $memc_flags $memc_exptime $memc_value|add]], [[#replace $memc_key $memc_flags $memc_exptime $memc_value|replace]], [[#prepend $memc_key $memc_flags $memc_exptime $memc_value|prepend]], and [[#append $memc_key $memc_flags $memc_exptime $memc_value|append]] uses the <code>$memc_key</code> as the key, <code>$memc_exptime</code> as the expiration time (or delay) (defaults to 0), <code>$memc_flags</code> as the flags (defaults to 0), to build the corresponding memcached queries.

If <code>$memc_value</code> is not defined at all, then the request body will be used as the value of the <code>$memc_value</code> except for the [[#incr $memc_key $memc_value|incr]] and [[#decr $memc_key $memc_value|decr]] commands. Note that if <code>$memc_value</code> is defined as an empty string (<code>""</code>), 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):

== get $memc_key ==

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 <code>200 OK</code> with the value put into the response body if the key is found, or <code>404 Not Found</code> otherwise. The <code>flags</code> number will be set into the <code>$memc_flags</code> variable so it's often desired to put that info into the response headers by means of the standard [[NginxHttpHeadersModule#add_header|add_header directive]].

It returns <code>502</code> for <code>ERROR</code>, <code>CLIENT_ERROR</code>, or <code>SERVER_ERROR</code>.

== set $memc_key $memc_flags $memc_exptime $memc_value ==

To use the request body as the memcached value, just avoid setting the <code>$memc_value</code> variable:

<geshi lang="nginx">
  # POST /foo
  # my value...
  location /foo {
      set $memc_cmd 'set';
      set $memc_key 'my_key';
      set $memc_flags 12345;
      set $memc_exptime 24;
      
      memc_pass 127.0.0.1:11211;
  }
</geshi>

Or let the <code>$memc_value</code> hold the value:

<geshi lang="nginx">
  location /foo {
      set $memc_cmd 'set';
      set $memc_key 'my_key';
      set $memc_flags 12345;
      set $memc_exptime 24;
      set $memc_value 'my_value';

      memc_pass 127.0.0.1:11211;
  }
</geshi>

Returns <code>201 Created</code> if the upstream memcached server replies <code>STORED</code>, <code>200</code> for <code>NOT_STORED</code>, <code>404</code> for <code>NOT_FOUND</code>, <code>502</code> for <code>ERROR</code>, <code>CLIENT_ERROR</code>, or <code>SERVER_ERROR</code>.

The original memcached responses are returned as the response body except for <code>404 NOT FOUND</code>.

== add $memc_key $memc_flags $memc_exptime $memc_value ==

Similar to the [[#set $memc_key $memc_flags $memc_exptime $memc_value|set command]].

== replace $memc_key $memc_flags $memc_exptime $memc_value ==

Similar to the [[#set $memc_key $memc_flags $memc_exptime $memc_value|set command]].

== append $memc_key $memc_flags $memc_exptime $memc_value ==

Similar to the [[#set $memc_key $memc_flags $memc_exptime $memc_value|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.

== prepend $memc_key $memc_flags $memc_exptime $memc_value ==

Similar to the [[#append $memc_key $memc_flags $memc_exptime $memc_value|append command]].

== delete $memc_key ==

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 <code>200 OK</code> if deleted successfully, <code>404 Not Found</code> for <code>NOT_FOUND</code>, or <code>502</code> for <code>ERROR</code>, <code>CLIENT_ERROR</code>, or <code>SERVER_ERROR</code>.

The original memcached responses are returned as the response body except for <code>404 NOT FOUND</code>.

== delete $memc_key $memc_exptime ==

Similar to the [[#delete $memc_key|delete $memc_key]] command except it accepts an optional <code>expiration</code> time specified by the <code>$memc_exptime</code> variable.

This command is no longer available in the latest memcached version 1.4.4.

== incr $memc_key $memc_value ==

Increments the existing value of <code>$memc_key</code> by the amount specified by <code>$memc_value</code>:

<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 <code>/foo</code> will cause the value of <code>my_key</code> increments by <code>2</code>.

Returns <code>200 OK</code> with the new value associated with that key as the response body if successful, or <code>404 Not Found</code> if the key is not found.

It returns <code>502</code> for <code>ERROR</code>, <code>CLIENT_ERROR</code>, or <code>SERVER_ERROR</code>.

== decr $memc_key $memc_value ==

Similar to [[#incr $memc_key $memc_value|incr $memc_key $memc_value]].

== flush_all ==

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>

== flush_all $memc_exptime ==

Just like [[#flush_all|flush_all]] but also accepts an expiration time specified by the <code>$memc_exptime</code> variable.

== stats ==

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 <code>200 OK</code> if the request succeeds, or 502 for <code>ERROR</code>, <code>CLIENT_ERROR</code>, or <code>SERVER_ERROR</code>.

The raw <code>stats</code> command output from the upstream memcached server will be put into the response body. 

== version ==

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 <code>200 OK</code> if the request succeeds, or 502 for <code>ERROR</code>, <code>CLIENT_ERROR</code>, or <code>SERVER_ERROR</code>.

The raw <code>version</code> command output from the upstream memcached server will be put into the response body.

= Directives =

All the standard [[NginxHttpMemcachedModule|memcached module]] directives in nginx 0.8.28 are directly inherited, with the <code>memcached_</code> prefixes replaced by <code>memc_</code>. For example, the <code>memcached_pass</code> directive is spelled <code>memc_pass</code>. 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).

== memc_pass ==

'''syntax:''' ''memc_pass <memcached server IP address>:<memcached server port>''

'''syntax (2):''' ''memc_pass <memcached server hostname>:<memcached server port>''

'''syntax (3):''' ''memc_pass <upstream_backend_name>''

'''default:''' ''none''

'''context:''' ''http, server, location, if''

Specify the memcached server backend.

== memc_cmds_allowed ==
'''syntax:''' ''memc_cmds_allowed <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">
   location /foo {
       set $memc_cmd $arg_cmd;
       set $memc_key $arg_key;
       set $memc_value $arg_val;
       
       memc_pass 127.0.0.1:11211;
        
       memc_cmds_allowed get;
   }
</geshi>

== memc_flags_to_last_modified ==
'''syntax:''' ''memc_flags_to_last_modified on|off''

'''default:''' ''off''

'''context:''' ''http, server, location, if''

Read the memcached flags as epoch seconds and set it as the value of the <code>Last-Modified</code> header. For conditional GET, it will signal nginx to return <code>304 Not Modified</code> response to save bandwidth.

== memc_connect_timeout ==
'''syntax:''' ''memc_connect_timeout <time>''

'''default:''' ''60s''

'''context:''' ''http, server, location''

The timeout for connecting to the memcached server. You can specify a time unit like "s" (for seconds), "ms" (for milliseconds). The default time unit is "ms".

== memc_send_timeout ==
'''syntax:''' ''memc_send_timeout <time>''

'''default:''' ''60s''

'''context:''' ''http, server, location''

The timeout for sending TCP requests to the memcached server. You can specify a time unit like "s" (for seconds), "ms" (for milliseconds). The default time unit is "ms".

== memc_read_timeout ==
'''syntax:''' ''memc_read_timeout <time>''

'''default:''' ''60s''

'''context:''' ''http, server, location''

The timeout for reading TCP responses from the memcached server. You can specify a time unit like "s" (for seconds), "ms" (for milliseconds). The default time unit is "ms".

== memc_buffer_size ==
'''syntax:''' ''memc_buffer_size <time>''

'''default:''' ''4k/8k''

'''context:''' ''http, server, location''

This buffer size is used for the memory buffer to hold

* the complete response for memcached commands other than "get",
* the complete response header (i.e., the first line of the response) for the "get" memcached command.

This default size is the page size, may be 4k or 8k.

= Installation =

Grab the nginx source code from [http://nginx.net/ nginx.net], for example,
the version 0.8.41 (see [[#Compatibility|nginx compatibility]]), and then build the source with this module:

<geshi lang="bash">
    $ wget 'http://sysoev.ru/nginx/nginx-0.8.41.tar.gz'
    $ tar -xzvf nginx-0.8.41.tar.gz
    $ cd nginx-0.8.41/
    
    # 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 [http://github.com/agentzh/memc-nginx-module/downloads memc-nginx-module file list].

== For Developers ==

The memached response parsers were generated by [http://www.complang.org/ragel/ Ragel]. If you want to
regenerate the parser's C file, i.e., [http://github.com/agentzh/memc-nginx-module/blob/master/src/ngx_http_memc_response.c 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>

= Compatibility =

The following versions of Nginx should work with this module:

* '''0.8.x'''                       (last tested version is 0.8.49)
* '''0.7.x >= 0.7.46'''             (last tested version is 0.7.67)

It's worth mentioning that some 0.7.x versions older than 0.7.46 might also work, but I can't easily test them because the test suite makes extensive use of the [[NginxHttpEchoModule|echo module]]'s [[NginxHttpEchoModule#echo_location|echo_location directive]], which requires at least nginx 0.7.46 :)

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 [[#Report Bugs|reporting a bug]].

= Report Bugs =

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>,
# or create a ticket on the [http://github.com/agentzh/memc-nginx-module/issues issue tracking interface] provided by GitHub.

= Source Repository =

Available on github at [http://github.com/agentzh/memc-nginx-module agentzh/memc-nginx-module].

= ChangeLog =

== v0.11 ==
* fixed the zero size buf alert in error.log when $memc_value is set to empty (). thanks iframist.

== v0.10 ==
* we no longer use the problematic <code>ngx_strXcmp</code> macros in our source because it may cause invalid reads and thus segmentation faults. thanks Piotr Sikora.

== v0.09 ==
* now we copy out <code>r->request_body->bufs</code> for our memcached request to avoid modifying the original request body. Thanks Matthieu Tourne.

== v0.08 ==
* now the memc commands other than get work with subrequests in memory. Thanks Yao Xinming for reporting it. Using storage memcached commands in ngx_eval module's eval blocks no longer hang the server.

== v0.07 ==
* applied the patch from nginx 0.8.35 that fixed a bug that ngx_eval may issue the incorrect error message "memcached sent invalid trailer".

== v0.06 ==
* implemented the [[#memc_flags_to_last_modified|memc_flags_to_last_modified]] directive.
* added a new variable named [[#$memc_flags_as_http_time|$memc_flags_as_http_time]].

== v0.05 ==
* removed the <code>memc_bind</code> directive since it won't compile with nginx 0.8.31.

== v0.04 ==
* to ensure Maxim's [http://mdounin.ru/hg/ngx_http_upstream_keepalive/ ngx_http_upstream_keepalive] module caches our connections even if <code>u->headers_in->status</code> 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.

== v0.03 ==
* fixed a connection leak caused by an extra <code>r->main->count++</code> operation: we should NOT do <code>r->main->count++</code> after calling the <code>ngx_http_read_client_request_body</code> function in our content handler.

== v0.02 ==
* applied the (minor) optimization trick suggested by Marcus Clyne: creating our variables and save their indexes at post-config phase when the [[#memc_pass|memc_pass]] directive is actually used in the config file.

== v0.01 ==
* initial release.

= Test Suite =

This module comes with a Perl-driven test suite. The [http://github.com/agentzh/memc-nginx-module/tree/master/test/t/ test cases] are
[http://github.com/agentzh/memc-nginx-module/blob/master/test/t/storage.t declarative] too. Thanks to the [http://search.cpan.org/perldoc?Test::Base 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 [http://search.cpan.org/perldoc?LWP::UserAgent LWP::UserAgent] or [http://search.cpan.org/perldoc?IO::Socket IO::Socket] is used by the [http://github.com/agentzh/memc-nginx-module/blob/master/test/lib/Test/Nginx/LWP.pm test scaffold].

Because a single nginx server (by default, <code>localhost:1984</code>) is used across all the test scripts (<code>.t</code> files), it's meaningless to run the test suite in parallel by specifying <code>-jN</code> when invoking the <code>prove</code> utility.

You should also keep a memcached server listening on the <code>11984</code> port at localhost before running the test suite.

Some parts of the test suite requires modules [[NginxHttpRewriteModule|rewrite]] and [[NginxHttpEchoModule|echo]] to be enabled as well when building Nginx.

= TODO =

* add support for the memcached commands <code>cas</code>, <code>gets</code> and <code>stats $memc_value</code>.
* add support for the <code>noreply</code> option.

= Getting involved =

You'll be very welcomed to submit patches to the [[#Author|author]] or just ask for a commit bit to the [[#Source Repository|source repository]] on GitHub.

= Author =

agentzh (章亦春) ''<agentzh@gmail.com>''

This wiki page is also maintained by the author himself, and everybody is encouraged to improve this page as well.

= Copyright & License =

The code base is borrowed directly from the standard [[NginxHttpMemcachedModule|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>.

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.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

= See Also =

* The original announcement email on the nginx mailing list: [http://forum.nginx.org/read.php?2,28359 ngx_memc: "an extended version of ngx_memcached that supports set, add, delete, and many more commands"]
* My slides demonstrating various ngx_memc usage: http://agentzh.org/misc/slides/nginx-conf-scripting/nginx-conf-scripting.html#34 (use the arrow or pageup/pagedown keys on the keyboard to swith pages)
* The latest [http://code.sixapart.com/svn/memcached/trunk/server/doc/protocol.txt memcached TCP protocol].
* The [http://github.com/agentzh/srcache-nginx-module ngx_srcache] module
* The standard [[NginxHttpMemcachedModule|memcached]] module.
* The [[NginxHttpEchoModule|echo module]] for Nginx module's automated testing.
* The standard [[NginxHttpHeadersModule|headers]] module and the 3rd-parth [[NginxHttpHeadersMoreModule|headers-more]] module.

Something went wrong with that request. Please try again.