Reference

commit acl

Available since

  • HAProxy 2.4
  • HAProxy Enterprise 2.4r1

Commit a transaction of acl changes.

Description Jump to heading

Commit a transaction of acl file changes.

This command cannot be used if the reference acl is a file also used as a map. In this case, the commit map command must be used instead.

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

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

If no changes were made to the acl version since the prepare acl operation, performing the commit acl operation effectively clears the acl file in runtime memory.

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

Examples Jump to heading

In this example, we first use show acl to display the ID number of the acl file and the version number of the transaction.

nix
echo "show acl" | \
sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "show acl" | \
sudo socat stdio tcp4-connect:127.0.0.1:9999
output
text
# id (file) description
0 () acl 'path' file '/etc/hapee-2.9/hapee-lb.cfg' line 89. curr_ver=0 next_ver=1 entry_cnt=1
output
text
# id (file) description
0 () acl 'path' file '/etc/hapee-2.9/hapee-lb.cfg' line 89. curr_ver=0 next_ver=1 entry_cnt=1

Confirm the entries in the transaction. The first argument, which has a value of @1 is the version number in the transaction and comes from the next_ver field in the show acl output. The second argument, which has a value of #0, is the ACL’s ID and also comes from the show acl output.

nix
echo "show acl @1 #0" | \
sudo socat stdio tcp4-connect:127.0.0.1:9999
nix
echo "show acl @1 #0" | \
sudo socat stdio tcp4-connect:127.0.0.1:9999
output
text
0x560024702060 /scripts/
output
text
0x560024702060 /scripts/

Commit the transaction:

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

Example workflow Jump to heading

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

An ACL is split into four parts:

  • a name for the ACL, which you choose
  • a fetch to collect information from the client’s session
  • optional flags
  • a value to match against

In the example proxy configuration fragment below, we mark these parts:

haproxy
frontend www
bind :80
# name fetch flags value
acl static_url path -i -m beg /images/
haproxy
frontend www
bind :80
# name fetch flags value
acl static_url path -i -m beg /images/

To submit multiple ACL modifications atomically, use the prepare acl and commit acl commands to initiate and commit a transaction, respectively.

  1. Display a list of defined ACLs by calling show acl:

    nix
    echo "show acl" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo "show acl" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    text
    # id (file) description
    0 () acl 'path' file '/etc/hapee-2.9/hapee-lb.cfg' line 51. curr_ver=0 next_ver=0 entry_cnt=1
    output
    text
    # id (file) description
    0 () acl 'path' file '/etc/hapee-2.9/hapee-lb.cfg' line 51. curr_ver=0 next_ver=0 entry_cnt=1
  2. Display detail for the ACL by calling show acl:

    nix
    echo "show acl #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo "show acl #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    text
    0x563d5dcc40a0 /images/
    output
    text
    0x563d5dcc40a0 /images/
  3. Start a transaction to contain ACL changes until you are ready to commit them. The command displays the version number of the temporary transaction file. You will use this number in later operations on the transaction file. You can display version numbers using the show acl operation.

    nix
    echo "prepare acl" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo "prepare acl" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    text
    New version created: 1
    output
    text
    New version created: 1
  4. Use add acl to add the value /scripts/. Specify the transaction version number using the “at” (@) symbol before the ID of the ACL:

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

    This updates the ACL so that it represents this expression:

    haproxy
    frontend www
    bind :80
    acl static_url path -i -m beg /images/ /scripts/
    haproxy
    frontend www
    bind :80
    acl static_url path -i -m beg /images/ /scripts/
  5. Use del acl to remove the value /images/. Specify the transaction version number and the ID of the ACL:

    nix
    echo "del acl @1 #0 /images/" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo "del acl @1 #0 /images/" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999

    This updates the ACL so that it represents this expression:

    haproxy
    frontend www
    bind :80
    acl static_url path -i -m beg /scripts/
    haproxy
    frontend www
    bind :80
    acl static_url path -i -m beg /scripts/
  6. Commit the transaction:

    nix
    echo "commit acl @1 #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo "commit acl @1 #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
  7. Confirm the changes:

    nix
    echo "show acl #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    nix
    echo "show acl #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    text
    0x560024702060 /scripts/
    output
    text
    0x560024702060 /scripts/

See also Jump to heading

Do you have any suggestions on how we can improve the content of this page?