commit map

Commit a transaction of map file changes.

Description Jump to heading #

Commit a transaction of map file changes. A transaction is initiated by executing the prepare map operation, which creates a new version of the map file. The version number is displayed as next_ver by the show map command. By specifying the version number and map ID or file name, you can make changes to the temporary map version using operations such as add map and clear map.

Committing the transaction makes the changes active in runtime memory and deletes all past versions of the map file in runtime memory. The operation is atomic. All changes represented in the transaction are applied together instantly, and any previous versions of the map are deleted from memory.

If no changes were made to the map version since the prepare map operation, performing the commit map operation 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 first use show map to display the ID number of the map file and the version number of the transaction.

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
2 (/etc/hapee-2.8/maps/routes.map) pattern loaded from file '/etc/hapee-2.8/maps/routes.map' used by map at file '/etc/hapee-2.8/hapee-lb.cfg' line 89. curr_ver=0 next_ver=1 entry_cnt=1 

output
bash
# id (file) description
2 (/etc/hapee-2.8/maps/routes.map) pattern loaded from file '/etc/hapee-2.8/maps/routes.map' used by map at file '/etc/hapee-2.8/hapee-lb.cfg' line 89. curr_ver=0 next_ver=1 entry_cnt=1 

Confirm the entries in the transaction:

bash
echo "commit map @1 #2" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

bash
echo "commit map @1 #2" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

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 #

• add map
• clear map
• del map
• get map
• prepare map
• set map
• show map