Jump to content
KAZOOcon: hackathon signup and details here! ×
  • 2600Hz-logo-RGB copy.png

    Welcome our Monster UI Apps Resource Pages!
    Below is a list of the applications developed by 2600Hz for KAZOO using the Monster UI Interface and documentation related to it. 
    If you have a question that is not covered here, check out our community forums.  

          Featured Apps

      New Updates!    Check it out!     

               SmartPBX_x512.png          

              CallCenter-PRO_x512.png          

              PortingManager_x512.png          

             commio_AppIcon-updated_round_x512.png          

             \DynamicCallerID.png            

             CallThruUs_x512.png          

    Smart PBX

    Call Center Pro

    Porting Manager   Comm.land   Dynamic Caller ID CallThru.us

     

    >>  2600Hzroundorangelogo.png  Return to Monster Apps Home Page  

     

  • Branding: Set up your White Label DNS


    2600HZ USER GUIDE  SETTING UP YOUR WHITE LABEL DNS 

    NOTE: We recommend completing this setup prior to setting up any new accounts.  This will ensure all accounts will use your white label domain.

    User Story
    A KAZOO reseller account wants to use their one of their own domain names in place of zswitch.net for white-labeling purposes.


    How this works
    On its most basic level, DNS points human readable “names” to machine readable “data”. These are called DNS records. The most basic of which (an A record) points a “name” such as www.2600hz.com to an IP address 23.239.13.252. More advanced records can tell phones what port numbers to use, what servers they should prefer most and least and what protocols to use (SRV and NAPTR records). 2600hz uses over a dozen of these records for its hosted KAZOO service, zswitch.net. Resellers wishing to white-label zswitch must configure their domain names to include all these records. In this guide, we will show you how to point your domain to a supported DNS provider (easyDNS), configure your records, then replicate those records to another DNS provider (Amazon Route 53) for extremely reliable white-labeled DNS configuration. 

    Here’s an illustration: DNS Mapping Charts4.png

    Disclaimer
    If you are very familiar with DNS, you may be aware that there are other services and methods you could use to implement your DNS. This purpose of this document is to provide as easy a path as possible for those who are not as familiar with DNS to successfully white-label without complicating the process by explaining all possibilities. You are free to use the services and methods that suit you best.

    Before you start

    NOTE:  Some DNS providers also offer domain registrar services. Using a DNS provider’s built in registrar service can seem like it simplifies nameserver settings, however it’s generally best to keep your registrar service with a major provider to ensure the security of your domain registration.

    • Make sure you have access to your login credentials for both services, as you will need to update them below.

    Overview

    This guide is set up in parts.  

    • Part 1  Enter basic company setup information in the KAZOO Branding app.
    • Part 2  Synch the server name for your DNS registration service with your DNS management service.
    • Part 3  Copy the IP address and target data path information from the Branding app to correlated EasyDNS fields.  Paths to define/remap include A records; CNAME; NAPTR; MX, SRV, and TXT. 
    • Part 4  For redundancy, consider copying the entire remapped data system to Amazon Web services. 
    • Part 5  Notes on Branding & Sub Accounts

    Part 1:  Branding App Setup & Configuration 

    1.  Access Your application Directory

    DNS: Launch branding app.png

    2.  Open the Branding application

    DNS - Branding app in list.png

     

    3.  General Tab :  Review the initial configuration settings

    DNS Step 1 Enter domain name.png
     

    • Enter your white label Domain name URL, using "portal" to prepend it.
    • Enter the Realm Suffix using "sip" to prepend your URL name.
      The Realm Suffix will be used to generate the account realms of accounts created by your white label interface.


    4.  Select the "Check DNS" button to the right of the Domain Name field

    DNS Check DNS Button.png
     

    This displays a template of all domains records that need to be configured.  You will want to keep a tab showing this open at all times, as you will be copying the information from this page to your DNS management system.
     

    DNS Copy DNS.png

     

     

    Part 2: Set up your EasyDNS account and copy its nameservers to registrar

    WARNING: This guide assumes the domain you are using will be used ONLY for white labling zswitch services. This step is dangerous if not.

    • Setup your account with easydns.com, selecting an appropriate plan for your expected volume
    • Get your new nameservers from easyDNS

      dIBEFu5NrSI1GlmrtgCJyOmEh9rkbEbo6R6y2vqo
       
    • Overwrite your nameservers on your registrar (godaddy or the like) account
    • DNS - change nameservers.png

      DNS - Enter Nameservers.png


     

    Part 3:  Configure your DNS records

    You may want to keep 2 windows open, 1 showing the Branding app in KAZOO, the other showing the records entry window in your easyDNS software.

    DNS  easydns Settings List .png

    To configure the different kinds of records, you will step through these links and assign the records shown in the branding app to the fields shown.  

    Configure “A Records”
    "A Records" map host names to IP addresses.  Click on the “A” option next to DNS Information in easyDNS (see above).  Copy the data from the branding app. to easyDNS as shown in the illustration below:

    DNS Copy A records.png

     NOTES:

    • Only copy the “A record” types listings to this page.
    • “Expected Record Data” field in the Branding App = IP Address 
    • Make sure the IP address starts flush against the field and does not show a tab or space to the left.

    Enter a value for TTL
    A TTL is “Time To Live”.  Set as seconds, it defines how long a DNS record should reside in a client’s DNS cache without being discarded or regenerated. 

    A common value for TTL is 7200 seconds (2 hrs) and is our recommendation for all record entries. Most DNS providers charge based on record lookups. The higher this setting, the less lookups will hit your provider;  also the higher your TTL is, the longer changes to your records will take to roll out.

    Save / CONFIRM your changes! 

    Configure “CNAME Records”
    Once the “A records” are copied, move to the next page in easyDNS and copy the CNAME data from the Branding app. to the correct field in easyDNS.

    CNAME records map host names to other host names, including hosts at other domains. 

    DNS CNAME mapping.png

    NOTES:

    • You MUST add a dot to the end of the CNAME URL (see above). This will indicate that the URL is a fully qualified domain name and does not need to be appended by your domain name (for example .myreseller.com).
    • Copy both the API and the WebGUI
    • Use 7200 TTL as default to start
       

    Configure “NAPTR Records”
    NAPTR refers to the “Name Authority Pointer Record.  It is used by your phone to map SIP servers and protocols. You will need to break out the information provided in the Branding app to the specified fields in the easyDNS listing.  


    DNS - NAPTR port image arrows.png
     

     NOTES:

    • The values in the KAZOO branding app are concatenated in a single string.  Many applications will provide separate fields for these.  See red arrows.
       
    • In the branding app you will see a set of empty quotes; this is a “null” listing for Regex.  Leave that field empty and copy the remaining to the “replacement” field.

     

    Configure “MX Records” for Outbound Faxing
    MX refers to the  “mail exchange” record.  This specifies the mail server responsible for accepting email messages on behalf of the  domain name. 
     

    BrandingApp_x512.png   From Branding App

    DNS Branding FAXline.png
     

    easyDNS logo.pngTo EasyDNS
    Use *.sip, so anything .sip will be forwarded to the fax domain URL.

    DNS MX record for FAZ.png

     

    Configure “SRV Records”
    SRV refers to the Service Record in the DNS. It is a specification of data in the Domain Name System defining the location, i.e., the hostname and port number, of servers for specified services.

    DNS - SRV port image with arrows2.png

      NOTES

    • You must put the “dot” at the end of the Target URL for this record also.
    • The values in the KAZOO branding app are concatenated in a single string.  Many applications will provide separate fields for these.  See above red arrows.
    • Each SRV value should be added as a separate line.  For example the branding app image above shows 2 lines per sip account;  you must add these as separate lines, so there should be a total of 4 entries in the easy SRV records list. See above orange arrows.

     

    Configure “TXT Records” (SPF Record)
    An SPF record is a specifically formatted TXT record. It lists all authorized hostnames / IP addresses that are permitted to send email on behalf of your domain. This will permit KAZOO to send emails such as voicemail notifications under your domain name.

    BrandingApp_x512.png   From Branding app:

    DNS Branding TXT.png
     

    easyDNS logo.png To EasyDNS

    dns easydns TXT records copy.png
     

    Check for errors!
    You should now see in the Branding app page the list with all green checkmarks at the right. 


    DNS error lines.png
     

    NOTE:  
    You MUST resolve any and all errors for your branded solution to work correctly. If there are still red configuration error notes, go back in and see if you can find the error.   Common mistakes include:

    • Not copying the full URL over (missing the last digit for example)
    • Unwanted space to the left of your pasted data.
    • A missing “dot” at the end of URLs, which causes EasyDNS to append your company URL at the end.

    Additional Notes

    • Make sure your records match EXACTLY.
    • You may need to use the paging option at the bottom right of the branding app to see all records you need to apply.

      dns branding page showing 2 pages.png

    Part 4:  For added redundancy:  Copy these records to Amazon Web Services 

    We recommend you copy all your settings to the Amazon Route 53 for additional redundancy. We have learned over the years that any DNS provider can and will have an outage eventually. This will allow your records to persist even if EasyDNS goes down. Here we will show you how to replicate your records using EasyDNS’s built-in replication feature.

    • First, purchase the Amazon Route 53 integration service from EasyDNS.
    • Then activate and copy your records.
    •  easyDNS logo.pngwill copy all your records and supply you with additional nameservers:
       

      DNS easydns Integrations Amazon.png

    DNS Auto Activate easyRoute53.png

    Once confirmed, you should see both nameservers listed.

    DNS - amazon Nameservers assigned.png

     

    • Finally, go back to your original Domain Registrar and add the AWS Route 53 nameservers, alternating between the EasyDNS and Route 53 name servers.
       

    5HbQSl1-L1mgFfcznvLA433ehgu05RHrYUF6nFup

     

    SAVE AND TEST!  
    You should now be able to test your new setup. 

     

    Notes on Branding. & Sub Accounts

    Overview

    How notification templates are read is mostly how Kazoo always allows sub accounts to override their parent accounts, with some twists :))

    In simpler term, KAZOO performs something called walking up the account hierarchy, or we like to call it The Walk. We start from sub account to read the notification template and if not found we walk up the account hierarchy (going to parent account/accounts) stopping in each parent account to see if the document exists in that parent account and if not continuing the walk UNTIL we reach to the first parent account that is the reseller of the original account that we started our walk. In that case if the reseller doesn’t have that document then we abandon our walk and fall back to read system_config notification template.

    If during our walk any parent account has the document we stop the walk and return that document.

    We also repeat the same process for template attachments. So a child account can only customize just only JSON part of document and not customizing the HTML/Text template, doing so will that account to inherit its parent template attachments.

    Monster UI branding app and even Kazoo is totally showing its age and the UI part is somewhat confusing.

    Some visual notes:

    1. On side bar when a a template name is in grey or has a red circle next to it it means that template is disable which means the account has the document (so if you see that in brandingtest account that means brandingtest is overriding its parents and reseller. Also it means when one of the child accounts (like brandingtest2here) doesn’t have the document, it would inherit it from brandingtest and not reseller, other ancestors or system.
      1. So in summary disable means this account has document and the walk is always stops in this account level
    2. A Green cog means the notification is enabled and the account is overrides the notification. That means the account has the document and the walk stops in this level
    3. When changing enable/disable the effect of red circle is not visible away you need to change view (go to other apps or tabs) and come back
    4. There is another cog next to Template name in title of the page when you go to that template that allows you to remove the customization in that account so it would inherit the template from its ancestors. Also there is an option to force write the template from system config itself. that means it override its parents settings and the walk with stop in this level for its
    5. If in doubt you can always check the payload from API when loading the template, look for something account_ovverridden or account_defined field set to true. Kazoo is never wrong :))

    Frequently Asked Questions

    Can I do all this DNS mapping in a single application, e.g. GoDaddy?

    While it seems like tedious work to juggle both a registrar (GoDaddy or other) and a DNS web hosting service (easyDNS), we recommend using both.  Each is an expert in its field.  Domain registrars focus on indexing and protecting your domain name and the most popular have solid reputations for just that.  DNS hosting systems are focused on reliably providing the records computers need to enable services to run on your domain name.  These also offer different levels of support;  we have found easyDNS provides us with all the record types we need (including NAPTR which some do not recognize) and easily creates a redundant occurrence of all settings to Amazon’s Route 53 Web Service.  There are likely other systems that offer similar solutions, we are happy to hear what works well for you. 

    Can I add just my branding logo, etc. and not update my DNS?

    No, the KAZOO platform needs some way to “know” what branding to show. The hostname that you use to visit is how this is determined. For instance if you visit http://portal.myreselleraccount.com/, KAZOO will know to show the Branding we configured in this article. But if you just visit http://ui.zswitch.net/, it won’t know of any reseller branding and will default to KAZOO branding.

    Do all the Lines in the Branding app need to show a green checkmark?

    Yes, with one possible exception:  there may be an instance where the TXT value does not show a green checkmark and the white-labeling redirect processes will still work properly. But you should be well versed in DNS, SPF and mail servers if you have a custom SPF record. If ANY other record does not have a green check mark, it WILL fail.

    What are some of the problems that occur if my setup is not correct?

    • Your custom UI branding may not display.
    • Your phones may not be able to register to make/receive calls.
    • Your phones may may not fail over to a secondary cluster if their primary cluster goes down.
    • Your customers may not receive their email notifications.
    • Your email notifications may go into the SPAM mailbox.

     

    API Reference Docs

    docs.2600hz.comdocs.2600hz.com
    REST API Reference for Kazoo Crossbar API

    ####

    DNS branding CNAMEddress.pngDNS CNAME in EasyDNS.png




    User Feedback

    Recommended Comments

    • Administrators
    Hi Shah:
    The feedback I hear is if you are a customer on our hosted, private cloud or global infrastructure platform, at this time you will need to  submit a support ticket for this.   I'm checking about any open source options.
    Link to comment
    Share on other sites

    • Administrators

    @Jean Francois Charlebois, at a high level it does need to be blank. There are different ways on different platforms to express this though. If you are forced to enter something, I'd personally try "" (two double quotes with nothing between). Can you post a screenshot? Might help me guide you better. Of course you'd need to use the branding tools to verify using the branding app to be sure it works as expected.

    Link to comment
    Share on other sites


×
×
  • Create New...