BuddyNS logo

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?

Continuity
If your server or DNS software are temporarily unavailable, your DNS continues to run smoothly.
Performance
Your clients resolve your domains much faster thanks to low-latency, geographically optimized servers.
Simplicity
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

System requirements

How it works

Here's an overview of your life with this integration plugin:

Installation

Note

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.

Foreword

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:

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 12.13.14.15,
    3. as contact e-mail, enter one unrelated to your hosting, so you're still reachable if it has downtime
    Important — you'll receive two confirmation e-mails:
    • a confirmation of activation of your zone; as a cPanel user, ignore the setup instructions in there.
    • one with your account credentials; use this to log into your BuddyBoard (BuddyNS control panel)
  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@12.13.14.15
  4. Download the installation script:
    curl -O http://lx.buddyns.com/cpanel-whm/installer.sh
  5. Run the installation script:
    sh installer.sh
    This will download, extract, and place the plugin components.

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:
    /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:

BuddyNS cPanel plugin page
  1. Decide 2 DNS servers from the BuddyNS backbone to delegate your zones to. We offer 7 servers, named {b, c, d, e, f, g, h}.ns.buddyns.com, pick 2 amongst them based on proximity to your users. Examples:
    • mostly North American users? Pick D and G.
    • mostly Asian users? Pick F and H.
    • global users? Pick D and E.
  2. Log into your WHM webapp, reach the Server Configuration → Basic cPanel & WHM Setup, and find the Nameservers section at the end of this page.
  3. Enter the two BuddyNS server names (e.g. d.ns.buddyns.com and g.ns.buddyns.com) 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:
    # update delegation for previously added domains
    /opt/BuddyNS/bin/update_ns.sh
    
    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.

Are you an Advanced User and want to use Vanity DNS? Consider the added setup complexity and maintenance burden on your side. We provide you the relevant data in our vanity setup instructions, and leave the setup to you.

Technical notes

The integration package is designed as follows:

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.

Troubleshooting

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:

/opt/BuddyNS/bin/send_sysreport.sh

(Privacy note: send_sysreport allows you to review the data assembled before sending. Our support team retains this data until the successful closure of your ticket.)

Upgrade

Plug-in versions ≥ 2014011801 advise you when a new plug-in version is available. This is displayed 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, take the following steps:

  1. Deinstall the old version (versions ≥2014011801 perserve your config files):
    /opt/BuddyNS/bin/deinstaller.sh
  2. Reinstall the new version:
    curl -O http://lx.buddyns.com/cpanel-whm/installer.sh
    sh installer.sh
    /opt/BuddyNS/bin/sync_buddyns_zones.py
  3. Reach your plug-in web page in cPanel and confirm the new version number (top/right of the 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. We respect this, so automated the full upgrade procedure, but we leave it up to the user to actually initiate it.

Removal

To remove the BuddyNS integration plugin from your system:

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

Changelog

Version Date (newest first) Changes
2017012101 Janary 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
2016082101
[minor]
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
2015080101
[minor]
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
2015011601
[minor]
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.