HAProxy Enterprise Documentation 2.0r1

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.

  • You can display and manage map files using Runtime API commands such as show map and add map.

Examples

The following examples show how the map file can be used to determine the proper backend.

Example 1

Consider this verbose configuration that does not use mapping. Instead, it 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:80

You can simplify this configuration 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_servers

Then 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:80

Example 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