Configure DNS so that you can use your org's domains to publish Banyan services
- Updated on Dec 09, 2021
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 right Banyan Access Tiers for each service.
Banyan provides two options to register the public domain names that a given Access Tier can handle:
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
As of Netagent v1.35.0 (Mar-31-2021), the
site_domain_namesconfiguration parameter has been deprecated. It is now maintained only for backwards compatibility and will be fully removed in a future version of Netagent.
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 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:
*.yourdomain.com -CNAME- access_tier_public_address.iaas.com foo.yourdomain.com -CNAME- access_tier_public_address.iaas.com
Step 3. Register Your Domain in the Command Center
3.1 In the Command Center, navigate to Directory & Infrastructure > 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
*.example.com) 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.
Please allow up to 10 minutes while we validate the domain. Then, ensure the domain status shows
Domains can have a status of Verified or Pending.
Assuming you’ve successfully registered your domain, you should now be able to 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: example.com 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.
nslookup command (or an alternative such as
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.