yaoweibin / Nginx_limit_access_module

Name nginx_limit_access_module - support to deny request by specific variable with HTTP POST interface

Status This module is at its very early phase of development and considered highly experimental. But you're encouraged to test it out on your side and report any quirks that you experience.

We need your help! If you find this module useful and/or interesting,
please consider joining the development!

Synopsis a simple deny ip example: http {

    limit_access_zone  zone=one:5m bucket_number=10007 type=ip;

    server {
        listen       80;
        server_name  localhost;

        limit_access_variable zone=one $limit_access_deny;

        location / {
            root   html;
            index  index.html index.htm;

            if ($limit_access_deny) {
                return 403;
            }
        }

        location /limit_interface {
            allow   192.168.1.0/24;
            deny all;
            limit_access_interface zone=one;
        }
    }
}

deny both $remote_addr and $host example: http {

    limit_access_zone  zone=addr:5m bucket_number=10007 type=$remote_addr;
    limit_access_zone  zone=host:5m bucket_number=10007 type=$host;

    server {
        listen       80;
        server_name  _;

        limit_access_variable zone=addr $limit_access_deny_addr;
        limit_access_variable zone=host $limit_access_deny_host;

        location / {
            root   html;
            index  index.html index.htm;

            if ($limit_access_deny_addr) {
                return 403;
            }

            if ($limit_access_deny_host) {
                return 403;
            }
        }

        location /limit_interface_addr {
            allow   192.168.1.0/24;
            deny all;
            limit_access_interface zone=addr;
        }

        location /limit_interface_host {
            allow   192.168.1.0/24;
            deny all;
            limit_access_interface zone=host;
        }
    }
}

Description This module can deny request specific variable with HTTP POST interface.

Directives limit_access_zone syntax: limit_access_zone zone=name:size [bucket_number=number] [type=ip|$your_variable];

default: *none*

context: *http*

The directive describes the area, which stores the record of the limit
hash table. Example of usage:

limit_access_zone zone=one:5m bucket_number=10007 type=ip;

In this case, the hash table is allocated 5MB as a zone called "one".
The hash table's bucket number is 10007. We can get the record's key of
this hash table from the remainder $binary_remote_addr with
bucket_number.

If the record is the type of ip, each record's size is about 32 bytes.
If you have a 5M zone, it can hold about 100k+ records.

The type can be 'ip' or any of the variable in Nginx. I use the 'ip' as
a special variable while I treat the ip as an integer. This can save
some storage memory. Otherwise, I treat all the variable to be string.

limit_access_interface syntax: limit_access_interface zone=name;

default: *none*

context: *location*

This directive set the interface location where you can add or delete
the deny list. See the section of Interface for detail.

limit_access syntax: limit_access zone=name;

default: *none*

context: *http, server, location*

This directive set the location where you can deny specific variable
from the zone's record. If you want to do deny action in several
locations, you can use this directive in their parent block. The
directive is like the deny
(<http://wiki.nginx.org/HttpAccessModule#deny>).

It will look up the zone's hash table. If it find the request's variable
is in the hash table and it's not expired, then return 403.

limit_access_variable syntax: limit_access_variable zone=name $limit_access_variable_name;

default: *none*

context: *http, server, location*

This directive set the name of variable and the zone attached with the
variable. When you access this variable, the variable will do like the
limit_access directive. It will look up the zone's hash table. If it
finds the request's variable is in the hash table and it's not expired,
then the value is '1'. If not, the value is null.

If you want to do the same deny action in several locations, you can use
the directive of *limit_acccess*.

limit_access_default_expire syntax: limit_access_default_expire expire_time;

default: *1d*

context: *http, server, location*

Set the default expire time for the ban list record. Default expire time
is 1 day. The unit of time can be: s(second,default), m(minute),
h(hour), d(day), w(week), M(month), y(year).

limit_access_buffer_size syntax: limit_access_buffer_size size;

default: *256k*

context: *http, server, location*

Specify the output buffer size. If you have a large hash table and want
to show all the records, your result page may be truncated to the buffer
size. You could enlarge the buffer size. Each record could take up about
128 bytes.

limit_access_log_level syntax: limit_access_log_level info|notice|warn|error;

default: *limit_access_log_level error*

context: *http, server, location*

Control the log level of the request deny message.

Interface The request method sent to the interface location is POST, and the content-type is application/x-www-form-urlencoded. The content is like this:

ban_type=variable&ban_expire=3600&ban_list=192.168.1.1,192.168.1.2

The parameters' specification is:

ban_type: the type of ban_list. It can be: ip, variable. It's related
with the type of zone.

ban_expire: the expire time for the ban list. The unit of time can be:
s(second,default), m(minute), h(hour), d(day), w(week), M(month),
y(year).

ban_list: the ban list, the ipv4 address can also be sent by a binary
form.

free_type: the type of free_list.

free_list: free the ban list, the variable will not be denied any more.

show_type: the type of show_list.

show_list: show the ban list. You can get the specific ban list like
this:

show_type=variable&show_list=127.0.0.1,127.1.1.1

If your zone's type is IP, and you want to show all the current ban IP
list, You can do like this:

show_type=ip&show_list=all

destroy_list: invalidate all the current ban list, then all the client
request is allowed.

Installation Download the latest version of the release tarball of this module from github (http://github.com/yaoweibin/nginx_limit_access_module)

Grab the nginx source code from nginx.org (<http://nginx.org/>), for
example, the version 0.8.53 (see nginx compatibility), and then build
the source with this module:

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

    $ ./configure --add-module=/path/to/nginx_limit_access_module

    $ make
    $ make install

Compatibility My test bed 0.8.53. TODO Known Issues Developing Changelogs v0.1 first release Authors Weibin Yao(姚伟斌) yaoweibin AT gmail DOT com License This README template is from agentzh (http://github.com/agentzh).

This module is licensed under 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.
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.