API
The ZeroConfig feature must be set up and enabled before use. Please refer to the configuration documentation for details.
Using ZeroConfig entails sending messages to LiteSpeed Web ADC detailing configuration for backend clusters. The API provides responses indicating success or 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.
Sending ZeroConfig API Messages
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
The fields user and my_cluster must NOT contain ':' (colon) characters.
Handling ZeroConfig API Responses
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
API Configuration Messages
ZCUP: Cluster up message ZCDOWN: Cluster down message ZCSSL: Add SSL credentials message ZCSSLRELEASE: Delete SSL credentials message ZCOWNRRELEASE: Relinquish ownership of config records
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.
ZCUP Message
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.
Tip:
A ZeroConf VHost is NOT the same as an ADC VHost. VHost in the context of a ZeroConf ZCUP message is defined as the list of domains that share the conf_list and template. A single VHost configuration can include thousands of domains as long as they share the conf_list. For example, if there is a backend server with 1000 domains that are listening to port 443, they can share a vhost.
Data:
conf={
"vhost_list":
[
{
"template" : "VHost template name",
"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" }
]
}
]
},
{
"template" : "noCacheTemplate"
"domain_list" :
[ "dom7", "dom8", "dom9" ],
"conf_list" :
[
{
"lb_port_list" : [ 443 ],
"dport" : 443,
"be_ssl" : true,
"ip_list" :
[
{ "ip" : "192.168.1.103" },
{ "ip" : "192.168.1.104" }
]
}
]
}
]
}
Note: * Templates introduced in ADC version 2.4 build 11.
ZCDOWN Message
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={}
ZCSSL Message
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_list" : [ a domain name (string) , more quoted domain names separated by commas ],
"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_list" : [ "litespeedtech.com", "blog.litespeedtech.com" ],
"key" : "-----BEGIN RSA PRIVATE KEY----- ... " ,
"cert" : "-----BEGIN CERTIFICATE----- ... " ,
"ca_bundle" : "-----BEGIN CERTIFICATE----- ...",
}
]
}
ZCSSLRELEASE Message
Delete SSL data (key, cert and CA bundle) for specified domains from LiteSpeed Web ADC
URL: https://[user:password@]ip_addr[:port]/ZCSSLRELEASE?name=cluster_name
Data:
conf=
{
"ssl_list" :
[
{
"domain_list" : [ a domain name (string) , more quoted domain names separated by commas ] }
, { more ssl configs } ...
]
}
Data example:
conf=
{
"ssl_list" :
[
{
"domain_list" : [ "litespeedtech.com", "blog.litespeedtech.com" ]
}
]
}
ZCOWNRRELEASE Message
Relinquish ownership of any configuration records for specified domains from LiteSpeed Web ADC (allows specified domains to be owned by a different authorized user, such as when transferring to another provider).
URL: https://[user:password@]ip_addr[:port]/ZCOWNRRELEASE?name=cluster_name
Data:
conf=
{
"domain_list" : [ a domain name (string) , more quoted domain names separated by commas ]
}
Data example:
conf=
{
"domain_list" : [ "litespeedtech.com", "blog.litespeedtech.com" ]
}
API Control Messages
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
ZCSUSPEND Message
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"
]
}
ZCRESUME Message
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"
]
}
API Status Messages
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
ZCQUERY Message
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 '_' (underscore) prefix indicates non-ssl backend destinations. Secure (ssl) destinations are shown with an 's' prefix.
ZCISUSPEND Message
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