laobei2012/nginx-limit-traffic-rate-moduleDocumentation

Notes on the limit_traffic_rate module
=====

To install, compile nginx with this ./configure option:

    --add-module=path/to/this/directory

To build it as a dynamic module instead (nginx 1.9.11 or later), use:

    --add-dynamic-module=path/to/this/directory

and load it at the top level of nginx.conf (outside the http block):

    load_module modules/ngx_http_limit_traffic_rate_filter_module.so;

Nginx directive limit_rate could limit connection's speed, and limit_conn 
could limit connection number by given variable. If the client is a browser,
 it only open one connection to the server. The speed will be limited to 
limit_rate, unless the client is a multi-thread download tool.

Limit_traffic_rate module provides a method to limit the total download rate
 by client IP or download URL, even there are several connections. The 
limit condition could be defined by the following directive.

The limit_traffic_rate module need to use a share memory pool. Directive 
syntax is same to limit_zone. 

    http {
        #limit_traffic_rate_zone   rate $request_uri 32m;
        limit_traffic_rate_zone   rate $remote_addr 32m;
        
        server {
            location /download/ {
                limit_traffic_rate  rate 20k;
            }
        }
    }

limit_traffic_rate can be used in http, server and location context. A
setting at an outer level is inherited by inner levels that do not set it
themselves; a location-level setting overrides the server/http one.

Several limit_traffic_rate directives using different zones may be given in
the same block. A request is then accounted in every zone and the lowest of
the computed rates is applied. For example, to limit each client IP to 100k
and the whole virtual server to 10m at the same time:

    http {
        limit_traffic_rate_zone   perip  $binary_remote_addr 32m;
        limit_traffic_rate_zone   global $server_name 1m;

        server {
            server_name  example.com;

            location /download/ {
                limit_traffic_rate  perip  100k;
                limit_traffic_rate  global 10m;
            }
        }
    }

Requests for which the zone variable is empty are not limited by that zone
(in the example above server_name must be set). Using the same zone twice in
one block is an error. The directives are inherited from the previous level
only if there are no limit_traffic_rate directives on the current level.

If the core limit_rate directive, the $limit_rate variable or the
X-Accel-Limit-Rate header sets a lower rate for a request, the lower rate
is used, i.e. the effective rate is the lowest of the rates of all zones and
the core limit; the core limit is not counted per zone.

How the total rate is enforced (in each zone, when several are used):

  * All bytes sent for a variable value are counted, including those of
    requests that have already finished, so the limit also applies to
    many short responses, whether they are sent in parallel or one after
    another.
  * The bandwidth is shared between the active requests. If more than
    rate * seconds bytes have been sent, requests are slowed down until
    the total is within the limit again.
  * At most 1 second of unused bandwidth is saved up, so a burst after an
    idle period is limited to about "rate" bytes (plus the data in flight).
  * The rate is measured in whole seconds and enforced through the nginx
    write filter, so the rate over a short interval can be higher; over
    several seconds it stays close to the limit.
  * After the last request for a value finishes, its state is kept while
    it is still needed (the bytes sent are over the limit, or less than 1
    second of bandwidth is unused). Such idle states are freed when they
    are no longer needed, or, if the zone is full, oldest first. So a zone
    that is too small makes the limit less accurate for idle clients.
  * The first limit_rate_after bytes of each response are neither limited
    nor counted.
    So responses smaller than limit_rate_after are never counted toward
    the total.

Tested with nginx 1.28.0.

Examples
=====

The rate given to limit_traffic_rate is shared by all connections whose
zone key ($binary_remote_addr, $request_uri, $host, ...) has the same value.
It is a total, not a per-connection limit: with "limit_traffic_rate rate 4m"
one connection may get 4MB/s, while 8 connections from the same client get
about 512KB/s each.

Note: older versions of this module ignore limit_traffic_rate at
http{}/server{} level; with those, set it inside location{}.

1. Limit each client IP to at most 8 connections and 4MB/s in total, e.g.
   for multi-thread download managers. limit_conn is the standard nginx
   module; the 9th connection is rejected with 503.

    http {
        limit_conn_zone           $binary_remote_addr zone=addr:10m;
        limit_traffic_rate_zone   rate $binary_remote_addr 32m;

        server {
            location /download/ {
                limit_conn          addr 8;
                limit_traffic_rate  rate 4m;
            }
        }
    }

2. Limit the total download rate of each URI (all clients together), or of
   each virtual host. $uri is used rather than $request_uri, which includes
   the query string, so "?x" can not be added to get a new limit.

    http {
        limit_traffic_rate_zone   per_uri  $uri 32m;
        limit_traffic_rate_zone   per_host $host 32m;

        server {
            location /video/ {
                limit_traffic_rate  per_uri 1m;
            }
            location /files/ {
                limit_traffic_rate  per_host 10m;
            }
        }
    }

Tests
=====

The test suite (Test::Nginx) is in t/; see t/README for how to run it. CI runs
it against several nginx versions.

Changelogs
  v0.2 
    *   modify algorithm, rate = (limit - last_rate)/conn + last_rate
  v0.1
    *   first release

License
=====

Same as nginx:

/* 
 * Copyright (C) 2010 Simon([email protected])
 *
 * 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.
 */