Configure a DNS service with wildcards for virtual hosting


The Domain Name System (DNS) is a hierarchical distributed naming system for resources on the Internet or a private network. It translates domain names to numerical IP addresses used to locate services and devices worldwide, and associates details with domain names assigned to each resource. You can use wildcard DNS records to specify multiple domain names by using an asterisk in the domain name (such as *

A virtual host is a server, or pool of servers, that can host multiple domain names (for example, and To use virtual hosting for the API Gateway, you need to be able to use different host names to refer to the same destination server. A convenient way to do this is by using a DNS service to specify wildcard entries for physical host names (for example, by setting * to

This setting enables you to run more than one website, or set of REST APIs, on a single host machine (in this case, Each domain name can have its own host name, paths, APIs, and so on. For example:

[Note] Note

This topic explains how to set up DNS wildcards for virtual hosts. This is a prerequisite for configuring the API Gateway for virtual hosts. For more details, see the API Gateway User Guide.

DNS workflow

When a client makes an HTTP request to a specific URL, such as, the client must decide which IP address to connect to. In this case, the client makes a request on the local name service for the address of the machine. This usually involves the following workflow:

  1. Check the /etc/hosts file for the specified name, and if that fails, make a DNS request.

  2. Send the DNS request to the default DNS server for the client system, which refers the client to the server for (referral), or makes the request on the client's behalf (recursion).

  3. The DNS server that manages the domain responds with a record that specifies the IP address of

  4. The client contacts that IP address, and includes a Host header when making its request (Host:

  5. The server can use this Host header to distinguish requests to different sites (virtual hosts) that use the same physical hardware and HTTP server process.

You can divide a parent domain such as into subdomains, one for each hosted site. This provides each site with its own distinct namespace (for example,,,, and so on).

BIND DNS software

Internet Systems Consortium (ISC) BIND is the de facto standard DNS server used on the Internet. It works on a wide variety of LINUX and UNIX systems, and on Microsoft Windows. Windows Server operating systems can also use the Windows DNS service. The examples in this topic describe the configuration for BIND only. For more details, see

UNIX systems generally enable the configuration of BIND to be installed using a package manager. For example, for Ubuntu systems, you can use the following command:

$ sudo apt-get install bind9

The service and packages are generally called bind, bind9, or named. For example, on Ubuntu, you can restart BIND using the following command:

$ sudo /etc/init.d/bind9 start 
$ sudo /etc/init.d/bind9 stop 
$ sudo /etc/init.d/bind9 restart

Configure a wildcard domain

You can configure BIND using the named.conf configuration file, which is typically installed in one of the following locations:


This configuration file is typically set up with include entries to make configuration and upgrade easier, and which should be easy to follow. The simple example described in this topic uses a flat file only. There are two main parts to the configuration:

  • options to control the behavior of the service

  • zone indicates how each autonomous part of the domain name tree should behave

The example shown in this topic uses the simplest options.

Configure DNS options

The following are some example DNS options that you can configure for your installation in the named.conf file:

options { 
    directory "."; // e.g., /var/named 
    listen-on port 8866 { any; }; // remove this for production 
    pid-file ""; 
    allow-recursion { any; }; 
    allow-transfer { any; }; 
    allow-update { any; }; 
    forwarders {;; }; 

The example options are described as follows:

Option Description
directory This is normally set to a directory on a writeable filesystem, such as /var/bind. This example is set to the current directory (".").
listen-on port This example is set to 8866 for testing, but you should leave this blank for real DNS use in a production environment. Most DNS clients such as Web browsers always request on the standard DNS port 53. You can also configure debugging tools such as dig and nslookup to try other ports.
pid-file This example sets up named to run in the current directory (or /var/named if configured), and gives it a name to store its lock file.
allow- The example allow- options are permissive, and allow any external host to use this name server, update it dynamically, and transfer a dump of its domains. This makes it unsuitable for external exposure. To restrict these allow- options to the local system, change the any settings to
forwarders Requests that cannot be serviced locally are forwarded to the specified servers, which are the default DNS servers for the site. Specifying forwarders enables you to use this name server as your local DNS. It can forward requests for sites outside your domain (for example, ) to the forwarding name servers. This enables your test environment to coexist with your normal name servers.

Configure default zones

The next step is to configure default zones for the address. For example:

zone "localhost" IN { 
     type master; 
     file ""; 
     allow-transfer { any; }; 
zone "" IN { 
     type master; 
     file ""; 
     allow-transfer { any; };

These settings configure addresses for mapping localhost to, and mapping back to localhost when required. These example options are described as follows:

Option Description
type Specifies that this is the master server for localhost.
file Specifies the domain zone file that contains the records for the domain (for more details, see the section called “Configure domain zone files”).
allow-transfer Specifies addresses that are allowed to transfer zone information from the zone server. The default any setting means that the contents of the domain can be transferred to anyone.

Configure logging

The following settings provide some default logging configuration:

logging { 
   channel default_syslog { 
     file "named.log";  
     severity debug 10; 

For example, you can change the file setting to /var/log/named.log, or change the severity level.

Configure a wildcard domain

You must now configure your wildcard domain. Here you specify the name of the domain for which to serve wildcard addresses. For example:

zone "" IN { 
   type master; 
   file ""; 
   allow-transfer { any; 

This is almost identical to the localhost zone already configured.

Configure domain zone files

Finally, your zone configuration now includes references to two separate domain zone files (in this case, and your wildcard zone ( ). These domain zone files use a standard format, which is defined in RFC 1035: For more details, see also Wikipedia:

The domain zone files dictate how the server responds to requests for data in the specified zone. For example, your basic domain is as follows:

@  IN SOA ( 
            20131021  ; serial number of zone file (yyyymmdd##) 
            3H        ; refresh time
            15M       ; retry time in case of problem 
            1W        ; expiry time
            1D )      ; maximum caching time in case of failed lookups 
   IN NS    @ 
   IN A

In this file, @ is shorthand for the domain, and describes the first (and only) record in the file. @ specifies the name of the zone, and has the following associated records:

  • SOA—specifies details about the zone, including various serial and timer settings

  • NS—specifies that the name server for this domain is localhost

  • A—specifies that the address for localhost is

Your wildcard domain is similar. For example, the contents of are as follows:

@  IN SOA  . ( 
             20130903  ; serial number of zone file (yyyymmdd##)  	
             604800    ; refresh time 	
             86400     ; retry time in case of problem  
             2419200   ; expiry time
             604800)   ; maximum caching time in case of failed lookups
   IN NS     . 
   IN A 
*  IN A

This domain has the SOA, NS, and A records like the localhost zone, but also adds a * record. This matches any subdomain of to resolve to the specified IP address.