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.

Integration overview

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

Carefully check these out before proceeding with installing!

Scenario requirements

  • Full (root) access to your cPanel/WHM server for installation.
  • Access to WHM for starting BuddyNS replication.
  • A BuddyNS account.

System requirements

  • 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)
    • curl
    • 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.



This 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, 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

  1. Account registration at BuddyNS Get a BuddyNS account (if you don't have one already): activating your domain on BuddyNS:
    1. as domain name, enter foobar.com,
    2. as IP of primary, enter,
    3. as contact e-mail, enter one unrelated to your hosting, so you're still reachable if it has downtime
  2. Enable cPanel mode for your BuddyNS account:
    1. click the SETTINGS button in your BuddyBoard ("Account" pane)
    2. enter your current password and check the Enable cPanel mode checkbox
    3. hit Confirm to save.
  3. Log into a shell on your WHM server as root:
    # get a console on your cPanel/WHM server
    ssh root@
  4. Download the installation script:
    curl -LO https://lx.buddyns.com/cpanel-whm/installer.sh
  5. Run the installation script:
    sh installer.sh
    This will download, extract, and place the plugin components.

    Got multiple python versions which confused the installer? Run export PYTHON_BIN="/path/to/your/pythonN" to specify which python to use, before running installer.sh.

Configure BuddyNS integration

BuddyNS cPanel plugin page
  1. Log into your WHM web application as root, and reach PluginsBuddyNS DNS replication (see screenshot).
  2. You are required to:
    1. Select Enable BuddyNS integration
    2. Enter your API Key for your cPanel/WHM server to access BuddyNS' API
    Log into your BuddyBoard to get this value (see screenshot).
  3. Make sure BuddyNS replicates all zones active on your cPanel/WHM server:
    # synchronize your zones on cPanel/WHM and BuddyNS:

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:

BuddyNS cPanel plugin page
  1. 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.
  2. Log into your WHM webapp, reach the Server Configuration → Basic Setup, and find the Nameservers section at the end of this page.
  3. Enter the two BuddyNS server names in two free slots, and press Save Changes.
  4. 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:
    # automatically update delegation for existing domains
    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.

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 additional configuration options below.

Technical notes

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 (see file /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 replication.

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:

  1. Use the Target tool in your BuddyBoard to perform real-time checks of your zone transfer configuration.
  2. Look into log files /opt/BuddyNS/var/log/sync_zones.log and /opt/BuddyNS/var/log/buddyns.log. This may reveal a local/configuration issue.
  3. You can increase log verbosity to 'debug' in file /etc/BuddyNS/loglevel.txt.
  4. 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:


(Privacy note: send_sysreport.sh 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.sh script with option upgrade:

/opt/BuddyNS/bin/deinstaller.sh 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.

Migration to a new cPanel/WHM server

Say you want to migrate your cPanel/WHM to a new server. How do you do that?

Call OLD your existing server, and NEW the destination server. Proceed as follows:

  1. Install BuddyNS cPanel plug-in on NEW, following the standard steps for installation & configuration. During installation, the plug-in will enable AXFR from BuddyNS servers on NEW.
  2. Temporarily disable the BuddyNS integration plug-in from OLD. You can do so from the web screen of the plug-in. Your zones will stay registered – on your BuddyNS account – with OLD as master.
  3. Perform a dummy test: add a new test account zonetest123.com on NEW, then run /opt/BuddyNS/bin/sync_buddyns_zones.py on NEW, and verify that the test zone shows up in your BuddyNS. Use the Target tool to verify that the zone transfers successfully from NEW.
  4. If successful, remove the test account from NEW.
  5. Perform a live test: remove a real zone, then immediately run /opt/BuddyNS/bin/sync_buddyns_zones.py on NEW. Verify that the new zone shows up again in your BuddyNS account, with the IP address of NEW.
  6. Once confirmed successful, proceed by doing so for each zone. You can also automate that by running the script below from NEW.

Automating migration

Got a lot of zones to migrate to your NEW server? Below is a script to automate the migration of each zone on your BuddyNS account to use the IP address of the NEW server.

The script will:

  1. Take a list of zones to migrate from file zones_to_migrate.txt.
  2. For each zone, remove it from the BuddyNS account, and immediately re-add it with the IP address of NEW.

Run the commands in a small test first, with 3 zones only from your list. Run one line at a time and check the output, for best control:

# run this on NEW server

# These commands automatically update a bunch zone at BuddyNS to use the new IP address

# add a couple of test zones to the file (use valid)
/opt/BuddyNS/bin/whm_utils.py domains | head -n3 | tee zones_to_migrate.txt

# run bulk migration for these few test zones
master_ip=$(/opt/BuddyNS/bin/whm_utils.py master_ip)
echo "Will migrate zones to my address = $master_ip"
cat zones_to_migrate.txt | while read zname ; do echo "=== Migrating $zname ===" ; /opt/BuddyNS/bin/buddyns_ctl.py del "$zname" || echo "Removal of $zname failed. Check BuddyNS account."; /opt/BuddyNS/bin/buddyns_ctl.py add "$master_ip" "$zname" || echo "Addition of $zname failed. Check BuddyNS account." ; done

If the above worked, unleash the commands on your full list of zones available on the NEW server. Again, run one line at a time and check the output, for best control:

# Check the BuddyNS account now, and ensure that the test zones look good.
# If they do, proceed to Bulk-update all other zones.
# Nota bene: there's a "pause" in the command below, to ensure BuddyNS' API rate limits don't break your flow.
/opt/BuddyNS/bin/whm_utils.py domains | tee zones_to_migrate.txt
estimated_time_s=$(awk 'END { print 3*NR }' zones_to_migrate.txt)
echo "This will take some ${estimated_time_s}s to run. Get some tea :)"
cat zones_to_migrate.txt | while read zname ; do echo "=== Migrating $zname ===" ; /opt/BuddyNS/bin/buddyns_ctl.py del "$zname" || echo "Removal of $zname failed. Check BuddyNS account."; /opt/BuddyNS/bin/buddyns_ctl.py add "$master_ip" "$zname" || echo "Addition of $zname failed. Check BuddyNS account." ; sleep 2; done


The instructions following are for WHM removal only: they'll leave the zones in your BuddyBoard unaffected. If you also want to clear your zones from your BuddyNS account, run this command as root on your WHM server prior to WHM removal:

delzones=`/opt/BuddyNS/bin/whm_utils.py domains`
for z in $delzones ; do /opt/BuddyNS/bin/buddyns_ctl.py del $z ; done

Alternatively, log into your BuddyBoard and use the DELETE ACCOUNT button if you want to eliminate your BuddyNS account altogether.

Now, on to removing the BuddyNS integration plugin from your WHM system:

  1. Remove BuddyNS nameservers from Server Configuration → Basic cPanel & WHM Setup.
  2. Reflect this change into your zones:
  3. Run the removal script with remove option:
    /opt/BuddyNS/bin/deinstaller.sh remove


Version Date (newest first) Changes
August 2, 2023
  • Add addresses of new DNS and transfer servers.
November 24, 2022
  • Update addresses of transfer servers.
February 4, 2022
  • Improve handling of systems with multiple python versions installed.
December 9, 2021
  • Fix cron warnings on servers running EOLed python 2.
2021120601 December 6, 2021
  • Fix display of troubleshooting information in cPanel plug-in page.
  • Repond to more zone-altering actions performed in cPanel by non-admins.
2021022501 February 25, 2021
  • Early support for distros finally switched to python3.
May 9, 2020
  • add ability to filter logs in user interface.
2020050302 May 3, 2020
  • Eliminate log errors when adding domains already registered on BuddyNS.
  • Enable send_sysreport.sh when BuddyNS integration is inactive.
  • Switch to the public open-source version of the API client.
December 22, 2019
  • Fix regression in v2019070901 for synchronization of parked & addon domains.
  • Automatically support cPanel in NAT mode.
July 28, 2019
  • Automatically manage "cPanel mode" setting on BuddyNS account.
2019070901 July 9, 2019
  • New, simplified workflow for onboarding.
  • Simplified troubleshooting with insightful outcome messages and logging.
  • Fix an error upon temporary network errors occurring while WHM accounts added/removed.
2019062603 June 26, 2019
  • new design for plug-in control page.
  • list properties of own BuddyNS account.
  • simplify and strengthen logging.
  • improve efficiency and reliability of synchronization logic with many zones.
  • improve reliability of send_sysreport tool
2017120601 December 6, 2017
  • improve compatibility of update_ns script to automatically update NS delegation.
  • fix bug causing sync_buddyns_zones to potentially hang when given many hundred zones.
June 18, 2017
  • support newly released cPanel 64
  • fix update_ns script misreading some zone names
2017012101 January 21, 2017
  • prevent failed user creations/removal upon API error
  • add tool to simplify reports to BuddyNS support
  • add auto-upgrade capability to deinstall tool
  • allow manual override of auto-detected master IP address
2016122701 December 27, 2016
  • fix some extra subdomains being activated
2016110401 November 4, 2016
  • support PowerDNS as DNS backend
August 21, 2016
  • use PHP 5.6 if available on cPanel v11.58+
2016060601 June 6, 2016
  • support multiple cPanel/WHM servers per BuddyNS account
  • verify system requirements before installation
  • improve feedback reporting
August 8, 2015
  • fix automatic setting of BIND's allow-transfer failing on some newer systems
  • improve feedback reporting
2015041801 April 18, 2015
  • minor graphical and UX improvements to control page
  • fix issue preventing activation of '.club' and some other TLDs
January 16, 2015
  • update instructions to reflect some changes in the BuddyBoard
  • installer dynamically retrieves transfer servers to enable
2014022401 February 24, 2014
  • Zone and traffic utilization graphs
  • Zone list is real-time
  • Highlight zones failing to initialize in red
  • Better UX when auth/other errors prevent API access
  • Fix PHP warnings in some installations
  • Reduce log verbosity
2014011801 January 18, 2014
  • Support >1000 configured zones.
  • Display latest activity in web interface.
  • Check & report availability of new plug-in versions automatically.
  • Improve user reporting in web interface.
  • Support upgrades kind to previous configs.
  • List zones registered at BuddyNS on web interface.
1.1 January 3, 2014
  • Improve accuracy of IP extractor; Allow manually setting it.
  • List zones registered at BuddyNS on web interface.
1.0 December 13, 2013
  • Automatic sync of added account & add-on domains.
  • Configuration web interface.