Set up DNS wildcards for virtual hosts
7 minute read
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 *.example.com
).
A virtual host is a server, or pool of servers, that can host multiple domain names (for example, company1.api.example.com
and company2.api.example.com
). To use virtual hosting for the
API Gateway or API Manager, 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 *.example.com
to 192.0.2.11
).
This setting enables you to run more than one website, or set of REST APIs, on a single host machine (in this case, 192.0.2.11
). Each domain name can have its own host name, paths, APIs, and so on. For example:
https://company1.api.example.com:8080/api/v1/test
https://company2.api.example.com:8080/api/v2/test
DNS workflow
When a client makes an HTTP request to a specific URL, such as http://www.example.com
, 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 www.example.com
machine. This usually involves the following workflow:
- Check the
/etc/hosts
file for the specified name, and if that fails, make a DNS request. - Send the DNS request to the default DNS server for the client system, which refers the client to the server for
example.com
(referral), or makes the request on the client’s behalf (recursion). - The DNS server that manages the
www.example.com
domain responds with a record that specifies the IP address ofwww.example.com
. - The client contacts that IP address, and includes a
Host
header when making its request (Host:www.example.com
). - 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 example.com
into subdomains, one for each hosted site. This provides each site with its own distinct namespace (for example, company1.example.com
, company2.example.com
, company3.example.com
, and so on).
When using API Manager, you can divide the parent domain (for example, apiportal.io
) into subdomains, one for each hosted organization. This provides each organization with its own distinct namespace (for example, company1.apiportal.io
, company2.apiportal.io
, company3.apiportal.com
, 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 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 http://www.isc.org/downloads/bind/.
Linux 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:
/etc/named.conf /etc/bind/named.conf
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
control the behavior of the servicezone
indicates how each autonomous part of the domain name tree should behave
The example shown in this topic uses the simplest options, and it shows a single domain used for API Manager.
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 "named.pid";
allow-recursion { any; };
allow-transfer { any; };
allow-update { any; };
forwarders { 10.253.253.253; 10.252.252.252; };
};
The example options are described as follows:
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 127.0.0.1
.
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, example.com
or apiportal.io
) 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 127.0.0.1
address. For example:
zone "localhost" IN {
type master;
file "localhost.zone";
allow-transfer { any; };
};
zone "0.0.127.in-addr.arpa" IN {
type master;
file "127.0.0.zone";
allow-transfer { any; };
};
These settings configure addresses for mapping localhost
to 127.0.0.1
, and mapping 127.0.0.1
back to localhost
when required. These example options are described as follows:
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 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 the 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 "example.com." IN {
type master;
file "example.zone";
allow-transfer { any;
};
};
This is almost identical to the localhost
zone already configured.
Similarly, for an API Manager domain:
zone "apiportal.io." IN {
type master;
file "apiportal.zone";
allow-transfer { any;
};
};
Configure domain zone files
Finally, your zone
configuration now includes references to two separate domain zone files (in this case, localhost.zone
and your wildcard zone (example.zone
or apiportal.zone
). These domain zone files use a standard format, which is defined in RFC 1035:http://www.ietf.org/rfc/rfc1035.txt. For more details, see also Wikipedia:http://en.wikipedia.org/wiki/Zone_file.
The domain zone files dictate how the server responds to requests for data in the specified zone. For example, your basic localhost.zone
domain is as follows:
@ IN SOA root.acmecorp.com. (
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 127.0.0.1
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 settingsNS
specifies that the name server for this domain islocalhost
A
specifies that the address for localhost is127.0.0.1
Your wildcard domain is similar. For example, the contents of example.zone
or apiportal.zone
are as follows:
@ IN SOA . root.acmecorp.com. (
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 192.168.0.10
* IN A 192.168.0.10
This domain has the SOA
, NS
, and A
records like the localhost
zone, but also adds a *
record. This matches any subdomain of example.com
or apiportal.io
to resolve to the specified IP address.