Command line API

You can use the alohactl2 command line utility to manage the load balancer configuration.

Syntax Jump to heading #

The syntax for alohactl2 is as follows:

nix
sudo alohactl2 [-S <scope>|-T <transactionid>] <command> [param] [--<attribute> <value>|--reset-<attribute>]

nix
sudo alohactl2 [-S <scope>|-T <transactionid>] <command> [param] [--<attribute> <value>|--reset-<attribute>]

The parameters are as follows.

If a command must be applied through a transaction or a scope, precede any parameter with the following options as appropriate:

• -S <scope> for a scope
• -T <transactionid> for a transaction

Note also:

Return codes:

• Success: 0
• Error: Exit codes

Standard error:

• Warning / information messages

Attribute output (one attribute per line):

• + for a configured attribute
• - if default is used
• ? if attribute is configured but value is not supported by the current API version

Exit codes Jump to heading #

Global errors Jump to heading #

Normal errors Jump to heading #

Lock error Jump to heading #

Apply errors Jump to heading #

Transaction management errors Jump to heading #

Critical errors Jump to heading #

Information Jump to heading #

Scopes Jump to heading #

A scope is a portion of the configuration. It is identified by a name composed of alphanumeric characters.

A specific scope name is reserved: root. It can access any configuration which is outside of a scope.

It is not possible to list existing scopes through the alohactl2 command.

In a HAProxy configuration, a scope is identified by begin and end tags.

All frontends and backends between these tags are prefixed by the scope name.

Example:

An HAProxy configuration for a scope called bob:

haproxy
defaults bob:l7_begin
frontend bob:newservice
  [...]
  default_backend bob:newfarm
backend bob:newfarm
  [...]
defaults bob:l7_end

haproxy
defaults bob:l7_begin
frontend bob:newservice
  [...]
  default_backend bob:newfarm
backend bob:newfarm
  [...]
defaults bob:l7_end

Create a scope Jump to heading #

To create a scope, apply a configuration either atomically or through a transaction to a new scope name.

Delete a scope Jump to heading #

To delete a scope, remove all configuration belonging to the scope.

Transactions Jump to heading #

Transactions allow multiple configuration changes in one atomic operation.

Each transaction is identified by a unique identifier composed of alphanumeric characters (example: BrwClcc76t).

• Each request can be executed either atomically or as part of a transaction

• Both atomic requests and transactions apply only on a single scope

• An atomic request immediately applies the changes to the files

• A transaction must be started before issuing a load of requests; then it can be either committed or canceled

• Canceling a transaction makes no change to files and drops the entire load of requests from the beginning of the transaction

• Committing a transaction consecutively applies the changes to the files for the entire load of requests from the beginning of the transaction

where:

When committing a transaction, the following happens:

1. It creates a working context from current configuration.

2. It replays all update actions recorded on the transaction identified on the newly recreated context. Next, there are two options:

   • If replay is successful: configuration is locked, validated, applied, and finally unlocked.

   • If an error occurs during the locked phase, it processes a configuration rollback and lock is removed.

L7 farms Jump to heading #

• Attribute list: L7 farm parameters

• alohactl2 usage: alohactl2 syntax

Must be applied through a transaction or a scope.

where:

L7 servers Jump to heading #

• Attribute list: L7 server parameters

• alohactl2 usage: alohactl2 syntax

Must be applied through a transaction or a scope.

where:

L7 services Jump to heading #

• Attribute list: L7 service parameters

• alohactl2 usage: alohactl2 syntax

Must be applied through a transaction or a scope.

where:

L7 listeners Jump to heading #

• Attribute list: L7 listener parameters

• alohactl2 usage: alohactl2 syntax

Must be applied through a transaction or a scope.

where:

L7 rules Jump to heading #

• Attribute list: L7 rule parameters

• alohactl2 usage: alohactl2 syntax

Must be applied through a transaction or a scope.

where:

When deleting a rule, the following applies:

• To delete the latest rule of the list, set to tail

• To delete the first rule of the list, set to either 1 or head

• To delete the Xth rule, set to X

When creating a new rule, the following applies:

• To add a rule at the bottom of the list, set to tail

• To add a rule at the top of the list, set to either 1 or head

• To insert a rule before Xth one, set to X

L4 farms Jump to heading #

• Attribute list: L4 farm attribute

• alohactl2 usage: alohactl2 syntax

Must be applied through a transaction or a scope.

where:

L4 servers Jump to heading #

• Attribute list: L4 server attribute

• alohactl2 usage: alohactl2 syntax

Must be applied through a transaction or a scope.

where:

Complete example Jump to heading #

Configuration through a transaction Jump to heading #

To create a new frontend ft_web that points to a new backend bk_web in scope root using the API and following the procedure below:

1. Create the backend

2. Add srv1 to the backend

3. Add srv2 to the backend

4. Create the frontend

5. Add a listener to the frontend

There are two options:

• Use the atomic method: The configuration is updated, applied, and the load balancer is reloaded after each step.

• Use a transaction: A single configuration update is processed. The load balancer is reloaded only once.

Create a new transaction in the scope root:

nix
sudo alohactl2 -S root transaction-begin

nix
sudo alohactl2 -S root transaction-begin

output
text
vZ9bBZiQcp

output
text
vZ9bBZiQcp

Create the backend bk_web:

nix
sudo alohactl2 -T vZ9bBZiQcp l7-farm-create bk_web --balance roundrobin --protocol http --log enabled --log-format http --http-xff-header-insert enabled --http-cookie enabled --http-cookie-name bkweb --http-cookie-mode set-silent --http-cookie-nocache enabled --check-interval 3 --check-rise 2 --check-fall 3 --adv-check http --adv-check-http-method HEAD --adv-check-http-uri / --server-inactivity-timeout 25 --connect-timeout 4

nix
sudo alohactl2 -T vZ9bBZiQcp l7-farm-create bk_web --balance roundrobin --protocol http --log enabled --log-format http --http-xff-header-insert enabled --http-cookie enabled --http-cookie-name bkweb --http-cookie-mode set-silent --http-cookie-nocache enabled --check-interval 3 --check-rise 2 --check-fall 3 --adv-check http --adv-check-http-method HEAD --adv-check-http-uri / --server-inactivity-timeout 25 --connect-timeout 4

Add srv1 in the backend:

nix
sudo alohactl2 -T vZ9bBZiQcp l7-server-create bk_web srv1 --address 192.168.1.21 --port 80 --max-connections 1000 --weight 10 --http-cookie-id srv1 --check enabled

nix
sudo alohactl2 -T vZ9bBZiQcp l7-server-create bk_web srv1 --address 192.168.1.21 --port 80 --max-connections 1000 --weight 10 --http-cookie-id srv1 --check enabled

Add srv2 in the backend:

nix
sudo alohactl2 -T vZ9bBZiQcp l7-server-create bk_web srv2 --address 192.168.1.22 --port 80 --max-connections 1000 --weight 10 --http-cookie-id srv2 --check enabled

nix
sudo alohactl2 -T vZ9bBZiQcp l7-server-create bk_web srv2 --address 192.168.1.22 --port 80 --max-connections 1000 --weight 10 --http-cookie-id srv2 --check enabled

Create the service ft_web:

nix
sudo alohactl2 -T vZ9bBZiQcp l7-service-create ft_web --protocol http --log enabled --log-format http --client-inactivity-timeout 25 --max-connections 1000 --default-farm bk_web

nix
sudo alohactl2 -T vZ9bBZiQcp l7-service-create ft_web --protocol http --log enabled --log-format http --client-inactivity-timeout 25 --max-connections 1000 --default-farm bk_web

Create the listener for the L7 service:

nix
sudo alohactl2 -T vZ9bBZiQcp l7-service-create ft_web --protocol http --log enabled --log-format http --client-inactivity-timeout 25 --max-connections 1000 --default-farm bk_web

nix
sudo alohactl2 -T vZ9bBZiQcp l7-service-create ft_web --protocol http --log enabled --log-format http --client-inactivity-timeout 25 --max-connections 1000 --default-farm bk_web

Create the listener for the L7 service:

nix
sudo alohactl2 -T vZ9bBZiQcp l7-listener-create ft_web http --port 80 --address 0.0.0.0

nix
sudo alohactl2 -T vZ9bBZiQcp l7-listener-create ft_web http --port 80 --address 0.0.0.0

Commit the transaction:

nix
sudo alohactl2 -T vZ9bBZiQcp transaction-commit

nix
sudo alohactl2 -T vZ9bBZiQcp transaction-commit

Save configuration in a cluster Jump to heading #

Save the configuration on the master:

nix
sudo alohactl2 global-save

nix
sudo alohactl2 global-save

Push the master configuration to the slave configuration:

nix
sudo alohactl2 global-push

nix
sudo alohactl2 global-push

From the master configuration, tell the slave to save its configuration:

nix
sudo alohactl2 global-remote-save

nix
sudo alohactl2 global-remote-save