add map

Add an entry to a Map file.

Description Jump to heading #

A Map file contains a list of key-value pairs. You can reference the file on an acl line by using the -M and -f /path/to/file flags. Use add map to add a new entry to a Map file. Note that this only adds it to the load balancer’s runtime memory and not to the file on disk.

Map files can also be virtual or optional. If you’re using a virtual Map file, prefix the filename with virt@ when calling add map. If the file is optional, then don’t specify a prefix.

Examples Jump to heading #

Add a map entry Jump to heading #

In this example, the key foo.example.com and value be_bar are added as a new line in the file /etc/hapee-3.0/maps/hosts.map.

nix
echo "add map /etc/hapee-3.0/maps/hosts.map foo.example.com be_bar" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "add map /etc/hapee-3.0/maps/hosts.map foo.example.com be_bar" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Add a map entry to a transaction Jump to heading #

Multiple map file changes can be submitted atomically using the transaction feature. Use prepare map to start a transaction and commit map to apply the transaction.

The prepare map command returns a temporary map file version ID. Specify this ID using the “at” (@) symbol before the map ID.

1. Use the show maps command to list map files and their unique IDs.

   nix
   echo "show map" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "show map" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   # id (file) description
   0 (/etc/hapee-3.0/routes.map) pattern loaded from file '/etc/hapee-3.0/routes.map' used by map at file '/etc/hapee-3.0/hapee-lb.cfg' line 61. curr_ver=0 next_ver=1 entry_cnt=0

   output
   text
   # id (file) description
   0 (/etc/hapee-3.0/routes.map) pattern loaded from file '/etc/hapee-3.0/routes.map' used by map at file '/etc/hapee-3.0/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:

   nix
   echo "show map #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "show map #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   0x563bbeeee160 /cart/ cart_api
   0x563bbeeee1a0 /reviews/ reviews_api

   output
   text
   0x563bbeeee160 /cart/ cart_api
   0x563bbeeee1a0 /reviews/ reviews_api

3. Use prepare map to start a transaction.

   nix
   echo "prepare map #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "prepare map #0" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   New version created: 1

   output
   text
   New version created: 1

4. Add the key /support/ and value support_api as a new line in the temporary transaction file.

   nix
   echo "add map @1 #0 /support/ support_api" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "add map @1 #0 /support/ support_api" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

5. Use commit map to apply the transaction.

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

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

See also Jump to heading #

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