Syntax
Things to know:
A map file is a simple text file.
Each line begins with a key, followed by a space, then the value.
The key must not have spaces, but the value can have spaces.
Empty lines are ignored.
Comments begin with a hash sign and must be on their own line.
HAProxy Enterprise loads the file only during startup or a reload.
Examples
The following examples show how the map file can be used to determine the proper backend.
Example 1
Consider this verbose configuration that uses five use_backend lines to route traffic in different directions depending on the URL path:
frontend www
bind :80
use_backend cart_api if { path_beg /cart/ }
use_backend reviews_api if { path_beg /reviews/ }
use_backend products_api if { path_beg /products/ }
use_backend login_api if { path_beg /login/ }
use_backend chat_servers if { path_beg /chat/ }
default_backend webservers
backend cart_api
server s1 192.168.50.20:80
backend reviews_api
server s1 192.168.50.21:80
backend products_api
server s1 192.168.50.22:80
backend login_api
server s1 192.168.50.23:80
backend chat_servers
server s1 192.168.50.24:80
backend webservers
server s1 192.168.50.25:80You can simplify this by using a map file. In the file, the path would be the key and the backend to use would be the value.
Example map file routes.map:
/cart/ cart_api
/review/ review_api
/products/ products_api
/login/ login_api
/chat/ chat_serversThen you could use the map_beg converter to look up a key in the map and get its value.
Below, we pass the requested URL path to the converter, which checks whether any of the keys in the map match the beginning of the requested path. If yes, that key's value is returned and used to complete the use_backend line:
frontend www
bind :80
use_backend %[path,map_beg(/etc/hapee-2.0/routes.map)]
default_backend webservers
backend cart_api
server s1 192.168.50.20:80
backend reviews_api
server s1 192.168.50.21:80
backend products_api
server s1 192.168.50.22:80
backend login_api
server s1 192.168.50.23:80
backend chat_servers
server s1 192.168.50.24:80
backend webservers
server s1 192.168.50.25:80Example 2
In this example we use the req.hdr fetch method to get the Host request header and then pass it to the map converter to look up the matching key in the file routes.map. If a matching key exists in the file, HAProxy Enterprise returns its value (such as apiservers). Otherwise, it uses the default value, webservers.
Example map file routes.map:
www.example.com webservers api.example.com apiservers static.example.com cacheservers
HAProxy Enterprise configuration:
frontend www bind :80 # Choose which backend depending on the Host header use_backend %[req.hdr(host),map(/etc/hapee-2.0/routes.map,webservers)] backend webservers server s1 192.168.50.10:80 check backend apiservers server s1 192.168.50.20:80 check backend cacheservers server s1 192.168.50.30:80 check
If there is no matching key found in the map file and if you do not specify a default, HAProxy Enterprise does not return a value from the converter.
Map converters
You access map files using the map family of converters. A converter's first argument is the path to the map file. Its second parameter sets a default value and is optional. Variants of the map converter allow a partial match of a key. See map converters in the Configuration Manual for details.
Match the beginning of a sample
The map_beg converter matches the key against the beginning of the input sample returned by the fetch. For instance, a requested URL path of /api/weather/midwest would match /api/ in the file.
Map file routes.map:
/api/ apiservers /static/ cacheservers
HAProxy Enterprise configuration:
frontend www bind :80 # Matches the beginning of the input, but defaults to webservers use_backend %[path,map_beg(/etc/hapee-2.0/routes.map,webservers)]
Match the end of a sample
The map_end converter matches the key against the end of the input sample. For instance, a URL path /image.jpg would match .jpg in the file.
Map file routes.map:
.jpg cacheservers .png cacheservers
HAProxy Enterprise configuration:
frontend www bind :80 # Matches the end of the input, but defaults to webservers use_backend %[path,map_end(/etc/hapee-2.0/routes.map,webservers)]
Match a substring of a sample
The map_sub converter matches a substring in the input sample. For instance, a URL path /shop/shirts/sale/ would match /shirts/ in the file.
Map file routes.map:
/shirts/ webservers1 /pants/ webservers2
HAProxy Enterprise configuration:
frontend www bind :80 # Matches a substring in the input, but defaults to webservers1 use_backend %[path,map_sub(/etc/hapee-2.0/routes.map,webservers1)]
Match an IP address
The map_ip converter matches an IP address. If a key in the map file has a netmask (e.g. 192.168.0.0/16), then the IP matches if it falls within the IP range.
Map file routes.map:
10.0.0.0/16 eastcoast 10.1.0.0/16 westcoast
HAProxy Enterprise configuration:
frontend www bind :80 # Matches an IP addres in a range, but defaults to eastcoast use_backend %[src,map_ip(/etc/hapee-2.0/routes.map,eastcoast)]
Match a domain
The map_dom converter matches a domain or a part of a domain against a key. For instance, the key example.com would match input samples example.com, www.example.com, or demo.example.com.
Map file routes.map:
example.com webservers1 test.com webservers2
HAProxy Enterprise configuration:
frontend www bind :80 # Matches an IP addres in a range use_backend %[req.hdr(host),map_dom(/etc/hapee-2.0/routes.map)]
Match a regular expression
The map_reg converter matches the input sample based on a regular expression. For instance, the regular expression ^(\/sale\/).*(\.jpg)$ would match a URL that begins with /sale/ and ends with .jpg.
Map file routes.map:
^(\/sale\/).*(\.jpg)$ cacheservers
HAProxy Enterprise configuration:
frontend www bind :80 # Matches the regular expression, but defaults to webservers use_backend %[path,map_reg(/etc/hapee-2.0/routes.map,webservers)]
See also
Next up
Stick Tables