API

Using ZeroConf 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 ZeroConf API Messages

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

  • BASICAUTH_USER - The configured basic auth user name.
  • BASICAUTH_PASSWORD - The configured basic auth password.
  • LSADC_IP - The LSADC IP.
  • LSADC_ZEROCONF_PORT - The configured port for ZeroConf messages on the ADC.
  • API_COMMAND - The command to issue, listed below.
  • UNQ_BACKEND_NAME - This name should uniquely identify this backend server. It is used as an identifier for uploaded configurations.
DATA=/path/to/data/file
curl --silent -X POST --data-binary $DATA https://BASICAUTH_USER:BASICAUTH_PASSWORD@LSADC_IP:LSADC_ZEROCONF_PORT/API_COMMAND?name=UNQ_BACKEND_NAME

Handling ZeroConf API Responses

Messages to the ZeroConf API receive HTTP responses, with common status codes (typically 200 for success, 400 for invalid messages / failures). Response bodies may contain data from the ZeroConf 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 ZeroConf 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 ZeroConf 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

The configuration is a list of vhost objects. Each vhost object's configurations are not correlated with each other.

  • (optional) template: The name of the template to use with the !!!(WORD CHOICE)!!!paired domains. If not set, the domains will use the ADC's server default settings.
  • domain_list: The list of domains that will utilize this vhost definition.
  • conf_list: List of LB port -> Backend Port combinations. Each port combination should be its own object.
  • lb_port_list: The list of ports to associate with the backend port.
  • dport: The backend port to forward the requests to.
  • be_ssl: true/false defining whether the backend is an SSL backend or plaintext.
  • ip_list: List of IPs to mark as the backend. Each IP should be its own object.
    • ip: A backend IP.
    • (optional) port_list: A comma delimited list of ports (integers), if different than dport.

Message Format:

conf={
  "vhost_list":
    [
      {
        "template" : "TEMPLATE_NAME",
        "domain_list" :
          [ "example1.com", "example2.com", "example3.com" ],
        "conf_list" :
          [
            {
              "lb_port_list" : [ 80 ],
              "dport" : 80,
              "be_ssl" : false,
              "ip_list" :
                [
                  {
                    "ip" : "10.10.40.153",
                    "port_list" : [ PORT1, PORT2 ]
                  }
                ]
            }
          ]
      }
    ]
}
conf=
{
  "vhost_list" :
    [
      {
        "domain_list" :
          [ "example1.com", "sub.example1.com", "example2.com" ],
        "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" :
          [ "example1.com", "sub.example1.com", "example2.com", "secureonly.example.com" ],
        "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" :
          [ "nocachedom.example.com", "nocachedom2.example.com", "nocache3.com" ],
        "conf_list" :
          [
            {
              "lb_port_list" : [ 443 ],
              "dport" : 443,
              "be_ssl" : true,
              "ip_list" :
                [
                  { "ip" : "192.168.1.103" },
                  { "ip" : "192.168.1.104" }
                ]
            }
          ]
      }
    ]
}

The sample data above should be in the data file when sending via command line. The API_COMMAND should be ZCUP.

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.

Note

Templates introduced in ADC version 2.4 build 11.

The example ZCUP configuration includes three vhosts. The second and third conf lists are identical; the only difference is the domain list and a template configuration in the third VHost.

The second VHost uses the server level configurations. The third VHost uses the VHost Template named noCacheTemplate configured in the ADC.

ZCDOWN Message

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

Message Format:

conf={}

The sample data above should be in the data file when sending via command line. The API_COMMAND should be ZCDOWN.

ZCSSL Message

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

The configuration is a list of SSL configuration objects.

  • domain_list: The list of domains that will utilize this ssl definition.
  • key: The SSL Private Key the domains should use. This is NOT the file name.
  • cert: The SSL certificate the domains should use. This is NOT the file name.
  • ca_bundle: The SSL CA bundle that is associated with the certificate. This is NOT the file name.
conf={
  "ssl_list":
    [
      {
        "domain_list" :
          [ "example1.com", "example2.com", "example3.com" ],
        "key" : "PRIVATE_KEY",
        "cert" : "CERTIFICATE",
        "ca_bundle" : "CERT_CHAIN"
      }
    ]
}
conf={
  "ssl_list":
    [
      {
        "domain_list" :
          [ "example1.com", "example2.com", "example3.com" ],
        "key" : "-----BEGIN RSA PRIVATE KEY----- ... ",
        "cert" : "-----BEGIN CERTIFICATE----- ... ",
        "ca_bundle" : "-----BEGIN CERTIFICATE----- ..."
      }
    ]
}

The sample data above should be in the data file when sending via command line. The API_COMMAND should be ZCSSL.

ZCSSLRELEASE Message

Delete SSL data (key, cert and CA bundle) for specified domains from LiteSpeed Web ADC

conf={
  "ssl_list":
    [
      {
        "domain_list" :
          [ "example1.com", "example2.com", "example3.com" ]
      }
    ]
}
conf={
  "ssl_list":
    [
      {
        "domain_list" :
          [ "example1.com", "example2.com", "example3.com" ]
      }
    ]
}

The sample data above should be in the data file when sending via command line. The API_COMMAND should be ZCSSLRELEASE.

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).

conf={
  "domain_list" : [ "example1.com", "example2.com", "example3.com" ]
}
conf={
  "domain_list" : [ "example1.com", "example2.com", "example3.com" ]
}

The sample data above should be in the data file when sending via command line. The API_COMMAND should be ZCOWNRRELEASE.

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.

be_list={
  [
    "IP1:PORT",
    "IP2:PORT",
    "IP3:PORT"
  ]
}
be_list={
  [
    "192.168.1.111:80",
    "192.168.1.111:8080"
  ]
}

The sample data above should be in the data file when sending via command line. The API_COMMAND should be ZCSUSPEND.

ZCRESUME Message

Resume currently suspended backend servers.

be_list={
  [
    "IP1:PORT",
    "IP2:PORT",
    "IP3:PORT"
  ]
}
be_list={
  [
    "192.168.1.111:80",
    "192.168.1.111:8080"
  ]
}

The sample data above should be in the data file when sending via command line. The API_COMMAND should be ZCRESUME.

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.

query="IP:PORT"
query="192.168.1.111:80"

The sample data above should be in the data file when sending via command line. The API_COMMAND should be ZCQUERY.

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

be_list={
  [
    "IP1:PORT",
    "IP2:PORT",
    "IP3:PORT"
  ]
}
be_list={
  [
    "192.168.1.111:80",
    "192.168.1.111:8080"
  ]
}

The sample data above should be in the data file when sending via command line. The API_COMMAND should be ZCISUSPEND.

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

Last update: July 7, 2020