What is ZCLI

zcli is the acronym of ZEVENET Command Line Interface. This tool allows managing multiple load balancers from a command line or automation of load balancer actions in the operation scripts.

zcli is a wrapper of the ZAPI (ZEVENET Application Programming Interface), it has an autocompletion feature to navigate easier through the load balancer modules and its objects.

It can be used with ZEVENET load balancers with version EE 6.1 or higher.

First steps with zcli

Installation

zcli is available in the official ZEVENET APT repositories and it can be installed in a ZEVENET load balancer using:

apt-get update && apt-get install zcli

Also, this package is also valid for any Debian, Ubuntu or any distro based in deb packages in order to launch commands remotely to your load balancers.

User Profiles

User Profiles contain the information in regards to the load balancer where the commands will be executed and the user who will execute the command. The user feature is only available for ZEVENET Enterprise and it is managed in the RBAC module, the commands will be executed depend on the user’s permissions. zcli is able to manage different profiles.

Setup

Before running zcli a ZAPI key is required. It can be enabled from the ZEVENET Web GUI, in the menu System > User.

Once zcli is installed, it can be started by executing zcli in the shell. If it is executed from the load balancer, it will run with the default profile localhost which manages the local load balancer and the ZAPI key will be requested. In any other case, the configuration assistant will be started.

If the profile settings have to be modified or another profile has to be created, the zcli profile object should be executed.

It is possible to set the profile during the zcli invocation time using the -p option like it’s shown below.

sh:~$ zcli -p my_profile

or using the command with zcli in an interactive mode:

zcli: profile apply my_profile

An example is shown below:

How it is used

zcli has two working modes:

1. Launched without arguments, the zcli shell is executed in interactive mode. This mode provides autocompletion and it does not finish once a command is executed, to exit from the zcli shell, type quit or press Ctrl+D.

2. zcli is invoked with arguments. This will execute the command, without entering into the zcli interactive shell, and the return back to the system console.

Let’s see below the commands available in the ZEVENET Command Line Interface.

Commands

A command has the following syntax:

sh:~$  zcli [   options   ] [        object      ] [action] [   ids list   ] [    parameters    ]

As an example:

sh:~$ zcli -nc -p test-lb2 farms-services-backend   set    farm1 service1 0 -ip 1.1.1.1 -port 80
           ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^   ^^^    ^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^
               options            object           action      ids list         parameters

Find below the description of every parameter.

options: They are set in the zcli invocation. The complete option list is detailed in the help.
object: It is the kind of load balancer object that is selected.
action: It is the verb that will be executed.
ids list: They are the identifiers that refer to the object. These IDs are related to the module.
parameters: They are the parameters to set in the object. Mostly, they are expected when an object is created/added or modified.

All these parameters can be used in JSON format using the -j (–json) option.

The expected command arguments can be retrieved pressing Enter. Sometimes parameters are not expanded until the previous arguments are set.

zcli has an auto-completion functionality that can be triggered pressing double TAB button.

The updated help can be checked with the command below.

sh:~$ zcli help

Output Data

The zcli prompt will change the color depending on the command error code. So the output will be shown in green if the command was successful or red if there was an error during the command execution. Also, the profile name will be printed as grey when zcli couldn’t connect to the load balancer. For such kind of errors, it is useful to review the profile configuration and the load balancer ZAPI key.

The output is printed in a colored JSON format, but they can be disabled using the option -nc (–no-colors). Some information messages could be shown, those messages are omitted when zcli is launched in command execution mode (without interactive zcli).

The error messages are displayed through the STDERR output.

Command Examples

A complete list of examples can be queried in the ZAPI documentation. Here only some useful examples:

Get system info

sh:~$ zcli system get

Get system stats

sh:~$ zcli statistic-system get

List an overview of the farms

sh:~$ zcli farm list

Create a farm

sh:~$ zcli farm create -profile http -farmname farm1 -vip 10.0.0.241 -vport 443

Retrieve the configuration of a farm

sh:~$ zcli farm get farm1

Modify a farm

sh:~$ zcli farm set farm1 -listener https

Restart a farm

sh:~$ zcli farm restart farm1

Create a service

sh:~$ zcli farm-service add farm1 -id images

Modify a service

sh:~$ zcli farm-service set farm1 images -urlp /images

Add a backend

sh:~$ zcli farm-service-backend add farm1 images -ip 10.0.4.40 -port 443

Modify a backend

sh:~$ zcli farm-service-backend set farm1 images 0 -priority 1

Delete a backend

sh:~$ zcli farm-service-backend remove farm1 images 0

Unset a backend in maintenance mode

sh:~$ zcli farm-service-backend maintenance farm1 images 0

Set a backend in maintenance mode

sh:~$ zcli farm-service-backend non_maintenance farm1 images 0

Source Code Repository

The zcli source code project is available in the URL https://github.com/zevenet/zcli

Enjoy zcli, the ZEVENET Command Line Interface!