Command Line API

The command line hapee ctl is a utility dedicated to manage load balancing configuration.

Syntax

The syntax for hapee ctl is as follows:

hapee ctl [-S <scope>|-T <transactionid>] <command> [param] [--<attribute> <value>|--reset-<attribute>]

with these parameters:

<scope> Scope name to run the command within
<transactionid> Transaction ID to run the command
<command> Command to run
<attribute> List provided by the object type
Return codes
  • Success: 0
  • Error: Exit codes
stderr output 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

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 hapee ctl 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.

Each scope is independent, which makes the API multitenant.
The ALOHA GUI LB Admin tab can modify the root scope only.

It is not possible to list existing scopes through the hapee ctl 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:

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
A transaction must belong to a scope.
Action hapee ctl parameters
list all transaction-list
cancel all transaction-flush
start -S <scope> transaction-begin
commit -T <transactionid> transaction-commit
cancel -T <transactionid> transaction-cancel
run an atomic command in a scope -S <scope> <command> <parameters>
run an atomic command in a transaction -T <transactionid> <command> <parameters>

where:

<scope> scope identifier
<transactionid> transaction unique identifier
<command> and <parameters> actions to perform

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

Action hapee ctl parameters
List available L7 farms l7-farm-list
Delete all available L7 farms l7-farm-flush
Display an L7 farm configuration l7-farm-dump <farmname>
Create an L7 farm l7-farm-create <farmname> [–<attribute> <value>]
Update an L7 farm l7-farm-update <farmname> [–<attribute> <value>|–reset-<attribute>]
Delete an L7 farm l7-farm-delete <farmname>

where:

<farmname> name of an L7 farm
<attribute> an L7 farm attribute

L7 servers

Action hapee ctl parameters
List available servers in an L7 farm l7-server-list <farmname>
Delete all available L7 servers l7-server-flush <farmname>
Display an L7 server configuration l7-server-dump <farmname> <servername>
Create an L7 server l7-server-create <farmname> <servername> [–<attribute> <value>]
Update an L7 server l7-server-update <farmname> <servername> [–<attribute> <value>|–reset-<attribute>]
Delete an L7 server l7-server-delete <farmname> <servername>

where:

  • <farmname> : name of an L7 farm
  • <servername> : name of a L7 server
  • <attribute> : an L7 farm attribute

L7 services

Action hapee ctl parameters
List available servers in an L7 service l7-service-list <servicename>
Delete all available L7 service l7-service-flush <servicename>
Display an L7 service configuration l7-service-dump <servicename>
Create an L7 service l7-service-create <servicename> [–<attribute> <value>]
Update an L7 service l7-service-update <servicename> [–<attribute> <value>|–reset-<attribute>]
Delete an L7 service l7-service-delete <servicename>

where:

  • <servicename>: name of a L7 service
  • <attribute>: an L7 service attribute

L7 listeners

Action hapee ctl parameters
List available listeners in an L7 service l7-listener-list <L7 servicename>
Delete all available listeners l7-listener-flush <L7 servicename>
Display an L7 listener configuration l7-listener-dump <L7 servicename> <listenername>
Create an L7 listener l7-listener-create <L7 servicename> <listenername>[–<attribute> <value>]
Update an L7 listener l7-listener-update <L7 servicename> <listenername>[–<attribute> <value>|–reset-<attribute>]
Delete an L7 listener l7-listener-delete <L7 servicename> <listenername>

where:

  • <servicename>: name of a L7 service
  • <listenername> : name of a L7 listener
  • <attribute>: an L7 listener attribute

L7 rules

Action hapee ctl parameters
List rules by type l7-<objecttype>-<ruletype>-list <objectname>
Delete all rules by type l7-<objecttype>-<ruletype>-flush <objectname>
Display a rule configuration l7-<objecttype>-<ruletype>-show <objectname> <number>
Create a rule l7-<objecttype>-<ruletype>-create <objectname> <number> [–<attribute> <value>]
Update a rule l7-<objecttype>-<ruletype>-update <objectname> <number> [–<attribute> <value>|–reset-<attribute>]
Delete a rule l7-<objecttype>-<ruletype>-delete <objectname> <number>

where:

<objecttype> can be either:

  • service : if the rule applies to a L7 service
  • farm : if the rule applies to a L7 farm

<objectname> : name of the object to apply the action on

<ruletype> depends on <objecttype>:

  • rules available for a service :
    • tcpreqconn, with the following <attribute> list: L7 tcpreqconn rule attributes
    • tcpreqcont, with the following <attribute> list: L7 tcpreqcont rule attributes
    • httpreq, with the following <attribute> list: L7 httpreq rule parameters
    • redirect, with the following <attribute> list: L7 redirect rule parameters
    • usefarm, with the following <attribute> list: L7 usefarm rule parameters
  • rules available for a farm:
    • tcpreqcont, with the following <attribute> list: L7 tcpreqcont rule attributes
    • httpreq, with the following <attribute> list: L7 httpreq rule parameters
    • redirect, with the following <attribute> list: L7 redirect rule parameters
    • useserver, with the following <attribute> list: L7 useserver rule parameters
    • tcprspcont, with the following <attribute> list: L7 tcprspcont rule parameters
    • tcpcheck, with the following <attribute> list: L7 tcpcheck rule parameters

<number> can be either:

  • tail: get the first rule of the list
  • head: get the last rule of the list
  • a positive integer: get the rule indicated by the integer

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

Action hapee ctl parameters
List farms l7-farm-list
Delete all farms l7-farm-flush
Display configuration l7-farm-dump <farmname>
Create a farm l7-farm-create <farmname> [–<attribute> <value>]
Update a farm l7-farm-update <farmname> [–<attribute> <value>|–reset-<attribute>]
Delete a farm l7-farm-delete <farmname>

where:

<farmname> name of an L4 farm
<attribute> an L4 farm attribute

L4 servers

Action hapee ctl parameters
List available servers in a farm l4-server-list <farmname>
Delete all servers from a farm l4-server-flush <farmname>
Display server configuration l4-server-dump <farmname> <servername>
Create a server l4-server-create <farmname> <servername> [–<attribute> <value>]
Update a server l4-server-update <farmname> <servername> [–<attribute> <value>|–reset-<attribute>]
Delete a server l4-server-delete <farmname> <servername>

where:

  • <farmname> : name of an L4 farm
  • <servername> : name of a L4 server
  • <attribute> : 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:

  1. create the backend
  2. add srv1 to the backend
  3. add srv2 to the backend
  4. creation of the frontend
  5. 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.

1. Create a new transaction in the scope root:

hapee ctl -S root transaction-begin
vZ9bBZiQcp

2. Create the backend `bk_web`:

hapee ctl -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

3. Add srv1 in the backend:

hapee ctl -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

4. Add srv2 in the backend:

hapee ctl -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

5. Create the service ft_web:

hapee ctl -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

6. Create the listener for the L7 service:

hapee ctl -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

7. Create the listener for the L7 service:

hapee ctl -T vZ9bBZiQcp l7-listener-create ft_web http --port 80 --address 0.0.0.0

8. Commit the transaction:

hapee ctl -T vZ9bBZiQcp transaction-commit

Save configuration in a cluster

1. Save the configuration on the master:

hapee ctl global-save

2. Push the master configuration to the slave configuration:

hapee ctl global-push

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

hapee ctl global-remote-save