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 toYes
, and click Save. - Edit
HTTPS
listener, set Enable Zero Config toYes
, 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
(replaceHTPASSWD_PATH
with the actual file path to.htpasswd
) - Group Password File:
/HTGROUP_PATH/.htgroup
(optional, replaceHTGROUP_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 ADCLSADC_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¶
ZCUP
: Cluster upZCDOWN
: Cluster downZCSSL
: Add SSL credentialsZCSSLRELEASE
: Delete SSL credentialsZCOWNRRELEASE
: 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 thandport
.
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 serversZCRESUME
: 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 pairZCISUSPEND
: 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