How are array / object fields (e.g. listen) entered in the CLI?

Short answer

Each item of list (array) fields is written with its own index: --listen.0.ip and --listen.0.port (Field writing rules). Nested (object) fields are written with a dot; without a prefix if they are required (addr.ip, addr.port), with -- if they are optional. Fields inside an array item are written with -- even if they are required. Multi-select fields are also written with an index (--certificate.0), and duration fields with a value and a unit (--cookieMaxIdle.val 60 --cookieMaxIdle.unit m). In the update command, writing to an index changes the item at that index; to add a new item, the current list is first viewed with lb service show and the first empty index is used. A single item is removed from the list with --listen.1.delete, and the whole list with --listen.delete.

Problem: It Is Not Known How List Fields Are Written on the Command Line

For fields that take multiple values, such as vService listeners, Backend Group servers or certificates, it must be known how they are written in WEB-CLI, how a new item is added during an update and how a single item is removed. An update command written with the wrong index changes an existing item instead of adding a new item.

Solution

Writing Rules and Examples

• How it works Array items are written with an index, object fields with a dot, and multi-selections with an index. The update command reads the existing record and changes only the fields that are written; if an item exists at the written index, the given fields of that item change, otherwise a new item is added.
• Where it is openedWEB-CLI
• Requirement CLI access for the user and the modify permission in the Load Balancer area. The --listen.N.ip value must be an IP defined on the device on the Network → Interfaces screen; Tab lists the defined IPs.
• Scope All list, object and multi-select fields in the lb branch

Step-by-Step Configuration

1

Adım 1 Choose the notation according to the field type

Field type	Notation
Array item	--listen.0.ip 192.0.2.10 --listen.0.port 443
Required object field	addr.ip 192.0.2.21 addr.port 8080
Object inside an array	--servers.0.addr.ip 192.0.2.21 --servers.0.addr.port 8080
Multi-select	--certificate.0 <certificate> --defaultBackendList.0 <backend-service>
Duration	--cookieMaxIdle.val 60 --cookieMaxIdle.unit m
Removing an item (only update)	--listen.1.delete
Emptying the list (only update)	--listen.delete

Values containing spaces or ( ) # ; are written in double quotes (Field types). The listener field of the vService is named listen in the CLI, and the type field type (lb service · The Listening Addresses).

2

Adım 2 Start the list from 0 in a new record

In the add command, the indexes are written in order starting from 0. The required fields (type, name, v-device) come first and in this order; the v-device value is selected with Tab:

lb service add type http name portal-web v-device <v-device> --listen.0.ip 192.0.2.10 --listen.0.port 443 --listen.0.ssl end --certificate.0 <certificate> --defaultBackendList.0 <backend-service>

3

Adım 3 View the current list before updating

If an item is to be added to an existing record, the list of the record is first displayed and the number of items is counted:

lb service show <vService>

4

Adım 4 Add an item with the first empty index

For example, if the listen list has only the item with index 0, the new listener is added with index 1; if it were written to index 0, the address and port of the existing listener would change:

lb service update id <vService> --listen.1.ip 192.0.2.10 --listen.1.port 80

5

Adım 5 Remove an item

The item with index 1 is removed from the list; the other items are kept:

lb service update id <vService> --listen.1.delete

6

Adım 6 Discover

While typing, Tab suggests the indexes and subfields; if ? is typed at the end of the line and Enter is pressed, the fields that can be written at that position are listed. In the update command, id is written before the record.

Verification

1RecordTR7 side

After the change, lb service show <vService> is run again; the listener rows in the vService preview in the interface can also be checked.

ExpectedOld items in place, the new item added or the removed item absent

Common Mistakes

• Writing to an existing index to add an item. In the update command, the values written to an existing index replace the values of that item; the first empty index is used for adding.
• Writing the required field in an array item without a prefix. --listen.0.ip is written, not listen.0.ip.
• Writing --servers.0.ip for Backend Group servers. The correct form is --servers.0.addr.ip and --servers.0.addr.port.
• Using the .delete notation in the add command. .delete exists only in the update command.
• Splitting the command into multiple lines. WEB-CLI runs each line as a separate command; a long command is written on a single line.

How it is done in the documentation

• lb · The Field Writing Rules
• API Commands · The field types
• lb service · The Listening Addresses
• lb service · Updating and Deleting

Related questions

• How are the lb commands grouped in the Web CLI (service, backend, backend-group, hc, certificate, ...)?
• Can I manage the Load Balancer configuration via CLI or API?
• Can I add many servers in bulk?