Load balance UDP with HAProxy Enterprise

You can use the UDP module to load balance syslog, DNS, and NTP traffic. Configuring the UDP module is similar to configuring a listen section, allowing you to specify an interface for receiving incoming traffic as well as a list of servers for load balancing traffic, all in one section. The UDP module does not transform the messages it receives.

Note that at this time, the UDP module does not log its traffic.

Install the UDP module Jump to heading #

1. Install the UDP module according to your platform:

   apt yum zypper pkg

   nix
   sudo apt-get install hapee-2.9r1-lb-udp

   nix
   sudo apt-get install hapee-2.9r1-lb-udp

   nix
   sudo yum install hapee-2.9r1-lb-udp

   nix
   sudo yum install hapee-2.9r1-lb-udp

   nix
   sudo zypper install hapee-2.9r1-lb-udp

   nix
   sudo zypper install hapee-2.9r1-lb-udp

   nix
   sudo pkg install hapee-2.9r1-lb-udp

   nix
   sudo pkg install hapee-2.9r1-lb-udp

2. In the global section of your configuration file, add a module-load directive to load the UDP module:

   haproxy
   global
     module-path /opt/hapee-2.9/modules
     module-load hapee-lb-udp.so

   haproxy
   global
     module-path /opt/hapee-2.9/modules
     module-load hapee-lb-udp.so

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 keyword udp-lb 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 should not 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 is recommended that proxy-requests is set to 1 and proxy-responses is set to 0.

haproxy
udp-lb myudp1
  dgram-bind 192.168.56.25:3516 shards 48 by-thread

haproxy
udp-lb myudp1
  dgram-bind 192.168.56.25:3516 shards 48 by-thread

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 is better to load balance DNS over TCP because TCP supports larger responses. This scenario may occur with DNS-based service discovery. In most cases, though, 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 keyword udp-lb 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.

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 keyword udp-lb 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 do not 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 on which it runs 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.

proxy-requests and proxy-responses should both be set to 1, as there is one response expected for every NTP request.

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 keyword udp-lb 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 that requests from the same client are routed to the same server.
• We do not 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 do not 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.

Reference Jump to heading #

The UDP module uses the following directives for configuration:

dgram-bind Jump to heading #

Syntax:

text
dgram-bind <addr> [param*]

text
dgram-bind <addr> [param*]

Configures a datagram listener to receive messages to forward. Addresses must be in IPv4 or IPv6 form, optionally followed by a port. dgram-bind supports these bind parameters:

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

maxconn Jump to heading #

Syntax:

text
maxconn <maxconn>

text
maxconn <maxconn>

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

accepted-payload-size Jump to heading #

Syntax:

text
accepted-payload-size <number>

text
accepted-payload-size <number>

Maximum UDP datagram payload size (in bytes). The default is 1472. The maximum allowed is 65507.

server Jump to heading #

Syntax:

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

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

Configures a target server.

timeout client Jump to heading #

Syntax:

text
timeout client <timeout>

text
timeout client <timeout>

Maximum inactivity time on the client side.

timeout server Jump to heading #

Syntax:

text
timeout server <timeout>

text
timeout server <timeout>

Maximum inactivity time on the server side.

proxy-requests Jump to heading #

Syntax:

text
proxy-requests <number>

text
proxy-requests <number>

The number of expected datagrams per client session. Since UDP is not 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 is not 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 proxy-requests 1 then a destination server will be rotated after each datagram received from the client.

proxy-responses Jump to heading #

Syntax:

text
proxy-responses <number>

text
proxy-responses <number>

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 zero value is specified, all responses from the server will be ignored and not forwarded back to the client. If a value is not specified, the number of expected responses is set to unlimited.

balance Jump to heading #

Syntax:

text
balance <algorithm>`

text
balance <algorithm>`

The load balancing algorithm. The UDP module supports the following:

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

option udp-check Jump to heading #

Syntax:

text
option udp-check

text
option udp-check

Perform health checks via ICMP.

option tcp-check Jump to heading #

Syntax:

text
option tcp-check

text
option tcp-check

Perform health checks using TCP connection attempts.

tcp-check Jump to heading #

Syntax:

text
tcp-check <option> [param*]

text
tcp-check <option> [param*]

Configure TCP health check using supported options:

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

source Jump to heading #

Syntax for setting source address:

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

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

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 interface name:

text
source <addr>[:<port>] [interface <name>]

text
source <addr>[:<port>] [interface <name>]

Sets the interface <name> for binding on outgoing connections.

See also Jump to heading #

• DNS service discovery
• shards reference