ZeroConf Configuration

Every time you add a new site or modify a domain, you must configure:

  • Cluster
  • Worker Group
  • Virtual Hosts
  • Listeners
  • Virtual Host Mappings

Wouldn't it be nice to simply that workflow? That's where ZeroConf comes in.

Benefits of ZeroConf

With ZeroConf enabled, you only need to configure Listeners, and optionally Virtual Host Templates. That's it.

ZeroConf enables automatic configuration updates to simplify the process of setting up the ADC and Web Server. ZeroConf simplifies configuration for admins with many sites and/or servers. It works for a single front end node as well as for a multi-front-end highly available set up.

  • No need to manage multiple clusters anymore. You manage:
    • One Cluster
    • One Mode
    • One Strategy
  • No need to set up all the end points in a Worker Group
  • No need to set up Virtual Hosts and Cluster mapping

Set up ZeroConf in WebAdmin

ZeroConf must be set up in the Web ADC's WebAdmin Console. There is an optional cPanel plugin as well, which interfaces with the server side. If you wish to use the cPanel plugin, you can follow these instructions to set it up, after you have finished configuring WebAdmin.

Set up Listeners

  • Navigate to Configuration > Listeners.
  • Edit HTTP listener, set Enable Zero Config to Yes, and click Save.
  • Edit HTTPS listener, set Enable Zero Config to Yes, and verify that the SSL-related fields are also set up.

Create Account and Password

Determine where to place the .htpasswd file. It must be in a directory readable by the user running the ADC worker (default nobody).

Run the following command to generate the .htpasswd file from console, replacing zero with the account name you would like to use. You can change it to whatever you want, but keep in mind, there can only be one ZeroConf account: 

htpasswd -c /HTPASSWD_PATH/.htpasswd zero

Enter your preferred password two times. For this example, let's say it is also zero.

Tip

If the command htpasswd is not found, please run the following command to install on CentOS: 

yum -y install httpd-tools

Tip

An .htgroup may be created if desired, but is not required.

Configure ZeroConf

Navigate to Configuration > Server > ZeroConf.

Click Edit in the General section and set the following:

  • Enable Zero Config: Yes
  • User Password File: /HTPASSWD_PATH/.htpasswd (replace HTPASSWD_PATH with the actual file path to .htpasswd)
  • Group Password File: /HTGROUP_PATH/.htgroup (optional, replace HTGROUP_PATH with the actual file path to .htgroup)
  • ZConf SHM Directory: $SERVER_ROOT/zconf

Save your changes.

Click Add in the ZeroConf Listeners section and set the following:

  • Listener Name: ZConf (or whatever you'd like to call it)
  • Address: Web ADC's IP address and a port of your choice, e.g.10.10.40.150:55688
  • Private Key File: $SERVER_ROOT/crm.key (replace with actual path to your key)
  • Certificate File: $SERVER_ROOT/crm.pem (replace with actual path to your cert)

Save the new listener.

Optional Debug Log

If you are encountering problems with ZeroConf, you can enable debug logging.

Click Edit in the ZeroConf Listener Log section and set the following:

  • File Name: $SERVER_ROOT/Zconf.log
  • Log Level: DEBUG
  • Debug Level: HIGH
  • **Rolling Size (bytes):: 10M

Save your changes.

Tip

If you are not actively trying to find a problem, set Debug Level to NONE. Debug logs can easily fill up disk space, if left to run indefinitely.

Optional Access Log

You can keep an access log. Click Edit in the ZeroConf Access Log section and set the following:

  • File Name: $SERVER_ROOT/Zconf-Access.log
  • **Rolling Size (bytes):: 10M

Save your changes.

Virtual Host Templates

ZeroConf can use ADC-configured Virtual Host Templates to generate a collection of VHosts that differ only by domain and cluster.

ZeroConf only requires a Template VHost. There is no need to create Member VHosts. ZeroConf inherits from the Template VHost.

Warning

With ZeroConf, server-level inheritance is not guaranteed for template values that are Not Set. We recommend that you explicitly configure as many values as possible, and not rely on server-level inheritance.

ADC Configurations

In addition to the general template configurations, the following options are available:

  • Server > ZeroConf > Separate VHost Per Domain, and Virtual Host Templates > Template > ZeroConf> Separate VHost Per Domain each control how the ADC build virtual hosts. By default, domains that share backend combinations will also share VHosts and cache stores. Enabling Separate VHost Per Domain creates individual VHosts and cache stores. These are two separate options at two separate levels, and they do not impact each other. This option defaults to No on both levels.
  • Virtual Host Templates > Template > ZeroConf > Used By ZeroConf toggles whether to allow ZeroConf to use the template. It defaults to Yes.

Note

ZeroConf is not context aware. It does not know that there are similarities between example.com and blog.example.com. If Separate VHost per Domain is enabled, then these domains will each have their own VHosts.

ZeroConf Messages

By default, no templates are selected. Therefore, the server level settings are used to create the VHosts.

To use a template, the ZCUP ("ZeroConf Cluster Up") message that you send to the API needs to include a "template" configuration in one of the defined VHosts.

Example

Suppose we want to disable cache for a specific domain. In the ADC configuration, you would create a VHost Template named noCacheTemplate that disables the cache settings. Your ZCUP message would then look like the following: 

conf=
{
"vhost_list" :
        [
                {
                "template" : "noCacheTemplate",
                "domain_list" :
                        [ "c7-30.ls.com","mail.c7-30.ls.com","www.c7-30.ls.com","cpanel.c7-30.ls.com","webdisk.c7-30.ls.com","webmail.c7-30.ls.com"],
                "conf_list" : [
                        {
                        "lb_port_list" : [443],
                        "dport" : 443,
                        "be_ssl" : true,
                        "ip_list" :
                                [
                                        { "ip": "10.10.40.153", "port_list" : [443] }
                                ]
                        }
                ]
                }
,               {
                "domain_list" :
                        [ "newdomain100.com","mail.newdomain100.com","www.newdomain100.com","webmail.newdomain100.com","cpanel.newdomain100.com","webdisk.newdomain100.com"],
                "conf_list" : [
                        {
                        "lb_port_list" : [443],
                        "dport" : 443,
                        "be_ssl" : true,
                        "ip_list" :
                                [
                                        { "ip": "10.10.40.153", "port_list" : [443] }
                                ]
                        }
                ]
                }
        ]
}

This ZCUP configuration includes two VHosts. The conf list is identical. The only difference is the domain list and a template configuration in the first VHost. The first VHost uses the VHost Template named noCacheTemplate configured in the ADC. The second VHost uses the server level configurations.

API

ZeroConf works by sending messages to LiteSpeed Web ADC, detailing the configuration for backend clusters. The API provides responses indicating success or failure.

The current configuration status can be viewed in the WebAdmin Console, under Actions > Real-Time Stats.

Sending ZeroConf API Messages

ZeroConf messages have the following components and may conveniently be sent via curl command:

  • BASICAUTH_USER: The configured basic auth user name.
  • BASICAUTH_PASSWORD: The configured basic auth password.
  • LSADC_IP: The IP Address of Web ADC
  • LSADC_ZEROCONF_PORT: The configured port for ZeroConf messages on the ADC.
  • API_COMMAND: The command to be issued. These are listed below.
  • UNQ_BACKEND_NAME: A name to uniquely identify this backend server. It is used as an identifier for uploaded configurations.

Example

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 and failures). Response bodies may contain data from the ZeroConf system or error messages detailing a problem encountered while trying to process a received message.

Example

This is a sample error response for a configuration message. The request returns an HTTP status code of 400, with the following 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

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 in brackets ([ and ]) 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 brackets are used in the message format, optional fields are 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

The ZCUP message informs LiteSpeed Web ADC that a cluster is up (or back up) and is available to support backend traffic.

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

  • template (optional): The name of the template to use with the listed 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 ADC 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.
      • port_list(optional): 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 the command line. The API_COMMAND should be ZCUP.

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.

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.

ZCDOWN Message

ZCDOWN informs 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 the command line. The API_COMMAND should be ZCDOWN.

ZCSSL Message

ZCSSL provides 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. (NOT the file name, but the key itself).
  • cert: The SSL certificate the domains should use. (NOT the file name, but the cert itself).
  • ca_bundle: The SSL CA bundle that is associated with the certificate. (NOT the file name, but the CA bundle itself).
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

ZCSSLRELEASE deletes 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" ]
      }
    ]
}

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

ZCOWNRRELEASE Message

ZCOWNRRELEASE relinquishes ownership of any configuration records for specified domains from LiteSpeed Web ADC (i.e., 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" ]
}

The sample data above should be in the data file when sending via the 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 the 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 the 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 the 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 the 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: November 18, 2020