LiteSpeed Web ADC ZeroConfig API

The ZeroConfig feature must be set up and enabled before use. Please refer to the documentation for details.

Using ZeroConfig entails sending messages to LiteSpeed Web ADC detailing configuration for backend clusters. The API provides responses indicating success of failure.

A control interface will be available for maintenance operations in an upcoming release. The API for control messages is available for testing now, but does not yet affect the load balancing behavior.

A query interface is available for obtaining some details on the current configuration status.

The message requirements are detailed below for each message type. The curl command provides a convenient way to send messages:

DATA=my_data_file
curl --silent -X POST --data-binary $DATA https://user:password@my_load_balancer.com:my_listner_port/API_COMMAND?name=my_cluster

Messages to the ZeroConfig API receive HTTP responses, with common status codes (typically 200 for success, 400 for invalid messages / failures). Response bodies may contain data from the ZeroConfig system or error messages detailing a problem encountered while trying to process a received message.

A sample error response for a configuration message is shown below. The request returns an HTTP status code of 400, with the shown response body:

                "bip_list" :
                 ^
Error: Expected "domain_list" at line 7 at col 18
Error: Could not read vhost config at line 6 at col 18
Error: Could not read vhost list at line 4 at col 10
Error: Could not read configuration message at line 1 at col 1

ZCUP:

Cluster up message

ZCDOWN:

Cluster down message

ZCSSL:

SSL credentials message

Configuration messages are sent to LiteSpeed Web ADC using the HTTP protocol with Basic Authentication over a secure connection. Once the ZConf Listeners are configured according to the Setup section above, they will accept and process configuration messages sent to their respective IP and port.

Each configuration message must be sent to the URL composed of the ZConf Listener IP and port, with a request string specifying the configuration command and the cluster name. For URLs below, optional fields are shown between '[' and ']' characters and further explained in the notes.

The data for the command must be included in the POST body of the message in the order shown. As the '[' and ']' are used in the message format, optional fields are be shown underlined. After the initial 'conf=' string, white space is ignored between fields in the config message body.

Note that while the message is in JSON-like format, it is not generic JSON and the order must be followed as shown.

Inform LiteSpeed Web ADC that a cluster is up (or back up) and available to support backend traffic

URL: https://[user:password@]ip_addr[:port]/ZCUP?name=cluster_name

Where:

• user and password are the credentials in the ZConf password file, and are optional if authentication is not performed via the URL line.
• ip_addr is a ZConf Listener IP address, port is the ZConf Listener port (optional if the standard 443, although in most configurations it is typically set to a different port, leaving 443 available for load balancer traffic).
• cluster_name is a user assigned name for the cluster being configured.

Data:

conf={
    "vhost_list":
        [   
            {
                "domain_list" :
                    [ list of domains (strings) ],
                "conf_list" :
                    [
                        {
                            "lb_port_list" : [ list of load balancer ports (integers) ],
                            "dport" : default destination port (on backend server),
                            "be_ssl" : either true - for secure backend connections, or false ,
                            "ip_list" :
                                [
                                    { 
                                        "ip" : ip address for a serving backend (string),
                                        "port_list" : [ list of ports (integers), if needed beyond "dport" above ]
                                    }
                                    ,{ "ip" : another ip address, using "dport" }
                                    ...
                                ]
                        }
                        ,{ another config item with load balancer ports, destination ports, etc. } ... 
                    ]
            }
            ,{ another vhost_config } ... 
        ]
}

Data example:

conf=
{
    "vhost_list" :
        [
            {
                "domain_list" :
                    [ "dom1", "dom2", "dom3" ],
                "conf_list" : 
                    [
                        {
                            "lb_port_list" : [ 80 ],
                            "dport" : 80,
                            "be_ssl" : false,
                            "ip_list" :
                                [
                                    { "ip" : "192.168.1.101", "port_list" : [ 8080 ] },
                                    { "ip" : "192.168.1.102" }
                                ]
                        }
                    ]
            },
            {
                "domain_list" :
                    [ "dom4", "dom5", "dom6" ],
                "conf_list" :
                    [
                        {
                            "lb_port_list" : [ 443 ],
                            "dport" : 443,
                            "be_ssl" : true,
                            "ip_list" :
                                [
                                    { "ip" : "192.168.1.103" },
                                    { "ip" : "192.168.1.104" }
                                ]
                        }
                    ]
            }
        ]
}
 

Inform LiteSpeed Web ADC that a cluster is down and unavailable to support backend traffic

URL: https://[user:password@]ip_addr[:port]/ZCDOWN?name=cluster_name

Data:

conf={}

Provide SSL data (key, cert and CA bundle) to LiteSpeed Web ADC

URL: https://[user:password@]ip_addr[:port]/ZCSSL?name=cluster_name

Data:

conf=
{
    "ssl_list" :
        [
            {
                "domain" : a domain name (string),
                "key" : the contents (not the file name) of the private key file (string) ,
                "cert" : the contents (not the file name) of the certificate file (string) ,
                "ca_bundle" : the contents (not the file names) of the concatenated certifcate files for the CA chain (string)
            }
            , { more ssl configs } ... 
        ]
}

Data example:

conf=
{
    "ssl_list" :
        [
            {
                "domain" : "litespeedtech.com",
                "key" : "-----BEGIN RSA PRIVATE KEY----- ... " ,
                "cert" : "-----BEGIN CERTIFICATE----- ... " ,
                "ca_bundle" : "-----BEGIN CERTIFICATE----- ...",
            }
        ]
}

These messages are intended for temporary suspension and subsequent resumption of forwarding traffic to specific backend servers, such as when performing short term maintenance tasks. As noted above, this interface is only provided for API testing, and is slated for full support in an upcoming LiteSpeed Web ADC release.

ZCSUSPEND:

Temporarily cease forwarding traffic to backend servers

ZCRESUME:

Resume forwarding traffic to backend servers

LiteSpeed Web ADC will temporarily stop forwarding traffic to successfully suspended backend servers.

URL: https://[user:password@]ip_addr[:port]/ZCSUSPEND?name=cluster_name

Data:

be_list=
{
    "be_list" :
        [ 
            string containing ip:port to suspend
            , additional ip:port strings to suspend ...
        ] 
}

Data example:

be_list=
{
    "be_list" :
        [ 
            "192.168.1.111:80",
            "192.168.1.111:8080"
        ] 
}

Resume currently suspended backend servers.

URL: https://[user:password@]ip_addr[:port]/ZCRESUME?name=cluster_name

Data:

be_list={
    "be_list" :
        [
            string containing ip:port to resume
            , additional ip:port strings to resume ...
        ]
}

Data example:

be_list={
    "be_list" :
        [ 
            "192.168.1.111:80",
            "192.168.1.111:8080"
        ] 
}

These messages are used to query the current LiteSpeed Web ADC configuration.

ZCQUERY:

Look up backend servers for a specific domain / ADC port pair

ZCISUSPEND:

Look up whether forwarding traffic to specific backend servers is temporarily suspended

Find the currently mapped backend servers for a specific domain and ADC Listener port.

URL: https://[user:password@]ip_addr[:port]/ZCQUERY?name=cluster_name

Data:

query=string containing domain:lb_port to check

Data example:

query="dom1.com:443"

Sample Response:

_10.10.4.70:80;_10.10.4.71:80;_10.10.4.72:80;_10.10.4.73:80;_10.10.4.74:80;_10.10.4.75:80

Note: the 'u' (underscore) prefix indicates non-ssl backend destinations. Secure (ssl) destinations are shown with an 's' prefix.

Check whether specific backend server:port destinations are currently suspended

URL: https://[user:password@]ip_addr[:port]/ZCISUSPEND?name=cluster_name

Data:

be_list=
{
     "be_list" :
         [
             string containing backend server ip:port
             , string containing backend server ip:port ... 
         ]
}

Data example:

be_list=
{
     "be_list" :
         [
             "192.168.2.1:443",
             "192.168.2.2:443",
             "192.168.2.3:443",
             "192.168.2.4:443",
             "192.168.2.5:443"
         ]
}

Sample response:

192.168.2.1:443: Suspended
192.168.2.2:443: Suspended
192.168.2.3:443: Suspended
192.168.2.4:443: Clear
192.168.2.5:443: Suspended