Command Line API
The command line alohactl2 is a utility dedicated to manage load balancing configuration.
Syntax
The syntax for alohactl2
is as follows:
$ sudo alohactl2 [-S <scope>|-T <transactionid>] <command> [param] [--<attribute> <value>|--reset-<attribute>]
with these parameters:
| Scope name within which to run the command |
| Transaction ID to run the command |
| Command to run |
| List provided by the object type |
Return codes |
|
stderr output | Warning / information messages |
attribute output | One attribute per line:
|
If a command must be applied through a transaction or a scope, be sure to precede any parameter with the following ones:
-T <transactionid>
for a transaction-S <scope>
for a scope
Exit Codes
Global errors
1 | Syntax error/unknown option. |
---|---|
2 | Missing scope. |
3 | Missing transaction ID |
4 | Missing transaction ID or scope |
Normal errors
20 | Transaction does not exist |
---|---|
21 | Defaults does not exist |
22 | Object does not exist |
23 | Object already exists |
24 | Mandatory parameter not set |
25 | Invalid parameter value |
Lock error
100 | API is locked, retry later |
---|
Apply errors
101 | Invalid configuration (original is restored) |
---|---|
102 | New configuration apply failure (original is restored and re-applied) |
Transaction management errors
110 | Corrupted transaction |
---|---|
111 | Unable to create transaction |
112 | Unable to create transaction module context |
113 | Unable to prepare commit |
114 | Unable to backup configuration to attempt a commit |
115 | Unable to install new configuration |
Critical errors
120 | Unable to restore original configuration. |
---|---|
121 | Unable to apply original restored configuration |
122 | Unable to save configuration on flash or sync on a peer |
Information
Action | alohactl parameters |
---|---|
API version | version |
Scopes
A scope is a portion of the configuration. It is identified by a name composed of alpha-numeric characters.
A specific scope name is reserved: root
. It can access any configuration which that outside of a scope.
It is not possible to list existing scopes through the :code`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.
An HAProxy configuration for a scope called bob:
defaults bob:l7_begin
frontend bob:newservice
[...]
default_backend bob:newfarm
backend bob:newfarm
[...]
defaults bob:l7_end
Create a scope
To create a scope, apply a configuration either atomically or through a transaction to a new scope name.
Delete a scope
To delete a scope, remove all configuration belonging to the scope.
Transactions
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
Action | alohactl2 parameters |
---|---|
list all |
|
cancel all |
|
start |
|
commit |
|
cancel |
|
run an atomic command in a scope |
|
run an atomic command in a transaction |
|
where:
| scope identifier |
| transaction unique identifier |
| actions to perform |
When committing a transaction, the following happens:
It creates a working context from current configuration.
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
Attribute list: L7 farm parameters
alohactl2 usage: alohactl2 syntax
Must be applied through a transaction or a scope
Action | alohactl2 parameters |
---|---|
List available L7 farms |
|
Delete all available L7 farms |
|
Display an L7 farm configuration |
|
Create an L7 farm |
|
Update an L7 farm |
|
Delete an L7 farm |
|
where:
| name of an L7 farm |
| an L7 farm attribute |
L7 servers
Attribute list: L7 server parameters
alohactl2 usage: alohactl2 syntax
Must be applied through a transaction or a scope
Action | alohactl2 parameters |
---|---|
List available servers in an L7 farm |
|
Delete all available L7 servers |
|
Display an L7 server configuration |
|
Create an L7 server |
|
Update an L7 server |
|
Delete an L7 server |
|
where:
| name of an L7 farm |
| name of a L7 server |
| an L7 farm attribute |
L7 services
Attribute list: L7 service parameters
alohactl2 usage: alohactl2 syntax
Must be applied through a transaction or a scope
Action | alohactl2 parameters |
---|---|
List available servers in an L7 service |
|
Delete all available L7 service |
|
Display an L7 service configuration |
|
Create an L7 service |
|
Update an L7 service |
|
Delete an L7 service |
|
where:
| name of a L7 service |
| an L7 service attribute |
L7 listeners
Attribute list: L7 listener parameters
alohactl2 usage: alohactl2 syntax
Must be applied through a transaction or a scope
Action | alohactl2 parameters |
---|---|
List available listeners in an L7 service |
|
Delete all available listeners |
|
Display an L7 listener configuration |
|
Create an L7 listener |
|
Update an L7 listener |
|
Delete an L7 listener |
|
where:
| name of a L7 service |
| name of a L7 listener |
| an L7 listener attribute |
L7 rules
Attribute list: L7 rule parameters
alohactl2 usage: alohactl2 syntax
Must be applied through a transaction or a scope
Action | alohactl2 parameters |
---|---|
List rules by type |
|
Delete all rules by type |
|
Display a rule configuration |
|
Create a rule |
|
Update a rule |
|
Delete a rule |
|
where:
| can be either:
| ||||||||||||||||||||||
| name of the object to apply the action on | ||||||||||||||||||||||
| depends on Rules available for a service:
Rules available for a farm:
| ||||||||||||||||||||||
| can be either
|
When deleting a rule, the following applies:
To delete the latest rule of the list, set <number> to tail
To delete the first rule of the list, set <number> to either 1 or head
To delete the Xth rule, set <number> to X
When creating a new rule, the following applies:
To add a rule at the bottom of the list, set <number> to tail
To add a rule at the top of the list, set <number> to either 1 or head
To insert a rule before Xth one, set <number> to X
L4 farms
Attribute list: L4 farm attribute
alohactl2 usage: alohactl2 syntax
Must be applied through a transaction or a scope
Action | alohactl2 parameters |
---|---|
List farms |
|
Delete all farms |
|
Display configuration |
|
Create a farm |
|
Update a farm |
|
Delete a farm |
|
where:
| name of an L4 farm |
| an L4 farm attribute |
L4 servers
Attribute list: L4 server attribute
alohactl2 usage: alohactl2 syntax
Must be applied through a transaction or a scope
Action | alohactl2 parameters |
---|---|
List available servers in a farm |
|
Delete all servers from a farm |
|
Display server configuration |
|
Create a server |
|
Update a server |
|
Delete a server |
|
where:
| name of an L4 farm |
| name of a L4 server |
| an L4 farm attribute |
Complete Example
Configuration through a transaction
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:
Create the backend
Add srv1 to the backend
Add srv2 to the backend
Create the frontend
Add a listener to the frontend
There are two options:
-
- Using the atomic method
-
The configuration is updated, applied, and HAProxy is reloaded after each step.
-
- Using a transaction
-
A single configuration update is processed. HAProxy is reloaded only once.
Create a new transaction in the scope root:
$ sudo alohactl2 -S root transaction-begin
vZ9bBZiQcp
Create the backend bk_web:
$ 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:
$ 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:
$ 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:
$ 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:
$ 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:
$ sudo alohactl2 -T vZ9bBZiQcp l7-listener-create ft_web http --port 80 --address 0.0.0.0
Commit the transaction:
$ sudo alohactl2 -T vZ9bBZiQcp transaction-commit
Save configuration in a cluster
Save the configuration on the master:
$ sudo alohactl2 global-save
Push the master configuration to the slave configuration:
$ sudo alohactl2 global-push
From the master configuration, tell the slave to save its configuration:
$ sudo alohactl2 global-remote-save
Next up
REST / JSON Web API