Smarter by Design.Simpler for Business
lb backend-group
The lb backend-group command gathers more than one backend server that gives the same service under a single record. The health check, SSL and source address settings are applied to the whole group; the address, the weight and the connection limit are written separately for every server. Its panel equivalent is the Backend Groups screen.
If a single server is enough, lb backend is used; a group is needed when the traffic will be distributed among the servers.
Command Summary
# Tab after the command
admin@TR7LBWAF01> lb backend-group
add delete list show update update-many
admin@TR7LBWAF01> lb backend-group list # list all of them
admin@TR7LBWAF01> lb backend-group show <id> # show one
admin@TR7LBWAF01> lb backend-group add name <name> v-device <v-device> …
admin@TR7LBWAF01> lb backend-group update id <id> … # change
admin@TR7LBWAF01> lb backend-group update-many <target> … # bulk change
admin@TR7LBWAF01> lb backend-group delete <id> # delete
admin@TR7LBWAF01>
Writing Order
Step 1 Write the name
lb backend-group add web-poolStep 2 Select the virtual device
The v-device on which the group will be defined. The default is the device on which the command runs.
Step 3 Select the route table
The default value is
1. Step 4 Add the servers with an index
--servers.0.addr.ip … --servers.0.addr.port … --servers.1.addr.ip …Step 5 Add the group settings
The health check, SSL and source address fields are applied to the whole group.
Required Fields
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | name | Required | The name of the group; it must be unique in the collection |
| 2 | v-device | Required | The virtual device; the default is the device on which the command runs |
| 3 | namespace | Required | The route table; the default is 1 |
| — | differentIp.ip | Conditionally required | It is asked for only when --useDifferentIp true is written |
These three fields are written bare, without a slash. The address and the port are not asked for at the group level; they are given for every server with the --servers.N.addr.ip and --servers.N.addr.port fields.
A group must not be left without a server
In the schema the server list is defined as required. For this reason the group is written on the command line together with at least one server: --servers.0.addr.ip and --servers.0.addr.port.
The Server Fields
Every server is written with its own index: in the form --servers.0.…, --servers.1.….
| Field | Default | Value |
|---|---|---|
--servers.N.addr.ip | — | The IP address or the domain name of the server |
--servers.N.addr.port | — | The port of the server |
--servers.N.weight | None | The distribution weight; between 1 and 256 |
--servers.N.connLimit | None | The concurrent connection limit; between 1 and 65535 |
--servers.N.cookieContent | None | The cookie value that marks this server in the session persistence |
The address, the weight, the connection limit and the cookie value exist only at the server level; all the fields below are applied to the whole group.
The Health Check Fields
| Field | Default | Value |
|---|---|---|
--hc | None | The lb hc record to be applied |
--enableHcLog | true | Whether the health check logs will be kept or not |
--useDifferentIp | false | The health check being done to a different address |
--differentIp.ip | — | The address on which the check will be done; required while --useDifferentIp true |
--differentIp.port | None | The port on which the check will be done |
--differentSrcType | None | The source address of the check: empty or deviceSrc |
--deviceSrc | — | The device address to be used while --differentSrcType deviceSrc |
The SSL Fields
These fields are applied to the connection between TR7 and the servers in the group and are effective only when --sslService true is written.
| Field | Default | Value |
|---|---|---|
--sslService | false | Connecting to the servers with SSL |
--ciphers | standard | The cipher suite: standard or low |
--sni | None | The SNI value to be sent in the connection |
--alpn | http20_disabled | http20_disabled (HTTP/2 off) or http20_enabled (HTTP/2 on) |
--sslSecurityProfile | None | The lb ssl-security profile to be applied |
--sslVerify | none | The verification of the server certificate: none or required |
--sslVerifyCa | None | The CA profile to be used in the verification; it is written while --sslVerify required |
--sslClientCert | None | The client certificate that TR7 will present while identifying itself to the servers |
The Group Behavior and Source Address Fields
| Field | Default | Value |
|---|---|---|
--backupService | false | Marking the group as a backup |
--maintenanceMode | false | Taking the group into maintenance; no traffic is sent |
--useFrontendPort | false | Connecting to the servers with the listening port on which the request arrived |
--proxyOpt | None | send-proxy (PROXY protocol v1) or send-proxy-v2 |
--snatOpt | None | The source address translation: clientIp or customIpDevice |
--snatIpDevice | — | The address to be used while --snatOpt customIpDevice |
--spoofing | false | The MAC relay behavior while --snatOpt clientIp |
--spoofingIp | — | The address to be used for the relay |
--spoofingClusterIp | — | The VIP that determines the relay condition |
--spoofingDefaultClusterId | 1 | The default device for the relay |
Examples
# the required fields are written without a prefix and before the -- fields in every case
admin@TR7LBWAF01> lb backend-group add name web-pool v-device <v-device> namespace 1 \
--servers.0.addr.ip 10.0.10.21 --servers.0.addr.port 8080 \
--servers.1.addr.ip 10.0.10.22 --servers.1.addr.port 8080
admin@TR7LBWAF01>
# a higher weight for the stronger server
admin@TR7LBWAF01> lb backend-group add name api-pool v-device <v-device> namespace 1 \
--servers.0.addr.ip 10.0.20.11 --servers.0.addr.port 9000 --servers.0.weight 60 \
--servers.1.addr.ip 10.0.20.12 --servers.1.addr.port 9000 --servers.1.weight 40 \
--hc <check> --enableHcLog true
admin@TR7LBWAF01>
admin@TR7LBWAF01> lb backend-group add name tls-pool v-device <v-device> namespace 1 \
--servers.0.addr.ip 10.0.30.11 --servers.0.addr.port 443 \
--servers.1.addr.ip 10.0.30.12 --servers.1.addr.port 443 \
--sslService true --sni portal.kurum.com.tr --sslVerify required --sslVerifyCa <ca-profile>
admin@TR7LBWAF01>
Adding and Removing a Server
# changing the weight of an existing server
admin@TR7LBWAF01> lb backend-group update id <id> --servers.0.weight 80
# adding a new server to the list: the next index is written
admin@TR7LBWAF01> lb backend-group update id <id> \
--servers.2.addr.ip 10.0.10.23 --servers.2.addr.port 8080
# removing a single server from the list
admin@TR7LBWAF01> lb backend-group update id <id> --servers.1.delete
# emptying the whole server list
admin@TR7LBWAF01> lb backend-group update id <id> --servers.delete
admin@TR7LBWAF01>
The --servers.N.delete and --servers.delete flags do not take a value and appear only in the update command.
Binding to a vService
admin@TR7LBWAF01> lb service update id <vService> --defaultBackendList.0 <group>
admin@TR7LBWAF01>
Updating and Deleting
admin@TR7LBWAF01> lb backend-group update id <id> --maintenanceMode true
admin@TR7LBWAF01> lb backend-group delete <id>
admin@TR7LBWAF01>
Bulk Update
update-many applies the same change to many group records at once. The writing order is the same on every resource.
Step 1 Select the target
The only required field is
target: selected for the records selected from the list, all for the entire collection. Step 2 Add the fields to be written
Only the fields that can be written to many records with the same value are present; the fields specific to the record, such as the id, the name and the server list, do not take place in this command.
Step 3 Mark the targets from the list
When
target selected is written and no id is given, a selection list with checkboxes opens. Step 4 Confirm
A warning stating how many records will be affected appears; nothing is written until the confirmation word is typed.
| Field | Status | Value |
|---|---|---|
target | Required | selected — the records selected from the list · all — the whole collection |
--ids.N | Conditional | The target ids for target selected. It is not suggested in the Tab list: the targets are marked from the selection list. In a script and in a pipeline it is written manually. |
--onError | Optional | abort (default) — if even one of the targets does not pass the validation, nothing is written · skip — the targets that pass are written |
Writable Fields
# Tab after the command
admin@TR7LBWAF01> lb backend-group update-many
--info target
# Tab after the target field
admin@TR7LBWAF01> lb backend-group update-many target
all selected
# write -- and Tab: all the writable fields
admin@TR7LBWAF01> lb backend-group update-many target all --
--alpn --backupService --ciphers
--differentSrcType --enableHcLog --hc
--info --maintenanceMode --onError
--proxyOpt --snatOpt --spoofing
--spoofingDefaultClusterId --sslClientCert --sslSecurityProfile
--sslService --sslVerify --sslVerifyCa
--useDifferentIp --useFrontendPort
admin@TR7LBWAF01>
There are 20 fields in the command; the list above is the same as what appears when -- is written and Tab is pressed on the device. What each one does and what is written after it is in the table below.
The fields that are condition-bound in the single command (those that open according to the value of another field) are listed here without a condition: in the bulk update every target is validated separately according to its own record, and if the field is not active on a target it is skipped only on that target.
| Field | What it does | What is written after it |
|---|---|---|
--info | Writes what the command will do without running it | It does not take a value; it is written on its own |
--onError | Determines what will happen if a target does not pass the validation | abort writes nothing (default) · skip writes the targets that pass |
--hc | Binds the health check to be applied to the targets | The lb hc record; Tab lists the existing ones |
--enableHcLog | Determines whether the health check logs will be kept or not | true · false (default true) |
--useDifferentIp | Turns on the health check being done to an address different from the address to which the traffic goes | true · false (default false). Since the check address is specific to the record, it cannot be written in this command; give the address with the single update |
--differentSrcType | Selects from which source address the health check will go out | It is left empty or deviceSrc is written |
--manualSrc | It is the field that serves to write by hand the source address from which the health check will go out | Since the value set of the --differentSrcType field does not contain manualSrc in this version, the field never becomes active |
--maintenanceMode | Takes the record into maintenance; no traffic is sent to the targets, the configuration is not deleted | true · false (default false) |
--backupService | Marks the record as a backup; it does not receive traffic while the others are healthy | true · false (default false) |
--useFrontendPort | Makes the connection to the backend be made with the listening port on which the request arrived | true · false (default false) |
--proxyOpt | Carries the real address of the client to the backend with the PROXY protocol | send-proxy (PROXY protocol v1) · send-proxy-v2; when it is left empty it is off |
--sslService | Turns on connecting to the backend with SSL; all the SSL fields depend on it | true · false (default false) |
--ciphers | Selects the cipher suite to be used in the SSL connection | standard · low (default standard) |
--alpn | Determines whether HTTP/2 will be used in the SSL connection or not | http20_disabled · http20_enabled (default http20_disabled) |
--sslSecurityProfile | Applies an SSL security profile to the backend connection | The lb ssl-security record. In this connection only the minimum/maximum SSL version, the cipher list and the curve settings of the profile are valid |
--sslVerify | Determines whether the certificate presented by the backend will be verified or not | none · required (default none) |
--sslVerifyCa | Selects which CA profile will be used in the verification | The lb ca record; it is meaningful together with --sslVerify required |
--sslClientCert | Selects the client certificate that TR7 will present while identifying itself to the backend (mTLS) | A certificate record. This is the opposite direction of the verification of the certificate of the visitor: here the client is TR7 |
--snatOpt | Selects how the source address of the connection going to the backend will be determined | clientIp carries the address of the client · customIpDevice uses the address selected over the device; when it is left empty no translation is done |
--spoofing | Turns on the MAC relay behavior while the source address is carried from the client | true · false (default false); it is meaningful together with --snatOpt clientIp |
--spoofingDefaultClusterId | Selects the default device for the MAC relay | It is selected from the device list (default 1) |
Fields that exist in the single command but not here, and the reasons:
| Field | Why it is not here |
|---|---|
name | The name is unique; the same value cannot be written to many records |
v-device | The virtual device determines the set of addresses and tables that can be selected; its value depends on the sibling fields |
namespace | The route table depends on the virtual device in the same way |
sni | It is a smart content field; it carries not a value but an expression resolved according to the record |
snatIpDevice | Its value comes from the address list of the selected virtual device |
spoofingIp | It is an address field; it is written separately for every record |
spoofingClusterIp | Its value depends on the sibling fields |
deviceSrc | Its value comes from the address list of the selected device |
differentIp.ip | The health check address is specific to the record; since it is an object field it cannot be written in bulk |
differentIp.port | It is part of the same object field |
servers.N.addr.ip | The server list items carry their own ids; the item ids of one group cannot be copied to the others |
servers.N.weight | It is part of the same list |
servers.N.connLimit | It is part of the same list |
servers.N.cookieContent | It is part of the same list |
Target Selection and Confirmation
admin@TR7LBWAF01> lb backend-group update-many target selected --maintenanceMode true
? Target objects
space: mark · ctrl+a: all · enter: confirm
Filter: (filter by typing) · esc: cancel
[x] <record-1>
[x] <record-2>
[ ] <record-3>
2 selected / 3
⚠ 2 objects will be updated
<record-1>, <record-2>
Type "yes" to confirm: yes
admin@TR7LBWAF01>
# the whole collection: the list does not open, the confirmation comes directly
admin@TR7LBWAF01> lb backend-group update-many target all --enableHcLog false
⚠ This operation will update ALL the objects in the collection
Type "yes" to confirm:
# in a script or in a pipeline: the targets are written by hand, the list does not open
admin@TR7LBWAF01> lb backend-group update-many target selected \
--ids.0 <id-1> --ids.1 <id-2> --maintenanceMode true --onError skip
admin@TR7LBWAF01>
The screen language depends on the user
The texts in the selection list and on the confirmation screen come according to the language preference of the signed-in user. The confirmation word is yes in the English interface and evet in the Turkish interface.
The detailed behavior of bulk update — which fields can be written in bulk and the report returned for each target — is on the API Commands page.
Things to Know
- The common settings belong to the group, the address to the server. The health check, SSL, the source address and the maintenance mode are applied to the whole group; the address, the port, the weight, the connection limit and the cookie value are written separately for every server.
- The index order matters. The servers are written in order in the form
--servers.0,--servers.1; in an update, writing to an existing index changes that server, writing to the next index adds a new server. - The bulk update does not carry the server fields. In the
update-manycommand the server list is not present; only the common fields at the group level can be written. The command always asks for confirmation before applying. - The name is unique. A second group with the same name cannot be created.
- The health check is a separate record. The check to be written in the
--hcfield is first created withlb hc.
