Setup/Configuration

You should have already installed Web ADC.

Benefits of Setting up ZeroConf

We noticed it's a little complicated to set up ADC + Web Server; needing to modify Cluster and Domain every time when adding a new site or modifying any domain. ZeroConf enables automatic configuration updates to simplify the process of setting up the ADC and Web Server.

Before setting up ZeroConf, the following needs to be configured for each site:

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

After setting up ZeroConf:

  • Listeners
  • Virtual Host Templates (optional)

ZeroConf simplifies configuration for those with many sites and/or servers. ZeroConf works for a single front end node as well as for a multi-front end highly available set up.

ZeroConf by Design

Web ADC

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

If you want to design a multi cluster with a different strategy, then you may want to setup manually instead of using ZeroConf settings.

ZeroConf Plugin

NOTE: Automatic sync takes 5 minutes to complete. (e.g. create an account(Domain) on cPanel, then you will see it sync to the ADC in 5 minutes.) It takes 5 minutes because the process pauses, giving the Apache configurations time to completely update before the changes are pushed. (We have found that the PkgAcct::Restore account action took the longest time to update.)

ADC ZeroConf Setup

Listeners

  • Navigate to ADC WebAdmin Console > Configuration > Listeners
  • Set up both HTTP/HTTPS with Enable Zero Config to Yes
  • Please do set SSL certificates for HTTPS listener, such as 443, either certificates from CA or Self-signed

ADC Password Setup

  • Determine where to place the htpasswd file. This file must be in a directory readable by the user running the ADC worker (default nobody).
  • Run the following command to generate .htpasswd file from console htpasswd -c /HTPASSWD_PATH/.htpasswd zero
  • Then enter password (e.g.zero) two times
  • If the command htpasswd is not found, please run the following command to install on CentOS: yum -y install httpd-tools
  • The zero after .htpasswd is the account name. You can change to whatever you want.
  • The ZeroConf password file accepts one account only
  • An .htgroup may be created if desired, but is not required.

ZeroConf Setup

Navigate to ADC WebAdmin Console > Configuration > Server > ZConf

General section

  • Set Enable Zero Config to Yes
  • Set User Password File to /HTPASSWD_PATH/.htpasswd
  • OPTIONAL: Set Group Password File to /HTGROUP_PATH/.htgroup
  • Set ZConf SHM Directory to $SERVER_ROOT/zconf

ZeroConf Listeners Section

  • Click Add button
  • Set Listener Name, e.g.ZConf
  • Set Address, The address should be the ADC's IP address and a port of your choice, e.g.10.10.40.150:55688
  • Setup Certificate with file PATH
    • Private Key File, e.g. $SERVER_ROOT/crm.key
    • Certificate File, e.g. $SERVER_ROOT/crm.pem

Optional Settings

ZeroConf Log

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

ZeroConf Access Log

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

VHost Templates

As of ADC Version 2.4 Build 11, ZeroConf VHosts may be created based on VHost Templates.

cPanel ZeroConf Setup

cPanel ZeroConf Plugin Install

  • Download plugin file from the ADC Downloads Page
  • Run the following command to install plugin: 
    unzip whm_lsadc_zconf.zip
cd whm_lsadc_zconf
./install.sh
  • Login to WHM and search zconf

ZeroConf Password Setup

  • Determine where to place the .zconfpasswd file. This file must be in a directory readable by the user running cPanel.
  • Run the following command to generate the .zconfpasswd file from console: 
    echo 'zero:zero' > /PATH_YOU_WANT/.zconfpasswd

The first zero is the account and the second is the password. These should match the credentials used to generate the .htpasswd for the ADC.

cPanel ZeroConf Setup

  • Navigate to WHM > LSADC ZConf Manager from the Plugins section
  • Click Configurations
  • Setup Server Conf Name, e.g. cpanel-153
  • Setup ADC Basic Auth, e.g. /PATH_YOU_WANT/.zconfpasswd
  • Setup ADC List, e.g. 10.10.40.150:55688
  • Setup Exclude Users(optional), e.g. testaccount
  • After configuring the settings, we can navigate back to upper level by clicking back to LSADC ZConf Manager button
    • The Server Conf Name is the conf name used by the ADC to identify this backend server. This should be unique to this server. If another backend server uses the same conf name, the old conf will be overridden.

Manually Send Server Confs

The first time we set up ZeroConf, we may want to try it manually to see if it works as we expect.

  • Click Generate ZConf to generate ZeroConf Message Files
  • Click Send Server Confs to send Server with config files

Firewall Configuration

If you set up ZeroConf to listen on port 55688, then you need to confirm the firewall allows TCP 55688 on both ADC and WebServer(cPanel).

For example, CentOS 7 firewall setup port 55688:

firewall-cmd --zone=public --permanent --add-port=55688/tcp
firewall-cmd --reload

How to verify ZeroConf is working

Experiment environment

  • ADC IP: 10.10.40.150
  • WHM IP: 10.10.40.153
  • DNS entry: 10.10.40.150 <-> c7-20.ls.com

Verification step

  • Create a New Account with Domain from WHM, e.g. c7-20.ls.com
  • Setup WordPress site, URL: http://c7-20.ls.com/wordpress/
  • Open http://c7-20.ls.com/wordpress/
  • Check response headers IP is 10.10.40.150 by Developer Tools

We can see IP is ADC's instead of web server(cPanel)'s, it means ZeroConf is working normally.

What if I Have Multi Servers?

Multi-ADC

If I have two Web ADCs, simply add multi ADC IPs 10.10.40.150:55688, 10.10.40.151:55688 into ADC List of ZeroConf Manager plugin.

Multi-cPanel

If I have two cPanels, simply follow cPanel ZeroConf setup with a different Server Conf Name.

How to Debug

Log check

  • From cPanel server, check error log, e.g. default path:/usr/local/cpanel/3rdparty/lsadc_zconf/error_log
  • From ADC server, check error log, e.g. default path:/usr/local/lslb/logs/error.log
  • From ADC server, enable optional settings for log then check

Warning Message

  • Required configurations are not set.
    • Configuration file not complete
  • Server conf files not generated yet.
    • ZeroConf file not generated yet
  • Failed to send command ZCUP to ADC_IP:PORT. This could be because the ADC is not configured to listen on that port. This could also be an issue related to iptables configurations on the server. To test please make sure that a basic curl command from the server to the ADC works. If the curl test returns that it couldn't connect to host, there is an issue.
    • ADC ZeroConf listener set up incorrectly
    • Firewall issue
  • Failed to send command ZCUP to ADC_IP:PORT, auth parameters did not work.
    • Password file not match. Please ensure the ADC Passwd file and ZeroConf Passwd file are properly configured. The file contents and file location are important for the connection to succeed.
  • Sending command ZCSSL to ADC_IP:PORT resulted in error 400
    • Password file not match
  • Sending command ZCUP to ADC_IP:PORT resulted in error 403
    • Access Control Denied

Learn More

LiteSpeed Web ADC ZeroConfig API