BuddyNS integration with cPanel/WHM
BuddyNS offers transparent integration with cPanel/WHM. This means: you control your domains entirely through your cPanel/WHM interface, and BuddyNS transparently propagates DNS for them in the background.
Goals and Benefits
Why using BuddyNS for replicating your domains managed with a cPanel/WHM server?
- If your server or DNS software are temporarily unavailable, your DNS continues to run smoothly.
- Add confidentiality and fight DNS attacks with our drop-in encrypted DNS, without extra setup on your side.
- Your clients resolve your domains much faster thanks to low-latency, geographically optimized servers.
- You can eliminate the costs and complexity of running extra DNSONLY servers.
Why is BuddyNS more appropriate than other DNS vendors?
- Best consistency
- Upon any change to your DNS data, BuddyNS synchronizes within minutes, as opposed to customary hours.
- Seamless integration
- Our integration plugin makes DNS replication effortless to you and your users.
Target users and System Requirements
- Full (root) access to your cPanel/WHM server for installation.
- Access to WHM for starting BuddyNS replication.
- A BuddyNS account.
- cPanel/WHM versions: tested on cPanel v11.40 and above; may reasonably work down to 11.32.
- cPanel/WHM profile: currently only installations with BIND or PowerDNS as DNS server are supported (Feedback us).
- cPanel's PHP open_basedir Tweak disabled. This prevents plugins from accessing configuration files, and cannot be cleanly customized.
- The following components installed:
- Python 2.6 or higher (see python -v)
- the /sbin/service utility
- the cron daemon
- System: works with the minimum parameters declared by cPanel (512MB RAM, 10GB disk).
- Resource occupation: few KBs of disk space, essentially zero CPU time.
How it works
Here's an overview of your life with this integration plugin:
- You create a BuddyNS account.
- You install our lean cPanel/WHM integration plugin (automated, run a script).
- When you create a new user account, its domain is replicated transparently onto BuddyNS.
- When your resellers add AddOnDomains or Parked domains, they are replicated transparently onto BuddyNS.
- When any of your zones get modified, BuddyNS automatically reflects the change promptly.
- During server downtime, network hiccups, or maintenance, your DNS runs smoothly through BuddyNS.
NoteThis installs similarly to cPanel: with a fully automated install script. Contrarily to cPanel, this can be removed just as easily with an enclosed removal script.
Make room for 30-60 minutes to run this through completion. If anything goes wrong, contact our support. If anything is unclear to you, or does not reflect your cPanel/WHM version, please report to our feedback address.
Please observe and replace the following values used in your guide for your cPanel/WHM installation:
- When you read 126.96.36.199, replace it with the main IP address of your cPanel/WHM server
- When you read foobar.com, replace it with the main domain name of your cPanel/WHM server (your domain name as a hosting provider)
Install the BuddyNS integration plugin
Get a BuddyNS account (if you don't have one already):
activating your domain on BuddyNS:
- as domain name, enter foobar.com,
- as IP of primary, enter 188.8.131.52,
- as contact e-mail, enter one unrelated to your hosting, so you're still reachable if it has downtime
- Enable cPanel mode for your BuddyNS account:
- click the SETTINGS button in your BuddyBoard ("Account" pane)
- enter your current password and check the Enable cPanel mode checkbox
- hit Confirm to save.
- Log into a shell on your WHM server as root:
# get a console on your cPanel/WHM server ssh email@example.com
- Download the installation script:
curl -LO https://lx.buddyns.com/cpanel-whm/installer.sh
- Run the installation script:
This will download, extract, and place the plugin components.
Configure BuddyNS integration
- Log into your WHM web application as root, and reach Plugins → BuddyNS DNS replication (see screenshot).
- You are required to:
- Select Enable BuddyNS integration
- Enter your API Key for your cPanel/WHM server to access BuddyNS' API
- Make sure BuddyNS replicates all zones active on your cPanel/WHM server:
# synchronize your zones on cPanel/WHM and BuddyNS: /opt/BuddyNS/bin/sync_buddyns_zones.py
At this point, any domain added to your cPanel/WHM system, by you (accounts), or by your users (AddOn and parked domains) gets automatically propagated onto BuddyNS.
Extra test? — You can use Create a New Account on cPanel/WHM using a random domain, and verify on your BuddyBoard that the domain makes it into BuddyNS. You can then use Terminate an Account on cPanel/WHM and verify that the domain is removed from BuddyNS.
Provide BuddyNS delegation
Add DNS servers to the nameservers declared by your domains to get DNS redundancy and speedup:
- Decide 2 DNS servers from the BuddyNS backbone to delegate your zones to. We offer many servers (see list here), select your 2 based on proximity to your users.
- Log into your WHM webapp, reach the Server Configuration → Basic Setup, and find the Nameservers section at the end of this page.
- Enter the two BuddyNS server names in two free slots, and press Save Changes.
- These settings will apply to newly added domains. To update delegation for previously added domains too, get a console onto your server and run the following:
Nota bene — you need to update delegation at your registry as well after performing this step. Registry delegation is the more important of the two.
# automatically update delegation for existing domains (BIND only!) /opt/BuddyNS/bin/update_ns.sh
After completing this, you can log into your BuddyBoard Zones page and verify the delegation status of your zones.
At this point, Congrats! Your basic setup is done. If you have special needs, find advanced configuration options below.
The integration package is designed as follows:
- When accounts are created (or removed) from WHM, their domain is added (or removed) on BuddyNS via a hook immediately.
- cPanel offers no hooks for real-time capturing of domains added (or removed) by your users and resellers. These are detected and reflected onto BuddyNS within 30 minutes by a cron script. This is extremely lightweight (10ms per run on a minimum-requirements virtualized system).
- Changes to your domains data (zone records) are detected and retrieved entirely by BuddyNS without action from your server.
Selecting which zones to synchronize
The plugin synchronizes all zones by default: zones found on cPanel and not at BuddyNS are added (onto BuddyNS), zones found at BuddyNS but not on cPanel are removed (at BuddyNS).
You can change this behavior by excluding zones from synchronization
/etc/BuddyNS/ignored_zones.txt). Zones listed in
this file are not added (or removed) if they are found on cPanel but not on
BuddyNS (or viceversa). This allows you to exempt some customers from DNS
Do you want to select by inclusion instead? That is,
replicating only a fixed set of zones no matter what new customers you add
on cPanel. In this case, simply activate the zones you want to replicate
on BuddyNS manually, and keep cPanel integration disabled.
BuddyNS will detect with its own logic whenever you change your DNS data,
and synchronize accordingly.
You may still want to install the integration plugin, and keep it disabled. This takes care of the initial setup of your server for you, and gives you a preview of your DNS traffic from inside your cPanel server.
In case of issues, proceed as follows:
- Use the Target tool in your BuddyBoard to perform real-time checks of your zone transfer configuration.
- Look into log files
/opt/BuddyNS/var/log/buddyns.log. This may reveal a local/configuration issue.
- You can increase log verbosity to 'debug' in file
- You can enable/disable recurring sync in
/etc/cron.d/buddyns. Please do NOT change the frequency!
If none of these helps, contact our support to report an issue. Before doing so, make to include all the essential troubleshooting data we need to help effectively: this includes system, cPanel and plug-in versions, along with their respective basic configuration. Plug-ins ≥2017012101 include a nifty tool to carry out this step quickly & reliably for you. Simply run the following:
send_sysreport allows you to review the
data assembled before sending. Our support team retains this data until
the successful closure of your ticket.)
The plug-in page notifies you when new versions are released, with a message on top of the plug-in page itself. Checks for new versions occur on a weekly basis.
In order to upgrade to a new version, run the deinstaller script with option upgrade:
You may then confirm the new version by checking the version number on the top/right of the plug-in page.
Why do we not make this happen behind the scenes? cPanel users are generally sensitive to having full control of what runs on their server.
To remove the BuddyNS integration plugin from your system:
- Remove BuddyNS nameservers from Server Configuration → Basic cPanel & WHM Setup.
- Reflect this change into your zones (BIND only!):
- Run the removal script with remove option:
|Version||Date (newest first)||Changes|
|2019072801||July 28, 2019||
|2019070901||July 9, 2019||
|2019062603||June 26, 2019||
|2017120601||December 6, 2017||
|June 18, 2017||
|2017012101||January 21, 2017||
|2016122701||December 27, 2016||
|2016110401||November 4, 2016||
|August 21, 2016||
|2016060601||June 6, 2016||
|August 8, 2015||
|2015041801||April 18, 2015||
|January 16, 2015||
|2014022401||February 24, 2014||
|2014011801||January 18, 2014||
|1.1||January 3, 2014||
|1.0||December 13, 2013||