Differences

This shows you the differences between two versions of the page.

--- litespeed_wiki:lslb:zconf [2019/07/23 13:13]
Kevin Fwu [ZCUP Message]
+++ litespeed_wiki:lslb:zconf [2020/11/18 15:36] (current)
Lisa Clarke Redirect to new Documentation Site
@@ Line 1: / Line 1: @@
-====== LiteSpeed Web ADC ZeroConfig API ======
+~~REDIRECT>https://docs.litespeedtech.com/products/lsadc/cache/~~
-The ZeroConfig feature must be set up and enabled before use. Please refer to [[https://www.litespeedtech.com/docs/litespeed-web-adc/config/zconf|the 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:
-<html><pre class="code">
-DATA=<i>my_data_file</i>
-curl --silent -X POST --data-binary $DATA https://<i>user:password</i>@<i>my_load_balancer.com:my_listner_port</i>/<i>API_COMMAND</i>?name=<i>my_cluster</i>
-</pre>
-<p><b>The fields <i>user</i> and <i>my_cluster</i> must NOT contain ':' (colon) characters.</b></html>
-==== 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:
-<html><pre class="code">
-                "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
-</pre></html>
-===== API Configuration Messages =====
-<html>
-<style>
-dt {
-  display: inline-block;
-  float: left;
-  clear: left;
-  margin-right: 10px;
-  font-weight: bold;
-  }
-dd {
-  display: inline;
-  }
-</style>
-<div><dl>
-<dt>ZCUP:<dt><dd>Cluster up message</dd><br />
-<dt>ZCDOWN:<dt><dd>Cluster down message</dd><br />
-<dt>ZCSSL:<dt><dd>Add SSL credentials message<br /></dd>
-<dt>ZCSSLRELEASE:<dt><dd>Delete SSL credentials message<br /></dd>
-<dt>ZCOWNRRELEASE:<dt><dd>Relinquish ownership of config records</dd></dl></div>
-</html>
-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: ''<nowiki>https://[user:password@]ip_addr[:port]/ZCUP?name=cluster_name</nowiki>''
-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:
-<html><pre class="code">
-conf={
-    "vhost_list":
-        [
-            {
-                <u>"template" : "<i>VHost template name</i>",</u>
-                "domain_list" :
-                    [ <i>list of domains (strings)</i> ],
-                "conf_list" :
-                    [
-                        {
-                            "lb_port_list" : [ <i>list of load balancer ports (integers)</i> ],
-                            "dport" : <i>default destination port (on backend server)</i>,
-                            "be_ssl" : <i>either</i> <b>true</b> <i>- for secure backend connections, or</i> <b>false</b> ,
-                            "ip_list" :
-                                [
-                                    {
-                                        "ip" : <i>ip address for a serving backend (string)</i>,
-                                        <u>"port_list" : [ <i>list of ports (integers), if needed beyond "dport" above</i> ]</u>
-                                    }
-                                    <u>,{ "ip" : <i>another ip address, using "dport"</i> }</u>
-                                    <u>...</u>
-                                ]
-                        }
-                        <u>,{ <i>another config item with load balancer ports, destination ports, etc.</i> } ... </u>
-                    ]
-            }
-            <u>,{ <i>another vhost_config</i> } ... </u>
-        ]
-}
-</pre></html>
-Data example:
-<code>
-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" }
-                                ]
-                        }
-                    ]
-            }
-        ]
-}
- </code>
-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: ''<nowiki>https://[user:password@]ip_addr[:port]/ZCDOWN?name=cluster_name</nowiki>''
-Data:
-<code>conf={}</code>
-==== ZCSSL Message ====
-Provide SSL data (key, cert and CA bundle) to LiteSpeed Web ADC
-URL: ''<nowiki>https://[user:password@]ip_addr[:port]/ZCSSL?name=cluster_name</nowiki>''
-Data:
-<html><pre class="code">
-conf=
-{
-    "ssl_list" :
-        [
-            {
-                "domain_list" : [ <i>a domain name (string)</i> <u>, more quoted domain names separated by commas </u> ],
-                "key" : <i>the <b>contents</b> (<b>not</b> the file name) of the private key file (string)</i> ,
-                "cert" : <i>the <b>contents</b> (<b>not</b> the file name) of the certificate file (string)</i> ,
-                "ca_bundle" : <i>the <b>contents</b> (<b>not</b> the file names) of the concatenated certifcate files for the CA chain (string)</i>
-            }
-            <u>, { <i>more ssl configs</i> } ... </u>
-        ]
-}
-</pre></html>
-Data example:
-<code>
-conf=
-{
-    "ssl_list" :
-        [
-            {
-                "domain_list" : [ "litespeedtech.com", "blog.litespeedtech.com" ],
-                "key" : "-----BEGIN RSA PRIVATE KEY----- ... " ,
-                "cert" : "-----BEGIN CERTIFICATE----- ... " ,
-                "ca_bundle" : "-----BEGIN CERTIFICATE----- ...",
-            }
-        ]
-}
-</code>
-==== ZCSSLRELEASE Message ====
-Delete SSL data (key, cert and CA bundle) for specified domains from LiteSpeed Web ADC
-URL: ''<nowiki>https://[user:password@]ip_addr[:port]/ZCSSLRELEASE?name=cluster_name</nowiki>''
-Data:
-<html><pre class="code">
-conf=
-{
-    "ssl_list" :
-        [
-            {
-                "domain_list" : [ <i>a domain name (string)</i> <u>, more quoted domain names separated by commas </u> ]            }
-            <u>, { <i>more ssl configs</i> } ... </u>
-        ]
-}
-</pre></html>
-Data example:
-<code>
-conf=
-{
-    "ssl_list" :
-        [
-            {
-                "domain_list" : [ "litespeedtech.com", "blog.litespeedtech.com" ]
-            }
-        ]
-}
-</code>
-==== 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: ''<nowiki>https://[user:password@]ip_addr[:port]/ZCOWNRRELEASE?name=cluster_name</nowiki>''
-Data:
-<html><pre class="code">
-conf=
-{
-    "domain_list" : [ <i>a domain name (string)</i> <u>, more quoted domain names separated by commas </u> ]
-}
-</pre></html>
-Data example:
-<code>
-conf=
-{
-     "domain_list" : [ "litespeedtech.com", "blog.litespeedtech.com" ]
-}
-</code>
-===== 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.
-<html>
-<dl>
-<dt>ZCSUSPEND:<dt><dd>Temporarily cease forwarding traffic to backend servers</dd><br />
-<dt>ZCRESUME:<dt><dd>Resume forwarding traffic to backend servers</dd>
-</dl>
-</html>
-==== ZCSUSPEND Message ====
-LiteSpeed Web ADC will temporarily stop forwarding traffic to successfully suspended backend servers.
-URL: ''<nowiki>https://[user:password@]ip_addr[:port]/ZCSUSPEND?name=cluster_name</nowiki>''
-Data:
-<html><pre class="code">
-be_list=
-{
-    "be_list" :
-        [
-            <i>string containing ip:port to suspend</i>
-            <u>, <i>additional ip:port strings to suspend ...</i></u>
-        ]
-}
-</pre></html>
-Data example:
-<code>
-be_list=
-{
-    "be_list" :
-        [
-            "192.168.1.111:80",
-            "192.168.1.111:8080"
-        ]
-}
-</code>
-==== ZCRESUME Message ====
-Resume currently suspended backend servers.
-URL: ''<nowiki>https://[user:password@]ip_addr[:port]/ZCRESUME?name=cluster_name</nowiki>''
-Data:
-<html><pre class="code">
-be_list=
-{
-    "be_list" :
-        [
-            <i>string containing ip:port to resume</i>
-            <u>, <i>additional ip:port strings to resume ...</i></u>
-        ]
-}
-</pre></html>
-Data example:
-<code>
-be_list=
-{
-    "be_list" :
-        [
-            "192.168.1.111:80",
-            "192.168.1.111:8080"
-        ]
-}
-</code>
-===== API Status Messages =====
-These messages are used to query the current LiteSpeed Web ADC configuration.
-<html>
-<dl>
-<dt>ZCQUERY:<dt><dd>Look up backend servers for a specific domain / ADC port pair</dd><br />
-<dt>ZCISUSPEND:<dt><dd>Look up whether forwarding traffic to specific backend servers is temporarily suspended</dd>
-</dl>
-</html>
-==== ZCQUERY Message ====
-Find the currently mapped backend servers for a specific domain and ADC Listener port.
-URL: ''<nowiki>https://[user:password@]ip_addr[:port]/ZCQUERY?name=cluster_name</nowiki>''
-Data:
-<html><pre class="code">query=<i>string containing domain:lb_port to check</i></pre></html>
-Data example:
-<code>query="dom1.com:443"</code>
-Sample Response:
-<code>_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</code>
-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: ''<nowiki>https://[user:password@]ip_addr[:port]/ZCISUSPEND?name=cluster_name</nowiki>''
-Data:
-<html><pre class="code">
-be_list=
-{
-     "be_list" :
-         [
-             <i>string containing backend server ip:port</i>
-             <u>, <i>string containing backend server ip:port</i> ... </u>
-         ]
-}
-</pre></html>
-Data example:
-<code>
-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"
-         ]
-}
-</code>
-Sample response:
-<code>
-.168.2.1:443: Suspended
-.168.2.2:443: Suspended
-.168.2.3:443: Suspended
-.168.2.4:443: Clear
-.168.2.5:443: Suspended
-</code>