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 you must apply a command 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.

Note

Each scope is independent, which makes the API multitenant.

Note

The ALOHA GUI LB Admin tab can modify the root scope only.

It is not possible to list existing scopes through the :code`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.

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

Note

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

Must be applied through a transaction or a scope

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

Must be applied through a transaction or a scope

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

Must be applied through a transaction or a scope

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

Must be applied through a transaction or a scope

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

Must be applied through a transaction or a scope

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 precepts apply:

  • 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 precepts apply:

  • 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

Must be applied through a transaction or a scope

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

Must be applied through a transaction or a scope

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 the scope root, use the API and follow 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:

  • Using the atomic method The configuration is updated and applied. 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:

hapee ctl -S root transaction-begin
vZ9bBZiQcp

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

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

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

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

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

Create the listener for the L7 service:

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

Commit the transaction:

hapee ctl -T vZ9bBZiQcp transaction-commit

Save configuration in a cluster

Save the configuration on the master:

hapee ctl global-save

Push the master configuration to the slave configuration:

hapee ctl global-push

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

hapee ctl global-remote-save