Register Domains

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

  • Updated on Nov 09, 2022

This article describes features that are only available in the Banyan Business edition and Banyan Enterprise edition.


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 admin’s responsibility to ensure DNS is configured correctly and that end users’ devices resolve service domain names to the IP addresses of the correct 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 Tier 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 the Hosted Websites capability.


To register a new domain, complete the following steps:

Step 1: In Banyan’s Command Center, note your Access Tier’s public address

1.1 Navigate from Networks > Access Tiers, and then to 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 it will be an 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: Register your domain in the Command Center

3.1 In the Command Center, navigate to Networks > Registered Domains and then select + 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 (i.e., wildcard) web services.

3.3 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.

Once the domain is registered, Banyan services can be published 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 due to your DNS not being correctly configured. As a result, the domain you’re trying to register doesn’t 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 be configured correctly for Banyan to manage 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 domain points to the right Access Tier domain, registration should succeed.

Can’t find what you’re looking for?

We’re happy to help. Contact our team.