HAProxy config tutorials

Session persistence

Session persistence means that the load balancer routes a client to the same backend server once they have been routed to that server once. It avoids the overhead of re-establishing a client’s state on a new server with each request, since the same server is always chosen. Often, it is optimal to avoid session persistence altogether by building your services to be stateless, such as by storing state off of the application servers in a shared database. However, for certain applications this is not possible.

Support for two forms of session persistence exists:

  • Persistence based on an HTTP cookie. This option is only available when mode http is set in the backend.
  • Persistence based on the client’s IP address. This option is available with both mode http and mode tcp.

To enable session persistence based on an HTTP cookie:

  • Add the cookie directive to your backend section. It instructs the load balancer to place a cookie in the client’s browser, which it will use to remember which server the client was routed to before.

  • Also, place a cookie argument on each server line. This sets the value that will be stored in the cookie and it should be unique for each server.

haproxy
backend servers
mode http
cookie SERVER_USED insert indirect nocache
server s1 192.168.0.10:80 check cookie s1
server s2 192.168.0.11:80 check cookie s2
haproxy
backend servers
mode http
cookie SERVER_USED insert indirect nocache
server s1 192.168.0.10:80 check cookie s1
server s2 192.168.0.11:80 check cookie s2

Instead of specifying cookie values explicitly via the cookie argument on a server line, you can configure the backend to dynamically generate cookie values. The value of the cookie will be the hash of the server’s IP address, port, and a secret key you provide.

To enable dynamic generation of server cookies, use the cookie directive’s dynamic argument. Specify the dynamic cookie key using the dynamic-cookie-key directive.

haproxy
backend servers
mode http
cookie SERVER_USED insert indirect nocache dynamic
dynamic-cookie-key secretphrase123
server s1 192.168.0.10:80 check
server s2 192.168.0.11:80 check
haproxy
backend servers
mode http
cookie SERVER_USED insert indirect nocache dynamic
dynamic-cookie-key secretphrase123
server s1 192.168.0.10:80 check
server s2 192.168.0.11:80 check

If you set the cookie argument on the server line, this cookie value will take precedence over the dynamic cookie value.

IP-based persistence Jump to heading

To enable session persistence based on the client’s IP address:

  • Add a stick-table line to your backend section. It creates an in-memory storage to hold client IP addresses. Entries in the stick table expire after 30 minutes if not used.
  • Add the line stick on src, which stores a client’s IP address in the stick table and associates it with the server to which they were routed. On subsequent visits, they will use this same server.
haproxy
backend servers
mode tcp
stick-table type ip size 1m expire 30m
stick on src
server s1 192.168.0.10:80 check
server s2 192.168.0.11:80 check
haproxy
backend servers
mode tcp
stick-table type ip size 1m expire 30m
stick on src
server s1 192.168.0.10:80 check
server s2 192.168.0.11:80 check

IP-based persistence can be less precise than cookie-based persistence because multiple clients may originate from the same IP address. The only side effect of this is persisting more clients to the same server.

Info

If you are using Global Profiling Engine, please see the guide GPE with session persistence for instructions.

See also Jump to heading

Do you have any suggestions on how we can improve the content of this page?