Register Domains

Configure DNS so you can use your organization's domains to publish Banyan services


Banyan uses Public DNS to resolve domain names on your end users’ devices so that traffic to your internal services can be routed to the correct Banyan Access Tier.

When an organization “self-hosts” its Access Tiers, it is the responsibility of Admins to ensure DNS is configured correctly and that end users’ devices resolve service domain names to the IP addresses of the right Banyan Access Tiers for each service.

Banyan provides two options to register the public domain names that a given Access Tier can handle:

  1. Netagent site_domain_names - When you install the Access Tier, you can specify the configuration parameter site_domain_names. The Access Tier will report this configuration parameter to the Command Center so it is displayed in the UI as its valid Public Domains. The Access will also then reject any requests that do not match the patterns specified in site_domain_names.

    As of Netagent v1.35.0 (Mar-31-2021), the site_domain_names configuration parameter has been deprecated. It is now maintained only for backwards compatibility and will be fully removed in a future version of Netagent.

  2. Registered Domains - In this option, you register your Access Tier’s domains in the Command Center. Banyan will validate that your DNS records are configured correctly and can be used when publishing services to your end users.

    You must use the Registered Domains option in order to use Banyan’s Let’s Encrypt certificates for Hosted Websites capability.


To register a new domain, you need to perform the following steps:

Step 1. In the Banyan Command Center, note your Access Tier’s Public Address

1.1 Navigate to Directory & Infrastructure > Access Tiers and then your specific Access Tier.

1.2 Take note of the Public Address of your Access Tier.

The Public Address reported in the UI is the same as the site_address provided when you installed the Access Tier. It represents the canonical domain name of the Access Tier, and will be a IP Address or a Domain Name reachable via Public DNS and the internet.

Step 2. In your DNS Registrar, create the CNAME or A record for your Registered Domain

2.1 Navigate to your DNS Registrar where you manage your domain’s DNS configuration

2.2 Create a CNAME or A Record that maps your domain to the applicable Access Tier.

You may set up individual CNAME records as well as wildcard CNAME records:


Step 3. Back in the Banyan Command Center, Register Your Domain

3.1 In the Banyan Command Center, navigate to Directory & Infrastructure > Registered Domains and then click + Add Registered Domains.

3.2 Enter the Registration Domains Details:

  • Enter a valid Domain Name (supports wildcards)
  • Enter a description of the domain
  • Select the applicable Cluster and Access Tier

You may use wildcards (such as * while registering your domains; however, Let’s Encrypt certificates can only be issued to single-domain web services and not multi-domain (aka wildcard) web services.

3.3 Click Save.

Please allow up to 10 minutes while we validate the domain. Then, ensure the domain status shows Verified.

Domains can have a status of Verified or Pending.

That’s it! You have successfully registered your domain. Now you can publish Banyan services using this domain.


Unable to Register Domain

Sometimes, you may see an error message while registering a domain:

Error occured while registering domain: for orgID: 1234-abcd

This is typically because your DNS is not configured correctly, so the domain you are trying to register does not resolve to a Banyan Access Tier. The ACME protocol that’s used to procure Let’s Encrypt certificates uses domain validation so DNS needs to configured correctly for Banyan to manages issuance, renewal, and revocation.

Use the nslookup command (or an alternative such as dig or host) to check how your DNS records resolve. Once you configure your DNS so that your Registered Domains points to the applicable Access Tier domain registration will succeed.

Last modified: Aug 05, 2021