limit-conn

Limits concurrent connections per key.

Category TrafficAdd it to Stream routeEngine plugin limit-connPriority 1003

What it does

limit-conn caps how many connections from one key are open at once on a stream route. The ceiling is Conn, and Burst is how many more are made to wait instead of being refused. The key tells clients apart, for example remote_addr. A waiting connection is held for Default connection delay and then let through.

When to use it

• A database behind the gateway that accepts a fixed number of connections, where one client could otherwise take them all.
• MQTT devices that reconnect in a loop after an error, each held to a few open connections by its own address.
• A ceiling for each port the gateway listens on, with Key at server_port.
• One ceiling per client address and another per listening address and port, under Rules, with keys like $remote_addr and ${server_addr}:$server_port.

Not for requests in flight on an HTTP route — see limit-conn (Limits concurrent connections per key) or keeping clients of other networks out altogether — see ip-restriction (Allows or denies connections by client IP address or CIDR range).

Set it up

Allow 100 open connections from each client address and let 20 more wait

Set Conn to 100, set Burst to 20, set Default connection delay to 0.5 seconds and set Key to remote_addr.

limit-conn · as the console saves it

{
  "conn": 100,
  "burst": 20,
  "default_conn_delay": 0.5,
  "key": "remote_addr"
}

Things to know

• Conn — A ceiling of 0 is refused when you save.
• Conn — The ceiling is a whole number: 1.5 is refused when you save.
• Default connection delay — A delay of 0 is refused when you save.
• Only use default delay — A stream connection reports no latency, so every waiting connection is held for the default delay whether this is on or off.
• Key — With Key type at one variable, the name is written without a dollar sign, remote_addr. A combination writes each name with one, $remote_addr $server_port.
• Key — A name no stream connection carries, or a combination in which no $name resolves, is stored without complaint and every connection is then counted by client address.
• Rules — On a stream route Conn, Burst and Key stay required beside these entries, though only the entries are counted.
• Key — An entry whose key expands no variable is dropped. A connection whose every entry was dropped is not let through unless Allow degradation is on.
• Allow degradation — Off, every connection the limiter cannot count is closed, for instance when no entry's key resolves; on, each of them passes unlimited.
• AdviceSet Conn above the number of connections one well-behaved client keeps open at its busiest, and leave Burst for the reconnects that follow a restart.

Settings

The fields as the console shows them, section by section.

ConnconnintegerRequired

How many connections may be open at once.

over 0

BurstburstintegerRequired

How many connections beyond Conn are made to wait instead of being refused. Zero is a value.

at least 0

Default connection delaydefault_conn_delaynumberRequired

How long a waiting connection is held before it is let through.

over 0 · in seconds

KeykeystringRequired

The variable that tells callers apart, such as remote_addr; with Key type var combination, a template such as $remote_addr $server_port. A dollar sign under Variable, or none under Variable combination, is a name no connection carries. Not read when Rules carries entries.

example remote_addr

Key typekey_typestringdefault var

Whether Key is one variable name or a template of several. Not read when Rules carries entries.

one of var, var_combination

Only use default delayonly_use_default_delaybooleandefault false

Allow degradationallow_degradationbooleandefault false

Let connections through when the limit cannot be counted, rather than answering 500.

Rulesrulesarray of objects

One limit per entry, each with its own key. When it carries entries, Conn, Burst, Key and Key type are not read.

Each item:

Burstrules[].burstinteger or stringRequired

How many connections beyond Conn this entry lets wait instead of refusing. Zero is a value.

integer at least 0

Connrules[].conninteger or stringRequired

How many connections this entry allows at once.

integer over 0

Keyrules[].keystringRequired

A template holding at least one $variable, expanded on every connection. An entry whose key expands no variable is dropped, and a connection whose every entry was dropped is refused unless Allow degradation is on.

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.