UDP load balancing reference

The UDP module uses the following directives for configuration.

accepted-payload-size Jump to heading #

Sets the maximum UDP datagram payload size in bytes. The default value is 1472, and the maximum value allowed is 65507.

Syntax
text
accepted-payload-size <number>

Syntax
text
accepted-payload-size <number>

acl Jump to heading #

Configure an ACL (Access Control List). See ACLs for more implementation details.

Syntax
text
acl <name> <criterion> [<ACL flags>] [<operator>] <value>

Syntax
text
acl <name> <criterion> [<ACL flags>] [<operator>] <value>

balance Jump to heading #

Sets the load balancing algorithm.

Syntax
text
balance <algorithm>

Syntax
text
balance <algorithm>

The UDP module supports the following algorithms for balance:

• static-rr
• roundrobin
• leastconn
• first
• source
• random

default-server Jump to heading #

Sets default parameters that will apply to all server lines within the same section. For a list of supported parameters, see default-server options.

Syntax
text
default-server [param*]

Syntax
text
default-server [param*]

dgram-bind Jump to heading #

Configures a datagram listener to receive messages to forward. Addresses must be in IPv4 or IPv6 form, optionally followed by a port.

Syntax
text
dgram-bind <addr> [param*]

Syntax
text
dgram-bind <addr> [param*]

The dgram-bind directive supports these bind parameters:

• maxconn
• namespace
• nice
• shards
• thread
• transparent

hash-balance-factor Jump to heading #

Specifies the balancing factor for bounded-load consistent hashing. See hash-balance-factor for more details.

Syntax
text
hash-balance-factor <factor>

Syntax
text
hash-balance-factor <factor>

hash-type Jump to heading #

Specifies a method to use for mapping hashes to servers. See hash-type for more details.

Syntax
text
hash-type <method> <function> <modifier>

Syntax
text
hash-type <method> <function> <modifier>

log Jump to heading #

Enables per-instance logging of events. For requests, the source is the client’s IP/port, and the destination is the listener’s IP/port. For responses, the source is the listener, and the destination is the client.

For details, see log reference.

Syntax
text
log <target> [len <length>] [format <format>] [sample <ranges>:<sample_size>] <facility> [<level> [<minlevel>]]

Syntax
text
log <target> [len <length>] [format <format>] [sample <ranges>:<sample_size>] <facility> [<level> [<minlevel>]]

log global Jump to heading #

Sets the instance’s logging parameters to be the same as the global ones.

Syntax
text
log global

Syntax
text
log global

log-tag Jump to heading #

Sets the log tag string to use for all outgoing logs.

Syntax
text
log-tag <string>

Syntax
text
log-tag <string>

maxconn Jump to heading #

Sets the maximum number of concurrent connections. Once the limit is reached, all datagrams received initiating new UDP connection will be dropped.

Syntax
text
maxconn <integer>

Syntax
text
maxconn <integer>

option persist Jump to heading #

Enables forced persistence on downed servers by forcing the datagram to be sent to the downed server(s) first.

Syntax
text
option persist

Syntax
text
option persist

option tcp-check Jump to heading #

Performs health checks using TCP connection attempts.

Syntax
text
option tcp-check

Syntax
text
option tcp-check

option udp-check Jump to heading #

Performs health checks via ICMP.

Syntax
text
option udp-check

Syntax
text
option udp-check

proxy-requests Jump to heading #

Sets the number of expected datagrams per client session. Since UDP isn’t a connection-oriented protocol, the UDP module must keep track of a client’s session such that it can route the response datagrams from an upstream server back to the correct client. Each session is indexed by the 4-tuple consisting of source IP/port and destination IP/port corresponding to the datagram.

• If this option isn’t set, then the load balancer will forward all datagrams from the client to the same backend server as long as the client is considered alive. If the client becomes inactive, their session expires, and the next time they send a datagram, the load balancer will again choose a server based on the load balancing algorithm.

• If this option is set to a value greater than 0, then session stickiness is disabled and the load balancer will choose the backend server on every <number> datagrams received. For example, if set to proxy-requests 1, then a destination server will be rotated after each datagram received from the client.

Syntax
text
proxy-requests <number>

Syntax
text
proxy-requests <number>

proxy-responses Jump to heading #

Sets the number of expected responses from the server. Sessions last until the timeout is reached or the expected number of responses has been received. If a zero value is specified, all responses from the server will be ignored and not forwarded back to the client. If a value isn’t specified, the number of expected responses is set to unlimited.

Syntax
text
proxy-responses <number>

Syntax
text
proxy-responses <number>

server Jump to heading #

Configures a target server.

Syntax
text
server <name> <address>[:[port]] [param*]

Syntax
text
server <name> <address>[:[port]] [param*]

source Jump to heading #

Sets the source address for outgoing connections. The <addr> and optional <port> will be used for binding before connecting to the server. The <addr2> and <port2> are presented to the server when connections are forwarded in full transparent proxy mode. If client or clientip is set, the load balancer will present the client’s IP address and port, or the client’s IP address only.

Syntax for setting source address
text
source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]

Syntax for setting source address
text
source <addr>[:<port>] [usesrc { <addr2>[:<port2>] | client | clientip } ]

Syntax for setting interface name
text
source <addr>[:<port>] [interface <name>]

Syntax for setting interface name
text
source <addr>[:<port>] [interface <name>]

tcp-check Jump to heading #

Configures TCP health checking.

Syntax
text
tcp-check <option> [param*]

Syntax
text
tcp-check <option> [param*]

Supported options are:

• comment
• connect
• send
• send-lf
• send-binary
• send-binary-lf
• expect
• set-var
• set-var-fmt
• unset-var

timeout client Jump to heading #

Sets the maximum inactivity time on the client side. The default is 10 seconds, but the ideal setting depends on your traffic and application. For example, if you have a large amount of traffic and a large number of client IP addresses and ports, you can lower the value in order to avoid tracking a high number of connections unnecessarily.

Syntax
text
timeout client <timeout>

Syntax
text
timeout client <timeout>

timeout server Jump to heading #

Sets the maximum inactivity time on the server side.

Syntax
text
timeout server <timeout>

Syntax
text
timeout server <timeout>

use-server Jump to heading #

Assign a specified server if/unless a condition is matched. For example, use a target UDP server based on the source IP.

If there is more than one use-server directive configured, they are evaluated in their declaration order. The first use-server directive that matches a condition will assign the specified server, unless the current session has already assigned that server. If no condition is valid, the unassigned servers will use other load balancing mechanisms.

When <server> is a simple name, the load balancer is checks it against existing servers in the configuration and reports an error if the specified server doesn’t exist. If <server> is in a custom log format, no check is performed when parsing the configuration. If the load balancer can’t resolve a valid server name at runtime, but a use-server was condition was met, no other use-server directive is applied, and the load balancer will fall back to load balancing.

Syntax
text
use-server <server> { if | unless } <condition>

Syntax
text
use-server <server> { if | unless } <condition>