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.

yum -y install httpd-tools

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

Everything else may be left as the default values.

Save your changes. The settings will be applied to all ZeroConf workers.

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.

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.

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.

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.

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] }
                                ]
                        }
                ]
                }
        ]
}

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.

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.

                "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
• ZCDOWN: Cluster down
• ZCSSL: Add SSL credentials
• ZCSSLRELEASE: Delete SSL credentials
• 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 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.

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