fossabot/redis-nginx-module

Redis module for Nginx

Name

ngx_redis - Brings "redis_pass" to get values from redis database.

This module is not distributed with the Nginx source. See the installation instructions.

Table of Contents

• Name
• Status
• Version
• Synopsis
• Description
• Directives
  • redis_pass
  • redis_bind
  • redis_connect_timeout
  • redis_read_timeout
  • redis_send_timeout
  • redis_buffer_size
  • redis_next_upstream
• Variables
  • $redis_key
  • $redis_db
  • $redis_auth
• Installation
• Compatibility
• Community
  • English Mailing List
  • Chinese Mailing List
• Report Bugs
• Source Repository
• Changes
• Test Suite
• Getting involved
• Author
• Copyright & License
• See Also

Status

This module is production ready.

Version

This document describes redis_pass v0.3.9.

Synopsis

    location / {
      set $redis_key  "$uri?$args";
      redis_pass      127.0.0.1:6379;
    }

    location / {
      set $redis_key  "$uri?$args";
      set $redis_db   "3";
      set $redis_auth "password";
      redis_pass      127.0.0.1:6379;
    }

http
{
 ...
    upstream redis {
        server  127.0.0.1:6379;
    }

    server {
     ...
        location / {
            set $redis_key  "$uri?$args"
            proxy_pass redis;
        }
        ...
     }
}

Back to TOC

Description

The nginx HTTP redis module for caching with redis.

The redis protocol implements GET and SELECT commands only.

This is fork of the ngx_http_redis module by Sergey A. Osokin.

Back to TOC

Directives

redis_pass

syntax: redis_pass <host>:<port>

default: no

context: location, location if

phase: content

Specify the Redis server backend.

redis_bind

syntax: redis_bind <addr>

default: none

context: http, server, location

Use the following IP address as the source address for redis connections.

redis_connect_timeout

syntax: redis_connect_timeout <time>

default: 60000

context: http, server, location

The timeout for connecting to redis, in milliseconds.

redis_read_timeout

syntax: redis_read_timeout <time>

default: 60000

context: http, server, location

The timeout for reading from redis, in milliseconds.

redis_send_timeout

syntax: redis_send_timeout <time>

default: 60000

context: http, server, location

The timeout for sending to redis, in milliseconds.

redis_buffer_size

syntax: redis_buffer_size <size>

default: see getpagesize(2)

context: http, server, location

The recv/send buffer size, in bytes.

redis_next_upstream

syntax: redis_next_upstream <error> <timeout> <invalid_response> <not_found> <off>

default: error timeout

context: http, server, location

Which failure conditions should cause the request to be forwarded to another upstream server? Applies only when the value in redis_pass is an upstream with two or more servers.

redis_gzip_flag

syntax: redis_gzip_flag <number>

default: unset

context: location

Reimplementation of memcached_gzip_flag, see https://forum.nginx.org/read.php?29,34332,34463 for details.

Back to TOC

Variables

$redis_key

The value of the redis key.

$redis_db

The redis database number to use. This is input value for SELECT command.

$redis_auth

The redis authentication to use. This is input value for AUTH command.

Back to TOC

Installation

You're recommended to install this module (as well as the Nginx core and many other goodies) via the OpenResty bundle. See the detailed instructions for downloading and installing OpenResty into your system. This is the easiest and most safe way to set things up.

Alternatively, you can install this module manually with the Nginx source:

Grab the nginx source code from nginx.org, for example, the version 1.11.2 (see nginx compatibility), and then build the source with this module:

 $ wget 'http://nginx.org/download/nginx-1.11.2.tar.gz'
 $ tar -xzvf nginx-1.11.2.tar.gz
 $ cd nginx-1.11.2/

 # Here we assume you would install you nginx under /opt/nginx/.
 $ ./configure --prefix=/opt/nginx \
     --add-module=/path/to/redis-nginx-module

 $ make -j2
 $ make install

Download the latest version of the release tarball of this module from redis-nginx-module file list.

Starting from NGINX 1.9.11, you can also compile this module as a dynamic module, by using the --add-dynamic-module=PATH option instead of --add-module=PATH on the ./configure command line above. And then you can explicitly load the module in your nginx.conf via the load_module directive, for example,

load_module /path/to/modules/ngx_http_redis_module.so;

Also, this module is included and enabled by default in the OpenResty bundle.

Back to TOC

Compatibility

The following versions of Nginx should work with this module:

• 1.13.x (last tested: 1.13.2)
• 1.12.x (last tested: 1.12.0)
• 1.11.x (last tested: 1.11.2)
• 1.10.x (last tested: 1.10.3)
• 1.9.x (last tested: 1.9.15)
• 1.8.x (last tested: 1.8.1)
• 1.7.x (last tested: 1.7.10)
• 1.6.x (last tested: 1.6.3)
• 1.5.x
• 1.4.x (last tested: 1.4.7)
• 1.3.x
• 1.2.x (last tested: 1.2.9)
• 1.1.x
• 1.0.x (last tested: 1.0.15

If you find that any particular version of Nginx does not work with this module, please consider reporting a bug.

Back to TOC

Community

Back to TOC

English Mailing List

The openresty-en mailing list is for English speakers.

Back to TOC

Chinese Mailing List

The openresty mailing list is for Chinese speakers.

Back to TOC

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

1. create a ticket on the issue tracking interface provided by GitHub,
2. or send a bug report, questions, or even patches to the OpenResty Community.

Back to TOC

Source Repository

Available on github at openresty/redis-nginx-module.

Back to TOC

Changes

You can see the changelist from CHANGES file.

Back to TOC

Test Suite

This module comes with a Perl-driven test suite. The test cases are declarative too. Thanks to the Test::Nginx module in the Perl world.

To run it on your side:

 $ PATH=/path/to/your/compiled-nginx-with-redis-module:$PATH prove -r t

You can also use the included Makefile to run tests in a docker containers:

$ make test

Note: The first installation takes quite some time (5-10min).

Back to TOC

Getting involved

You'll be very welcomed to submit patches to the author or just ask for a commit bit to the source repository on GitHub.

Back to TOC

Authors

Sergey A. Osokin <[email protected]>.

Yichun "agentzh" Zhang (章亦春) <[email protected]>, OpenResty Inc.

Onni "onnimonni" Hakala <[email protected]>, Keksi Labs Oy.

Back to TOC

Thanks to

Wang Yongke for his work on supporting redis AUTH with $redis_auth.

Maxim Dounin

Vsevolod Stakhov

Ezra Zygmuntowicz

Evan Miller for his "Guide To Nginx Module Development" and "Advanced Topics

In Nginx Module Development"

Valery Kholodkov for his "Nginx modules development"

Copyright & License

Copyright (C) 2002-2009 Igor Sysoev
Copyright (C) 2009-2013,2016 Sergey A. Osokin
 
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
   notice, this list of conditions and the following disclaimer.
2. 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.
 
THIS SOFTWARE IS PROVIDED BY AUTHOR 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 AUTHOR 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.

Back to TOC

See Also

• The original module in nginx.com.
• The OpenResty bundle.

Back to TOC

License