lb service
The lb service command manages the vServices that receive the traffic. A vService carries which address and port it will listen to, to which backends and how it will distribute the traffic, and which profiles will be applied. Its panel equivalent is the vService screen.
The first field written is type
The type of the service is selected first; this selection determines which fields will open. Without the type being written, not even name is listed.
Command Summary
Writing Order
lb service add type httpname portal-web v-device <device>--listen.0.ip <address> --listen.0.port 443--defaultBackendList.0 <backend> --sslSecurity <profile>Required Fields
| Order | Field | Status | What it does | What is written after it |
|---|---|---|---|---|
| 1 | type | Required | Determines the type of the service | http · tcp · layer4 |
| 2 | name | Required | Gives a name to the service | The name of the service; it must be unique in the collection |
| 3 | v-device | Required | Selects the virtual device on which the service will run | The virtual device; Tab lists them |
The Service Types
The type determines which field group will open.
type | What it does | The field groups that open |
|---|---|---|
http | Receives the request at the application layer; operations can be performed at the header, path and cookie level | The listening addresses · the backend · the distribution · the persistence · all the profiles · WAF, AGS, protection · the resource management |
tcp | Receives the connection at the transport layer | The listening addresses · the backend · the distribution · the persistence · the profiles (except compression and cache) · the protection · the resource management |
layer4 | Distributes the packets directly; the application layer operations are not performed | The listening addresses · the backend · the Layer4 fields |
--compression, --cache, --ags, --forwardfor and --trustedProxy exist only in the http type; --algorithm, --persistence, --engine, --qos and --sslSecurity exist in the http and tcp types.
The Listening Addresses
Determines from which addresses and ports the service will be listened to. Every address is written with its own index.
| Field | What it does | What is written after it |
|---|---|---|
--listen.N.ip | Determines the address that the service will listen to | An IP address defined on the virtual device; every address with its own index |
--listen.N.port | Determines the port that the service will listen to | The port number |
--listen.N.ssl | Selects how the TLS termination will be done on that address | The TLS termination option |
--listen.N.quic | Turns on the HTTP/3 (QUIC) support on that address | true · false (default false) |
--virtualHosting.N | Determines which domain names the service will answer | A domain name; each with its own index |
--certificate.N | Selects the certificates that the service will present | The lb certificate records; each with its own index |
Binding the Backend
Determines where the traffic will go. The conditional sets have priority over the default list.
| Field | What it does | What is written after it |
|---|---|---|
--defaultBackendList.N | Selects the backends to which the traffic will go by default | The lb backend or lb backend-group records |
--dynamicBackendList.N.beGroup | Gives an id to the condition-bound backend set | The set id |
--dynamicBackendList.N.beList.N | Selects the backends that will be used in that set | Backend or group records |
--dynamicBackendList.N.cond | Determines in which traffic the set will be used | A condition expression; it is built from the lb condition records |
The Distribution Algorithm
Determines how the traffic will be shared among the backends. Some algorithms open their own additional fields.
| Field | What it does | What is written after it |
|---|---|---|
--algorithm | Selects how the traffic will be distributed to the backends | roundrobinNoWeight (default) · roundrobin · leastconn · leasttime · leastbw · first · random · fastestWith · fastestWith+ · source · urilen · urlparam · hdr · rdp-cookie |
--leasttimeMetric | Selects which time the least time algorithm will measure | total the total time (default) · resp the response time. It opens while --algorithm leasttime |
--leastbwWindow.val | Determines the window of the bandwidth measurement | A number (default 10) |
--leastbwWindow.unit | Determines the unit of the bandwidth window | A unit (default s) |
--uriLen | Determines the number of URI characters to be hashed | A number between 1 and 10000 (default 50); it opens while --algorithm urilen |
--uriDepth | Determines the path depth to be hashed | A number between 1 and 100; it opens while --algorithm urilen |
--urlParamKey | Determines the query parameter to be used in the distribution | The parameter name; it opens while --algorithm urlparam |
--checkPost | Makes the parameter be searched in the request body too | true · false (default false); it opens while --algorithm urlparam |
--hdrName | Determines the header to be used in the distribution | The header name; it opens while --algorithm hdr |
--rdpCookieName | Determines the RDP cookie to be used in the distribution | The cookie name; it opens while --algorithm rdp-cookie |
--hashConsistency | Turns on the use of consistent hashing in the hash-based distribution | true · false (default false) |
--fastestOpt1 | Determines the first criterion of the fastest backend selection | The criterion value |
--fastestOpt2 | Determines the second criterion of the fastest backend selection | The criterion value |
Server Persistence
Makes the same client be directed to the same backend. The selected method opens its own fields.
| Field | What it does | What is written after it |
|---|---|---|
--persistence | Selects the method that makes the same client go to the same backend | tr7Cookie the cookie produced by TR7 · serverCookie the cookie of the backend · dynamicPersistence according to a variable · sam session aware. When it is left empty, persistence is not applied |
--tr7CookieName | Determines the name of the persistence cookie that TR7 will produce | The cookie name; it opens while --persistence tr7Cookie |
--serverCookieName | Determines which cookie produced by the backend will be tracked | The cookie name; it opens while --persistence serverCookie |
--cookieMaxIdle.val | Determines the time that the cookie can stay idle | A number (default 30) |
--cookieMaxIdle.unit | Determines the unit of the idle time | A unit (default m) |
--cookieMaxLife.val | Determines the total life of the cookie | A number (default 30) |
--cookieMaxLife.unit | Determines the unit of the cookie life | A unit (default m) |
--dynamicPersistenceKeys.N | Determines according to which variable the persistence will be established | A smart variable; it opens while --persistence dynamicPersistence |
--dynamicPersistenceTableSize | Determines how many records the persistence table will hold | A number (default 3000000) |
--dynamicPersistenceTableExpire.val | Determines how long the record in the table will be kept | A number (default 7) |
--dynamicPersistenceTableExpire.unit | Determines the unit of the keeping time | A unit (default d) |
--samCookieSource | Selects who will produce the session cookie | tr7 TR7 produces it (default) · backend the backend produces it. It opens while --persistence sam |
--samCookieName | Determines the name of the session cookie | The cookie name |
--samMaxLife.val | Determines the total life of the session | A number (default 24) |
--samMaxLife.unit | Determines the unit of the session life | A unit (default h) |
--samMaxIdle.val | Determines the time that the session can stay idle | A number (default 30) |
--samMaxIdle.unit | Determines the unit of the idle time | A unit (default m) |
--samSecurityFlags.N | Selects the security flags to be added to the session cookie | httpOnly (default) · secure · sameSiteStrict · sameSiteLax |
--samSessionFormat | Selects the format of the session id | ipTimestampRandom (default) · uuid · ipRandom · custom |
--samCustomFormatKeys.N | Determines the variables that make up the custom session id | A smart variable; it is used while --samSessionFormat custom |
The Bound Profiles
The profiles determine the behavior of the service; each one is created with a separate command.
| Field | What it does | What is written after it |
|---|---|---|
--sslSecurity | Selects the TLS profile to be applied on the listening side | The lb ssl-security record (default default) |
--trustedProxy | Selects the profile that determines from which intermediate servers the client address will be read | A trusted proxy profile |
--compression | Selects the profile that manages the compression of the responses | The lb compression record |
--cache | Selects the profile that manages the caching of the responses | The lb cache record |
--log | Selects the profile that determines where the traffic logs will go | The lb log record |
--notification | Selects the notification profile | The lb notification record |
--extraNotificationProfiles.N | Binds additional notification profiles | Notification profile records |
--reportProfile | Selects the main report profile | The lb report record |
--extraReportProfiles.N | Binds additional report profiles | Report profile records |
--poolLimits | Selects the limit profile to be applied to the listening service | The lb limits record |
--timeout | Selects the timeout profile | The lb timeouts record |
The Protection and Processing Switches
Turns on the layers to be applied to the traffic that passes over the service.
| Field | What it does | What is written after it |
|---|---|---|
--waf | Turns on the web application firewall | true · false (default false) |
--ags | Turns on the access gateway | true · false (default false) |
--threatProtection | Turns on the traffic protection layer | true · false (default false) |
--forwardfor | Turns on the addition of the X-Forwarded-For header that carries the address of the client to the backend | true · false (default false) |
--rules.N | Binds the actions to be applied to the service | The lb action records; each with its own index |
--bw | Turns on the bandwidth limiting | true · false (default false) |
--downloadBwPool | Determines the total download bandwidth limit of the service | A number; it opens while --bw true |
Resource Management
Determines the processor, memory and core resources to be allocated to the service. Most of the fields open when --qos true is written.
| Field | What it does | What is written after it |
|---|---|---|
--qos | Turns on the resource management allocated to the service | true · false (default false) |
--engine | Determines on which core engine the service will run | The engine name |
--poolCores.N | Determines the core numbers to be allocated to the service | A number between 0 and 64; it opens while --qos true |
--memoryLimit | Selects the memory limit that the service can use | A byte value (default 1073741824); it opens while --qos true |
--cpuPriority | Selects the processor priority of the service | low (default) · normal · high; it opens while --qos true |
--cpuLimit | Limits the processor percentage that the service can use | A percentage value; it opens while --qos true |
--inlineMode | Turns on the service running in inline mode | true · false (default false); it opens while --qos true |
--logNamespace | Selects from which route table the logs will be sent | A route table (default 1); it opens while --qos true |
The Layer4 Fields
It exists only in the services of the layer4 type.
| Field | What it does | What is written after it |
|---|---|---|
--l4Namespace | Selects which route table the Layer4 service will use | A route table (default 1) |
--l4Protocol | Selects the protocol of the Layer4 service | tcp (default) · udp · any |
--l4LbMode | Selects the Layer4 distribution mode | DR direct return (default) · NAT the routing mode · SNAT |
--l4Algorithm | Selects the Layer4 distribution algorithm | rr (default) · wrr · lc · lblc · wlc · sh · dh |
--l4PortRange | Turns on port range listening | true · false (default false) |
--l4Persistence.val | Determines the Layer4 persistence time | A number |
--l4Persistence.unit | Determines the unit of the persistence time | A unit (default ms) |
--l4SipPersistence | Turns on persistence for the SIP traffic | true · false (default false) |
--l4SnatIp | Selects the source address to be used in the Layer4 SNAT mode | An address; it is used while --l4LbMode SNAT |
Debugging
Makes detailed logs be produced while a problem is being examined.
| Field | What it does | What is written after it |
|---|---|---|
--debugMode | Turns on the detailed debugging log | true · false (default false) |
--debugModeConditions | Makes the debugging run only on certain traffic | A condition expression |
--debugLogEntries.N.key | Determines the name of the field to be added to the debugging log | The field name |
--debugLogEntries.N.value | Determines the value of that field | A smart variable |
Restarting and Status
| Command | What it does | Fields |
|---|---|---|
lb service restart poolId <vService> | Restarts the service | poolId Required which service · --hardReload starts it without waiting for the connections |
lb service status list | Lists the running status of all the services | --output · --filter |
lb service status id <vService> | Shows the status of a single service | poolId which service |
| Order | Field | Status | Value |
|---|---|---|---|
| 1 | poolId | Required | The vService to be restarted in the restart command; it is written together with the field name. In the status id command the field name is not written, the vService is written directly as the value |
Examples
Updating and Deleting
Bulk Update
update-many applies the same change to many vService records at once. The writing order is the same on every resource.
target: selected for the records selected from the list, all for the entire collection. target selected is written and no id is given, a selection list with checkboxes opens. | 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
There are 69 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 |
|---|---|---|
--active | Determines whether the service is in running state or not | true (default) · false |
--ags | Turns on the access gateway | true · false (default false) |
--algorithm | Selects how the traffic will be distributed to the backends | roundrobinNoWeight (default) · roundrobin · leastconn · leasttime · leastbw · first · random · fastestWith · fastestWith+ · source · urilen · urlparam · hdr · rdp-cookie |
--bw | Turns on the bandwidth limiting | true · false (default false) |
--cache | Selects the profile that manages the caching of the responses | The lb cache record |
--certificate.N | Selects the certificates that the service will present | The lb certificate records; each with its own index |
--checkPost | Makes the parameter be searched in the request body too | true · false (default false); it opens while --algorithm urlparam |
--compression | Selects the profile that manages the compression of the responses | The lb compression record |
--cookieMaxIdle | Determines the time that the persistence cookie can stay idle | A duration (default 30 minutes) |
--cookieMaxLife | Determines the total life of the persistence cookie | A duration (default 30 minutes) |
--cpuLimit | Limits the processor percentage that the service can use | A percentage value; it opens while --qos true |
--cpuPriority | Selects the processor priority of the service | low (default) · normal · high; it opens while --qos true |
--debugLogEntries.N.key | Determines the name of the field to be added to the debugging log | The field name |
--debugLogEntries.N.value | Determines the value of that field | A smart variable |
--debugMode | Turns on the detailed debugging log | true · false (default false) |
--debugModeConditions | Makes the debugging run only on certain traffic | A condition expression |
--defaultBackendList.N | Selects the backends to which the traffic will go by default | The lb backend or lb backend-group records |
--downloadBwPool | Determines the total download bandwidth limit of the service | A number; it opens while --bw true |
--dynamicBackendList.N.beGroup | Gives an id to the condition-bound backend set | The set id |
--dynamicBackendList.N.beList.N | Selects the backends that will be used in that set | Backend or group records |
--dynamicBackendList.N.cond | Determines in which traffic the set will be used | A condition expression; it is built from the lb condition records |
--dynamicPersistenceKeys.N | Determines according to which variable the persistence will be established | A smart variable; it opens while --persistence dynamicPersistence |
--dynamicPersistenceTableExpire | Determines the keeping time of the record in the persistence table | A duration (default 7 days) |
--dynamicPersistenceTableSize | Determines how many records the persistence table will hold | A number (default 3000000) |
--engine | Determines on which core engine the service will run | The engine name |
--extraNotificationProfiles.N | Binds additional notification profiles | Notification profile records |
--extraReportProfiles.N | Binds additional report profiles | Report profile records |
--forwardfor | Turns on the addition of the X-Forwarded-For header that carries the address of the client to the backend | true · false (default false) |
--hashConsistency | Turns on the use of consistent hashing in the hash-based distribution | true · false (default false) |
--hdrName | Determines the header to be used in the distribution | The header name; it opens while --algorithm hdr |
--info | Writes what the command will do without running it | It does not take a value; it is written on its own |
--inlineMode | Turns on the service running in inline mode | true · false (default false); it opens while --qos true |
--l4Algorithm | Selects the Layer4 distribution algorithm | rr (default) · wrr · lc · lblc · wlc · sh · dh |
--l4LbMode | Selects the Layer4 distribution mode | DR direct return (default) · NAT the routing mode · SNAT |
--l4Persistence | Determines the Layer4 persistence time | A duration |
--l4PortRange | Turns on port range listening | true · false (default false) |
--l4Protocol | Selects the protocol of the Layer4 service | tcp (default) · udp · any |
--l4SipPersistence | Turns on persistence for the SIP traffic | true · false (default false) |
--leastbwWindow | Determines the bandwidth measurement window | A duration (default 10 seconds) |
--leasttimeMetric | Selects which time the least time algorithm will measure | total the total time (default) · resp the response time. It opens while --algorithm leasttime |
--log | Selects the profile that determines where the traffic logs will go | The lb log record |
--memoryLimit | Selects the memory limit that the service can use | A byte value (default 1073741824); it opens while --qos true |
--notification | Selects the notification profile | The lb notification record |
--onError | Determines what will happen if a target does not pass the validation | abort writes nothing (default) · skip writes the targets that pass |
--persistence | Selects the method that makes the same client go to the same backend | tr7Cookie the cookie produced by TR7 · serverCookie the cookie of the backend · dynamicPersistence according to a variable · sam session aware. When it is left empty, persistence is not applied |
--poolCores.N | Determines the core numbers to be allocated to the service | A number between 0 and 64; it opens while --qos true |
--poolLimits | Selects the limit profile to be applied to the listening service | The lb limits record |
--qos | Turns on the resource management allocated to the service | true · false (default false) |
--rdpCookieName | Determines the RDP cookie to be used in the distribution | The cookie name; it opens while --algorithm rdp-cookie |
--reportProfile | Selects the main report profile | The lb report record |
--rules.N | Binds the actions to be applied to the service | The lb action records; each with its own index |
--samCookieName | Determines the name of the session cookie | The cookie name |
--samCookieSource | Selects who will produce the session cookie | tr7 TR7 produces it (default) · backend the backend produces it. It opens while --persistence sam |
--samCustomFormatKeys.N | Determines the variables that make up the custom session id | A smart variable; it is used while --samSessionFormat custom |
--samMaxIdle | Determines the time that the session can stay idle | A duration (default 30 minutes) |
--samMaxLife | Determines the total life of the session | A duration (default 24 hours) |
--samSecurityFlags.N | Selects the security flags to be added to the session cookie | httpOnly (default) · secure · sameSiteStrict · sameSiteLax |
--samSessionFormat | Selects the format of the session id | ipTimestampRandom (default) · uuid · ipRandom · custom |
--serverCookieName | Determines which cookie produced by the backend will be tracked | The cookie name; it opens while --persistence serverCookie |
--sslSecurity | Selects the TLS profile to be applied on the listening side | The lb ssl-security record (default default) |
--threatProtection | Turns on the traffic protection layer | true · false (default false) |
--timeout | Selects the timeout profile | The lb timeouts record |
--tr7CookieName | Determines the name of the persistence cookie that TR7 will produce | The cookie name; it opens while --persistence tr7Cookie |
--trustedProxy | Selects the profile that determines from which intermediate servers the client address will be read | A trusted proxy profile |
--uriDepth | Determines the path depth to be hashed | A number between 1 and 100; it opens while --algorithm urilen |
--uriLen | Determines the number of URI characters to be hashed | A number between 1 and 10000 (default 50); it opens while --algorithm urilen |
--urlParamKey | Determines the query parameter to be used in the distribution | The parameter name; it opens while --algorithm urlparam |
--virtualHosting.N | Determines which domain names the service will answer | A domain name; each with its own index |
--waf | Turns on the web application firewall | true · false (default false) |
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 that can be selected; its value depends on the sibling fields |
type | The type of the service determines the identity of the record; it cannot be changed in bulk |
listen.N.ip | The listening address is specific to the record and depends on the virtual device |
listen.N.port | It is part of the same address object |
listen.N.ssl | It is part of the same address object |
listen.N.quic | It is part of the same address object |
l4Namespace | The route table depends on the virtual device |
l4SnatIp | The address comes from the list of the selected virtual device |
fastestOpt1 | Its value depends on the sibling fields |
fastestOpt2 | Its value depends on the sibling fields |
Target Selection and Confirmation
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 type determines the fields. After
typeis selected, only the fields of that type are listed; in thelayer4type the application layer fields (WAF, AGS, compression, cache, actions) do not open at all. - The conditional backend set comes before the default list. In a request where
--dynamicBackendList.N.condmatches, the backends in that set are used; if there is no match,--defaultBackendList.Ncomes into play. - The algorithm opens its own fields. When
urilen,urlparam,hdr,rdp-cookie,leasttimeandleastbware selected, additional fields are asked for beside them. - The persistence method opens its own fields. Each of the
tr7Cookie,serverCookie,dynamicPersistenceandsamoptions brings a different field set. - The resource fields depend on QoS.
--poolCores.N,--memoryLimit,--cpuPriority,--cpuLimit,--inlineModeand--logNamespaceopen only when--qos trueis written. - Restarting can create an interruption.
--hardReload truestarts the service without waiting for the open connections to finish. - The name is unique. A second vService with the same name cannot be created.
