WIXLIB

Now you have a sample from converters and fetches, such asthe requested URL path via path , and something to matchagainst via the hardcoded path /evil . To compare the formerto the latter you can use one of several matching methods. Asbefore, there are a lot of matching methods and you can seethe full list by scrolling down (further than the flags) in theACL Basics section of the documentation. Here are somecommonly used matching methods:strPerform an exact string matchbegCheck the beginning of the string with the pattern,so a sample of “foobar” will match a pattern of “foo”but not “bar”.endCheck the end of a string with the pattern, so asample of foobar will match a pattern of bar butnot foo.subA substring match, so a sample of foobar will matchpatterns foo, bar, oba.regThe pattern is compared as a regular expressionagainst the sample. Warning: This is CPU hungrycompared to the other matching methods and shouldbe avoided unless there is no other choice.foundThis is a match that doesn’t take a pattern at all. Thematch is true if the sample is found, false otherwise.This can be used to (as a few common examples) seeif a header ( req.hdr(x-foo) -m found ) is present, ifa cookie is set ( cook(foo) -m found ), or if a sampleis present in a map( src,map(/etc/hapee-1.9/ip to country.map)-m found ).The HAProxy Guide to Multi-Layer Security15

lenReturn the length of the sample (so a sample of foowith -m len 3 will match)Up until this point, you may have noticed the use of path -mbeg /evil for comparing our expected path / evil with thebeginning of the sample we’re checking. It uses the matchingmethod b eg . There are a number of places where you can usea shorthand that combines a sample fetch and a matchingmethod in one argument. In this example p ath beg /foo andpath -m beg /foo are exactly the same, but the former iseasier to type and read. Not all fetches have variants withbuilt-in matching methods (in fact, most don’t), and there’s arestriction that if you chain a fetch with a converter you haveto specify it using a flag (unless the last converter on thechain has a match variant, which most don’t).If there isn’t a fetch variant of the desired matching method,or if you are using converters, you can use the m flag notedin the previous section to specify the matching method.Things to do with ACLsNow that you know how to define ACLs, let’s get a quick ideafor the common actions in HAProxy that can be controlled byACLs. This isn’t meant to give you a complete list of all theconditions or ways that these rules can be used, but ratherprovide fuel to your imagination for when you encountersomething with which ACLs can help.The HAProxy Guide to Multi-Layer Security16

Redirecting a RequestThe command h ttp-request redirect location sets theentire URI. For example, to redirect non-www domains totheir www variant you can use:http-request redirect location http://www.%[hdr(host)]%[capture.req.uri] unless { hdr beg(host) -i www }In this case, our ACL, hdr beg(host) -i www , ensures thatthe client is redirected unless their Host HTTP header alreadybegins with www.The command h ttp-request redirect scheme changesthe scheme of the request while leaving the rest alone. Thisallows for trivial HTTP-to-HTTPS redirect lines:http-request redirect scheme https if !{ ssl fc }Here, our ACL !{ ssl fc } checks whether the request didnot come in over HTTPS.The command h ttp-request redirect prefix allows youto specify a prefix to redirect the request to. For example, thefollowing line causes all requests that don’t have a URL pathbeginning with /foo to be redirected to /foo/{original URIhere} :The HAProxy Guide to Multi-Layer Security17

http-request redirect prefix /foo if !{ path beg /foo }For each of these a code argument can be added to specify aresponse code. If not specified it defaults to 302. Supportedresponse codes are 301, 302, 303, 307, and 308. Forexample:redirect scheme code 301 https if !{ ssl fc }This will redirect HTTP requests to HTTPS and tell clientsthat they shouldn’t keep trying HTTP. Or for a more secureversion of this, you could inject the Strict-Transport-Securityheader via h ttp-response set-header .Selecting a BackendIn HTTP ModeThe use backend line allows you to specify conditions forusing another backend. For example, to send trafficrequesting the HAProxy Stats webpage to a dedicatedbackend, you can combine use backend with an ACL thatchecks whether the URL path begins with / stats :use backend be stats if { path beg /stats }The HAProxy Guide to Multi-Layer Security18

Even more interesting, the backend name can be dynamicwith log-format style rules (i.e. %[ fetch method ]). In thefollowing example, we put the path through a map and usethat to generate the backend name:use backend be %[path,map beg(/etc/hapee-1.9/paths.map)]If the file paths.map contains /api api as a key-value pair,then traffic will be sent to be api , combining the prefix b ewith the string a pi . If none of the map entries match andyou’ve specified the optional second parameter to the mapfunction, which is the default argument, then that default willbe used.use backend be %[path,map beg(/etc/hapee-1.9/paths.map, mydefault)]In this case, if there isn’t a match in the map file, then thebackend be mydefault will be used. Otherwise, without adefault, traffic will automatically fall-through this rule insearch of another use backend rule that matches or thedefault backend line.In TCP ModeWe can also make routing decisions for TCP mode traffic, forexample directing traffic to a special backend if the traffic isSSL:The HAProxy Guide to Multi-Layer Security19

tcp-request inspect-delay 10suse backend be ssl if { req.ssl hello type gt 0 }Note that for TCP-level routing decisions, when requiringdata from the client such as needing to inspect the request,the inspect-delay statement is required to avoid HAProxypassing the phase by without any data from the client yet. Itwon’t wait the full 10 seconds unless the client stays silentfor 10 seconds. It will move ahead as soon as it can decidewhether the buffer has an SSL hello message.Setting an HTTPHeaderThere are a variety of options for adding an HTTP header tothe request (transparently to the client). Combining thesewith an ACL lets you only set the header if a given conditionis true.add-headerAdds a new header. If a header of thesame name was sent by the client this willignore it, adding a second header of thesame name.set-headerWill add a new header in the same way asadd-header , but if the request already hasa header of the same name it will beoverwritten. Good for security-sensitive flagsthat a client might want to tamper with.The HAProxy Guide to Multi-Layer Security20

replace-headerApplies a regex replacement of thenamed header (injecting a fake cookieinto a cookie header, for example)del-headerDeletes any header by the specifiedname from the request. Useful forremoving an x-forwarded-for headerbefore option forwardforadds a new one (or any custom headername used there).Changing the URLThis allows HAProxy to modify the path that the clientrequested, but transparently to the client. Its value acceptslog-format style rules (i.e. % [ fetch method ] ) so you canmake the requested path dynamic. For example, if youwanted to add /foo/ to all requests (as in the redirect exampleabove) without notifying the client of this, use:http-request set-path /foo%[path] if !{ path beg /foo }There is also s et-query , which changes the query stringinstead of the path, and s et-uri , which sets the path andquery string together.Updating Map FilesThese actions aren’t used very frequently, but open upinteresting possibilities in dynamically adjusting HAProxyThe HAProxy Guide to Multi-Layer Security21

maps. This can be used for tasks such as having a loginserver tell HAProxy to send a clients’ (in this case by sessioncookie) requests to another backend from then on:http-request set-var(txn.session id) cook(sessionid)use backend be %[var(txn.session id), map(/etc/hapee-1.9/sessionid.map)] if { var(txn.session id), map(/etc/hapee-1.9/sessionid.map) -m found }http-response set-map(/etc/hapee-1.9/sessionid.map) %[var(txn.session id)] %[res.hdr(x-new-backend)] if { res.hdr(x-new-backend) -m found }default backend be loginNow if a backend sets the x -new-backend header in aresponse, HAProxy will send subsequent requests with theclient’s sessionid cookie to the specified backend. Variablesare used as, otherwise, the request cookies are inaccessibleby HAProxy during the response phase—a solution you maywant to keep in mind for other similar problems that HAProxywill warn about during startup.There is also the related del-map to delete a map entry basedon an ACL condition.The HAProxy Guide to Multi-Layer Security22

Did you know? As with most actions, http-response set-maphas a related action called http-request set-map. This isuseful as a pseudo API to allow backends to add and removemap entries.CachingNew to HAProxy 1.8 is small object caching, allowing thecaching of resources based on ACLs. This, along withhttp-response cache-store , allows you to store selectrequests in HAProxy’s cache system. For example, given thatwe’ve defined a cache named icons , the following will storeresponses from paths beginning with / icons and reuse themin future requests:http-request set-var(txn.path) pathacl is icons path var(txn.path) -m beg /icons/http-request cache-use icons if is icons pathhttp-response cache-store icons if is icons pathUsing ACLs to BlockRequestsNow that you’ve familiarized yourself with ACLs, it’s time todo some request blocking!The HAProxy Guide to Multi-Layer Security23

The command h ttp-request deny returns a 403 to theclient and immediately stops processing the request. This isfrequently used for DDoS/Bot mitigation as HAProxy candeny a very large volume of requests without bothering theweb server.Other responses similar to this include http-requesttarpit (keep the request hanging until t imeout tarpitexpires, then return a 500—good for slowing down bots byoverloading their connection tables, if there aren’t too manyof them), h ttp-request silent-drop (have HAProxy stopprocessing the request but tell the kernel to not notify theclient of this – leaves the connection from a client perspectiveopen, but closed from the HAProxy perspective; be aware ofstateful firewalls).With both deny and tarpit you can add the deny status flagto set a custom response code instead of the default 403/500that they use out of the box. For example usinghttp-request deny deny status 429 will cause HAProxyto respond to the client with the error 429: Too ManyRequests.In the following subsections we will provide a number ofstatic conditions for which blocking traffic can be useful.HTTP Protocol VersionA number of attacks use HTTP 1.0 as the protocol version, soif that is the case it’s easy to block these attacks using thebuilt-in ACL H TTP 1.0 :The HAProxy Guide to Multi-Layer Security24

http-request deny if HTTP 1.0Contents of the user-agent StringWe can also inspect the User-Agent header and deny if itmatches a specified string.http-request deny if { req.hdr(user-agent) -m sub evil }This line will deny the request if the -m sub part of theuser-agent request header contains the string evil anywherein it. Remove the -m sub , leaving you withreq.hdr(user-agent) evil as the condition, and it will bean exact match instead of a substring.Length of the user-agent StringSome attackers will attempt to bypass normal user agentstrings by using a random md5sum, which can be identifiedby length and immediately blocked:http-request deny if { req.hdr(user-agent) -m len 32 }Attackers can vary more with their attacks, so you can rely onthe fact that legitimate user agents are longer while alsobeing set to a minimum length:The HAProxy Guide to Multi-Layer Security25

http-request deny if { req.hdr(user-agent) -m len le 32 }This will then block any requests which have a user-agentheader shorter than 32 characters.PathIf an attacker is abusing a specific URL that legitimate clientsdon’t, one can block based on path:http-request deny if { path /api/wastetime }Or you can prevent an attacker from accessing hidden files orfolders:http-request deny if { path -m sub /. }Updating ACL ListsUsing lb-updateACL files are updated when HAProxy is reloaded to read thenew configuration, but it is also possible to update itscontents during runtime.HAProxy Enterprise ships with a native module calledlb-update that can be used with the following configuration:The HAProxy Guide to Multi-Layer Security26

dynamic updateupdate id /etc/hapee-1.9/whitelist.acl url http://192.168.122.1/whitelist.acl delay 60sHAPEE will now update the ACL contents every 60 secondsby requesting the specified URL. Support also exists forretrieving the URL via HTTPS and using client certificateauthentication.Using the Runtime APITo update the configuration during runtime, simply use theRuntime API to issue commands such as the .2.3.4" socat stdio /var/run/hapee-lb.sockConclusionThat’s all folks! We have provided you with some examples toshow the power within the HAProxy ACL system. The abovelist isn’t exhaustive or anywhere near complete, but it shouldgive you the building blocks needed to solve a vast array ofproblems you may encounter quickly and easily. Use yourimagination and experiment with ACLs.The HAProxy Guide to Multi-Layer Security27

Introduction toHAProxy Stick TablesH TTP requests are stateless by design. However, thisraises some questions regarding how to track user activities,including malicious ones, across requests so that you cancollect metrics, block users, and make other decisions basedon state. The only way to track user activities between onerequest and the next is to add a mechanism for storing eventsand categorizing them by client IP or other key.Out of the box, HAProxy Enterprise and HAProxy give you afast, in-memory storage called stick tables . Released in 2010,stick tables were created to solve the problem of serverpersistence. However, StackExchange, the network of Q&Acommunities that includes Stack Overflow, saw the potentialto use them for rate limiting of abusive clients, aid in botprotection, and tracking data transferred on a per client basis.They sponsored further development of stick tables toexpand the functionality. Today, stick tables are an incrediblypowerful subsystem within HAProxy.The HAProxy Guide to Multi-Layer Security28

The name, no doubt, reminds you of sticky sessions used forsticking a client to a particular server. They do that, but also alot more. Stick tables are a type of key-value storage wherethe key is what you track across requests, such as a client IP,and the values consist of counters that, for the most part,HAProxy takes care of calculating for you. They arecommonly used to store information like how many requestsa given IP has made within the past 10 seconds. However,they can be used to answer a number of questions, such as: How many API requests has this API key been usedfor during the last 24 hours?What TLS versions are your clients using? (e.g. canyou disable TLS 1.1 yet?)If your website has an embedded search field, whatare the top search terms people are using?How many pages is a client accessing during a timeperiod? Is it enough as to signal abuse?Stick tables rely heavily on HAProxy’s access control lists, orACLs. When combined with the Stick Table Aggregatorthat’s offered within HAProxy Enterprise, stick tables bringreal-time, cluster-wide tracking. Stick tables are an areawhere HAProxy’s design, including the use of Elastic BinaryTrees and other optimizations, really pays off.Uses of Stick TablesThere are endless uses for stick tables, but here we’llhighlight three areas: server persistence, bot detection, andcollecting metrics.The HAProxy Guide to Multi-Layer Security29

Server persistence, also known as sticky sessions, is probablyone of the first uses that comes to mind when you hear theterm “stick tables”. For some applications, cookie-based orconsistent hashing-based persistence methods aren’t a goodfit for one reason or another. With stick tables, you can haveHAProxy store a piece of information, such as an IP address,cookie, or range of bytes in the request body (a username orsession id in a non-HTTP protocol, for example), andassociate it with a server. Then, when HAProxy sees newconnections using that same piece of information, it willforward the request to the same server. This is really useful ifyou’re storing application sessions in memory on yourservers.Beyond the traditional use case of server persistence, you canalso use stick tables for defending against certain types of botthreats. Request floods, login brute force attacks, vulnerabilityscanners, web scrapers, slow loris attacks—stick tables candeal with them all.A third area we’ll touch on is using stick tables for collectingmetrics. Sometimes, you want to get an idea of what is goingon in HAProxy, but without enabling logging and having toparse the logs to get the information in question. Here’swhere the power of the Runtime API comes into play. Usingthe API, you can read and analyze stick table data from thecommand line, a custom script or executable program. Thisopens the door to visualizing the data in your dashboard ofchoice. If you prefer a packaged solution, HAProxy Enterprisecomes with a fully-loaded dashboard for visualizing sticktable data.The HAProxy Guide to Multi-Layer Security30

Defining a Stick TableA stick table collects and stores data about requests that areflowing through your HAProxy load balancer. Think of it like amachine that color codes cars as they enter a race track. Thefirst step then is setting up the amount of storage a sticktable should be allowed to use, how long data should be kept,and what data you want to observe.

HAProxy Enterprise, which combines the stable codebase of HAProxy with an advanced suite of add-ons, expert support and professional services, can layer on additional defenses. At the end, you'll learn about the HAProxy Web Application Firewall, which catches application-layer attacks that are missed by other types of firewalls.