Load balance UDP with the LB Layer7 tab

You can load balance UDP (User Datagram Protocol) by using HAProxy ALOHA’s UDP module.

What is UDP? Jump to heading #

Applications employ UDP when they need a fire-and-forget transport of messages over a network, with minimal overhead. Because UDP lacks the message delivery guarantees that TCP has, it can be ideal for some situations but not others. For example, when sending syslog messages over a network, you might prefer TCP if you require delivery of all messages. Or you might choose UDP if it’s acceptable to lose some messages, but allow the sender to continue sending messages without waiting for confirmation they’ve been received. Under some network conditions, such as where there’s significant packet loss, UDP can have better throughput. But it can perform worse in congested networks, since it lacks TCP’s congestion control.

How does the UDP module work? Jump to heading #

The UDP module adds support for a new section in your LB Layer7 configuration called udp-lb. The udp-lb section defines the IP address and UDP port at which to accept datagrams. Also in this section, you’ll define the backend servers to load balance datagrams across. The module supports health checking servers and logging traffic too.

Installation Jump to heading #

To install the UDP module on HAProxy ALOHA:

1. On the LB Layer7 tab, add the module-load directive to the global section. Add the global section if it doesn’t exist.

   haproxy
   global
     ...
     module-load hapee-lb-udp.so

   haproxy
   global
     ...
     module-load hapee-lb-udp.so

2. Add one or more udp-lb sections to configure listening UDP ports and backend servers. See Examples.

Enable logging Jump to heading #

You can enable logging of UDP traffic through the load balancer. HAProxy ALOHA will log a message each time it receives a request datagram and forwards it to the backend server, or when the response datagram is sent back to the client. The log output format contains the source and destination addresses, bytes received or sent, the instance name, and the server if available.

1. Add the log global directive to your udp-lb section to send log messages to the syslog server declared in the global section:

   haproxy
   global
     maxconn            10000
     log                127.0.0.1 local0
     log                127.0.0.1 local1 notice
     ...
   udp-lb dns
     dgram-bind 192.168.56.25:53
     log global
     proxy-requests 1
     balance roundrobin
     option udp-check
     server dns1 10.10.10.10:53 check
     server dns2 10.10.10.20:53 check

   haproxy
   global
     maxconn            10000
     log                127.0.0.1 local0
     log                127.0.0.1 local1 notice
     ...
   udp-lb dns
     dgram-bind 192.168.56.25:53
     log global
     proxy-requests 1
     balance roundrobin
     option udp-check
     server dns1 10.10.10.10:53 check
     server dns2 10.10.10.20:53 check

   Example log messages:

   log
   Nov  7 20:40:54 hapee hapee-lb[1254]: UDP: request received (58 bytes) from 192.168.56.1:50806 to 192.168.56.25:53 (dns/dns2)
   Nov  7 20:40:54 hapee hapee-lb[1254]: UDP: response sent (181 bytes) from 192.168.56.25:53 to 192.168.56.1:50806 (dns/dns2)

   log
   Nov  7 20:40:54 hapee hapee-lb[1254]: UDP: request received (58 bytes) from 192.168.56.1:50806 to 192.168.56.25:53 (dns/dns2)
   Nov  7 20:40:54 hapee hapee-lb[1254]: UDP: response sent (181 bytes) from 192.168.56.25:53 to 192.168.56.1:50806 (dns/dns2)

   Alternatively, you can define a log directive directly in the udp-lb section to set target syslog servers, facility code, and severity level there. For details, see log reference.

2. Optional: Set log-tag to indicate in the logs which load balancer server proxied the traffic. On the rsyslog side, this sets the $programname variable. It defaults to haproxy.

   haproxy
   udp-lb dns
     dgram-bind 192.168.56.25:53
     log global
     log-tag aloha1
     proxy-requests 1
     balance roundrobin
     option udp-check
     server dns1 10.10.10.10:53 check
     server dns2 10.10.10.20:53 check

   haproxy
   udp-lb dns
     dgram-bind 192.168.56.25:53
     log global
     log-tag aloha1
     proxy-requests 1
     balance roundrobin
     option udp-check
     server dns1 10.10.10.10:53 check
     server dns2 10.10.10.20:53 check

   Example log messages on the Logs tab traffic logs:

   log
   Feb 28 17:14:06 ALOHA1 local0.info aloha1[6149]: UDP: request received (58 bytes) from 192.168.56.1:55604 to 192.168.56.45:53 (udp-dns/dns1) 
   Feb 28 17:14:06 ALOHA1 local0.info aloha1[6149]: UDP: response sent (181 bytes) from 192.168.56.45:53 to 192.168.56.1:55604 (udp-dns/dns1)

   log
   Feb 28 17:14:06 ALOHA1 local0.info aloha1[6149]: UDP: request received (58 bytes) from 192.168.56.1:55604 to 192.168.56.45:53 (udp-dns/dns1) 
   Feb 28 17:14:06 ALOHA1 local0.info aloha1[6149]: UDP: response sent (181 bytes) from 192.168.56.45:53 to 192.168.56.1:55604 (udp-dns/dns1)

Examples Jump to heading #

In this section, you’ll see examples of using the UDP module to load balance different types of applications. This will give you an understanding of the syntax, in case you want to load balance an application not shown here.

Load balance syslog Jump to heading #

You can use the UDP module to load balance syslog traffic. The UDP module listens on the configured port and will load balance incoming messages to the list of configured servers. Consider the example configuration below:

haproxy
udp-lb syslog-example
  dgram-bind 192.168.56.25:3516
  proxy-requests 1
  proxy-responses 0
  balance roundrobin
  option udp-check
  server srv1 10.10.10.10:1514 check
  server srv2 10.10.10.20:1514 check
  server srv3 10.10.10.30:1514 check

haproxy
udp-lb syslog-example
  dgram-bind 192.168.56.25:3516
  proxy-requests 1
  proxy-responses 0
  balance roundrobin
  option udp-check
  server srv1 10.10.10.10:1514 check
  server srv2 10.10.10.20:1514 check
  server srv3 10.10.10.30:1514 check

• We declare a UDP section using the udp-lb directive and name it syslog-example.
• We specify a dgram-bind on localhost port 3516. This is where we expect to receive the UDP syslog traffic.

  Listen port

  Use caution when specifying a port for listening for syslog messages. The default rsyslog configuration for HAProxy Enterprise listens for traffic on localhost port 514. If you try to specify the same interface and port, the load balancer will be unable to bind on that interface and will receive no messages.

• We set proxy-requests to 1. This specifies that the load balancer should load balance on each datagram it receives, since each syslog message will fit into a single datagram.
• We set proxy-responses to 0. This specifies that the load balancer shouldn’t expect a response from the server.
• We set the load balancing algorithm to roundrobin.
• We enable health checks over ICMP with option udp-check. Be sure to enable ICMP traffic in your network to allow this behavior.
  • Note that you could also enable health checks over TCP using option tcp-check.
• We list three servers that will receive the load balanced syslog traffic. These servers have been configured via rsyslog to expect UDP log traffic on port 1514.

Note that for the best performance for load balancing syslog, it’s recommended that proxy-requests is set to 1 and proxy-responses is set to 0.

Load balance DNS Jump to heading #

You can use the UDP module to load balance DNS traffic over UDP. However, in cases where the DNS response may be larger than one datagram, it’s better to load balance DNS over TCP because TCP supports larger responses. This scenario may occur with DNS-based service discovery. In most cases, a DNS request fits within one datagram, and UDP is sufficient.

Consider the example configuration below:

haproxy
udp-lb udp-dns
  dgram-bind 192.168.56.25:53
  proxy-requests 1
  balance roundrobin
  option udp-check
  server dns1 10.10.10.10:53 check
  server dns2 10.10.10.20:53 check
frontend tcp-dns
  mode tcp
  bind 192.168.56.25:53
  default_backend tcp-dns-backend
backend tcp-dns-backend
  mode tcp
  balance roundrobin
  server srv1 10.10.10.10:53 check
  server srv2 10.10.10.20:53 check
  server srv3 10.10.10.30:53 check

haproxy
udp-lb udp-dns
  dgram-bind 192.168.56.25:53
  proxy-requests 1
  balance roundrobin
  option udp-check
  server dns1 10.10.10.10:53 check
  server dns2 10.10.10.20:53 check
frontend tcp-dns
  mode tcp
  bind 192.168.56.25:53
  default_backend tcp-dns-backend
backend tcp-dns-backend
  mode tcp
  balance roundrobin
  server srv1 10.10.10.10:53 check
  server srv2 10.10.10.20:53 check
  server srv3 10.10.10.30:53 check

• UDP
  • We declare a UDP section using the udp-lb directive and name it udp-dns.
  • We specify a dgram-bind on 192.168.56.25:53.
  • We set proxy-requests to 1. This specifies that the load balancer should load balance on each datagram it receives, since each DNS request will fit into a single datagram.

    proxy-responses

    Unlike our other examples which explicitly set a value for proxy-responses, in the case for DNS, we leave this option unset. By leaving it unset, this specifies that the load balancer should expect an unlimited number of responses from the DNS server. It will forward all responses back to the client.

  • We set the load balancing algorithm to roundrobin.
  • We enable health checks over ICMP with option udp-check. Be sure to enable ICMP traffic in your network to allow this behavior.
    • Note that you could also enable health checks over TCP using option tcp-check.
  • We list two servers that will receive and provide responses for the load-balanced DNS requests.
• TCP
  • We define a frontend named tcp-dns and a backend named tcp-dns-backend. This frontend and backend will load balance DNS traffic over TCP.
  • We enable TCP healthchecks using check.
  • We list three servers that will receive and provide responses for the load-balanced DNS requests.

For more information, see DNS service discovery.

haproxy
udp-lb udp-dns
  dgram-bind 192.168.56.25:53
  proxy-requests 1
  balance roundrobin
  option udp-check
  server dns1 10.10.10.10 check
  server dns2 10.10.10.20 check

haproxy
udp-lb udp-dns
  dgram-bind 192.168.56.25:53
  proxy-requests 1
  balance roundrobin
  option udp-check
  server dns1 10.10.10.10 check
  server dns2 10.10.10.20 check

Load balance NTP Jump to heading #

You can use the UDP module to load balance NTP traffic. The UDP module listens on the configured port and will load balance incoming NTP requests to the list of configured NTP servers. It will then return the response to the appropriate client.

Consider the example configuration below:

haproxy
udp-lb ntp
  dgram-bind 192.168.56.25:123
  proxy-requests 1
  proxy-responses 1
  balance roundrobin
  option udp-check
  server srv1 10.10.10.10:123 check
  server srv2 10.10.10.20:123 check
  server srv2 10.10.10.30:123 check

haproxy
udp-lb ntp
  dgram-bind 192.168.56.25:123
  proxy-requests 1
  proxy-responses 1
  balance roundrobin
  option udp-check
  server srv1 10.10.10.10:123 check
  server srv2 10.10.10.20:123 check
  server srv2 10.10.10.30:123 check

• We declare a UDP section using the udp-lb directive and name it ntp.
• We specify a dgram-bind on all interfaces on port 123. This is the standard NTP port where we expect to receive NTP requests.

  NTP servers

  UDP Port 123 is the standard port for NTP and most implementations don’t allow you to change it. As such, your load balancer and NTP server(s) should not be the same server. The load balancer must bind on port 123 to load balance the NTP requests, which it would be unable to do if the server it runs on is also running as an NTP server (and therefore is already using UDP port 123).

• We set proxy-requests to 1. This specifies that the load balancer should load balance on each datagram it receives, since each NTP request will fit into a single datagram.
• We set proxy-responses to 1. This specifies that the load balancer should expect one response from the NTP server. It will then relay the response back to the client.
• We set the load balancing algorithm to roundrobin.
• We enable health checks over ICMP with option udp-check. Be sure to enable ICMP traffic in your network to allow this behavior.
  • Note that you could also enable health checks over TCP using option tcp-check.
• We list three servers that will receive the load balanced NTP traffic. These servers have been configured as NTP servers and will respond to requests on the standard UDP NTP port 123.

haproxy
udp-lb ntp
  dgram-bind 192.168.56.25:123
  proxy-requests 1
  proxy-responses 1
  balance roundrobin
  option udp-check
  server srv1 10.10.10.10 check
  server srv2 10.10.10.20 check
  server srv2 10.10.10.30 check

haproxy
udp-lb ntp
  dgram-bind 192.168.56.25:123
  proxy-requests 1
  proxy-responses 1
  balance roundrobin
  option udp-check
  server srv1 10.10.10.10 check
  server srv2 10.10.10.20 check
  server srv2 10.10.10.30 check

Load balance RADIUS Jump to heading #

You can use the UDP module to load balance RADIUS authentication traffic. The UDP module listens on the configured ports and will load balance incoming requests to the list of configured RADIUS servers. It will then return the responses to the appropriate client.

Consider the example configuration below where the load balancer is configured to route traffic to both RADIUS authentication (1812) and accounting (1813) ports:

haproxy
udp-lb radius-auth
  dgram-bind 192.168.56.25:1812
  balance source
  server srv1 10.10.10.10:1812
  server srv2 10.10.10.20:1812
  server srv3 10.10.10.30:1812
udp-lb radius-accounting
  dgram-bind 192.168.56.25:1813
  balance source
  server srv1 10.10.10.10:1813
  server srv2 10.10.10.20:1813
  server srv3 10.10.10.30:1813

haproxy
udp-lb radius-auth
  dgram-bind 192.168.56.25:1812
  balance source
  server srv1 10.10.10.10:1812
  server srv2 10.10.10.20:1812
  server srv3 10.10.10.30:1812
udp-lb radius-accounting
  dgram-bind 192.168.56.25:1813
  balance source
  server srv1 10.10.10.10:1813
  server srv2 10.10.10.20:1813
  server srv3 10.10.10.30:1813

• We declare two UDP sections using the udp-lb directive and name them radius-auth and radius-accounting.
• We specify a dgram-bind on all interfaces on port 1812 for radius-auth and port 1813 for radius-accounting.
  • Ensure that the ports you specify match the ports defined in your RADIUS configuration (1812 and 1813 are the RADIUS defaults).
• We set the load balancing algorithm to source. This is required so that requests from the same client are routed to the same server.
• We don’t set proxy-requests. There will be multiple requests from the client, and we want all requests from the same client to be routed to the same server. This applies regardless of any timeout value specified since we have also set balance to source.
• We don’t set proxy-responses. There will be multiple responses from the RADIUS server.
• We list three servers that will receive the load balanced RADIUS traffic. These servers have been configured as RADIUS servers and will respond to requests on the default RADIUS ports 1812 and 1813.

haproxy
udp-lb radius
  dgram-bind 192.168.56.25:1812
  dgram-bind 192.168.56.25:1813
  balance source
  server srv1 10.10.10.10
  server srv2 10.10.10.20
  server srv3 10.10.10.30

haproxy
udp-lb radius
  dgram-bind 192.168.56.25:1812
  dgram-bind 192.168.56.25:1813
  balance source
  server srv1 10.10.10.10
  server srv2 10.10.10.20
  server srv3 10.10.10.30

Reference Jump to heading #

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>