Reference

prepare acl

Available since

  • HAProxy 2.4
  • HAProxy Enterprise 2.4r1

Start a transaction made up of multiple acl changes.

Description Jump to heading

If you need to make multiple changes to an acl 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 acl and commit acl commands.

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

The workflow is as follows:

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

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

You can use the version number in the add acl, clear acl, and show acl 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 acl operation creates an empty version of the acl file. Consequently, committing the version without first adding any entries 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 start a new transaction for acl file /etc/hapee-2.8/paths.acl.

bash
echo "prepare acl /etc/hapee-2.8/paths.acl" | \
sudo socat stdio tcp4-connect:127.0.0.1:9999
bash
echo "prepare acl /etc/hapee-2.8/paths.acl" | \
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 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/

This ACL expression checks whether the requested URL path begins with /images/:

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

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

    bash
    echo "show acl #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo "show acl #0" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    bash
    0x563d5dcc40a0 /images/
    output
    bash
    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.

    bash
    echo "prepare acl" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo "prepare acl" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    bash
    New version created: 1
    output
    bash
    New version created: 1
  4. Use add acl to add the value /scripts/. Specify the transaction version number and the ID of the ACL:

    bash
    echo "add acl @1 #0 /scripts/" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    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:

    bash
    echo "del acl @1 #0 /images/" | \
    sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    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:

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

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

See also Jump to heading

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