Reference

prepare map

Available since

  • HAProxy 2.4
  • HAProxy Enterprise 2.4r1

Start a transaction made up of multiple map file changes.

Description Jump to heading

If you need to make multiple changes to a map file, and you need them to be applied all at the same time in one atomic change, submit them in a transaction using the prepare map and commit map commands.

  • Use prepare map to initiate the transaction.
  • Use add map and clear map as needed to make map changes.
  • Use show map to review the temporary version.
  • Use commit map to commit the changes and make them active in runtime memory.

The prepare map command starts the transaction by allocating a new version number for a map ID or filename returned by show map. The map ID or filename argument is passed to the prepare map command. The command responds with the new version number in the “New version created:” statement.

You can use the version number in the add map, clear map, and show map commands.

There is no impact of allocating new versions, as unused versions will automatically be removed once a more recent version is committed. Version numbers are unsigned 32-bit values which wrap at the end, so care must be taken when comparing them in an external program.

The prepare map operation creates an empty version of the map. Consequently, committing the version without first adding any entries effectively clears the map in runtime memory.

There is no abort map command. To abandon a transaction, simply do not commit it. Any uncommitted transaction is removed the next time you execute the prepare map command.

Examples Jump to heading

In this example, we start a new transaction for map file /etc/hapee-2.8/hosts.map.

bash
echo "prepare map /etc/hapee-2.8/hosts.map" | \
sudo socat stdio tcp4-connect:127.0.0.1:9999
bash
echo "prepare map /etc/hapee-2.8/hosts.map" | \
sudo socat stdio tcp4-connect:127.0.0.1:9999
output
bash
New version created: 1
output
bash
New version created: 1

Contextual Example Jump to heading

This operation can be performed as part of a series of operations used to manage map files. The example in this section demonstrates how to modify mappings in load balancer’s running configuration. The mappings are not persisted to the map file on disk. Any changes you make via the Runtime API are lost when the proxy halts.

Assume that you have a map file named /etc/hapee-2.8/routes.map with the following contents where the first column contains the keys and the second contains the values:

bash
/cart/ cart_api
/reviews/ reviews_api
bash
/cart/ cart_api
/reviews/ reviews_api

In the load balancer configuration, we reference this map file on a use_backend line with the map_beg fetch method. This tells the load balancer to choose the backend from the map file by matching the beginning of the requested URL path with a key in the file:

haproxy
frontend fe_main
bind :80
use_backend %[path,map_beg(/etc/hapee-2.8/routes.map,be_servers)]
haproxy
frontend fe_main
bind :80
use_backend %[path,map_beg(/etc/hapee-2.8/routes.map,be_servers)]
  1. Use the show maps command to list map files and their unique IDs. Here, the map file /etc/hapee-2.8/routes.map has an ID of 0:

    bash
    echo "show map" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo "show map" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    bash
    # id (file) description
    0 (/etc/hapee-2.8/routes.map) pattern loaded from file '/etc/hapee-2.8/routes.map' used by map at file '/etc/hapee-2.8/hapee-lb.cfg' line 61. curr_ver=0 next_ver=1 entry_cnt=0
    output
    bash
    # id (file) description
    0 (/etc/hapee-2.8/routes.map) pattern loaded from file '/etc/hapee-2.8/routes.map' used by map at file '/etc/hapee-2.8/hapee-lb.cfg' line 61. curr_ver=0 next_ver=1 entry_cnt=0
  2. Pass the map file’s unique ID to show map to display entries in the file:

    bash
    echo "show map #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo "show map #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    bash
    0x563bbeeee160 /cart/ cart_api
    0x563bbeeee1a0 /reviews/ reviews_api
    output
    bash
    0x563bbeeee160 /cart/ cart_api
    0x563bbeeee1a0 /reviews/ reviews_api
  3. Execute the set map command with these arguments: the map’s ID, the key to be modified, and a new value to replace the key’s existing value.

    Alternatively, use the map file’s path instead of its ID.

    In the example below, we modify the /cart/ key, replacing the value cart_api with the value web_servers:

    bash
    echo "set map #0 /cart/ web_servers" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo "set map #0 /cart/ web_servers" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
  4. Call show map to confirm the modification:

    bash
    echo "show map #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo "show map #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    bash
    0x563bbeeee160 /cart/ web_servers
    0x563bbeeee1a0 /reviews/ reviews_api
    output
    bash
    0x563bbeeee160 /cart/ web_servers
    0x563bbeeee1a0 /reviews/ reviews_api

See also Jump to heading

If this page was useful, please, Leave the feedback.

© 2023 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences