Monday, July 1, 2013

QT013: Resolving DNS Resolution Issues in CIOS

Quick Tip #013: Resolving DNS Resolution Issues in CIOS

The Domain Name System (DNS) is a global distributed network of servers that is used to resolve hostnames such as to an IP address which can be used by the network layer to connect to a remote host.

Common DNS Issues

DNS issues usually manifest themselves as UnknownHostExceptions in the system log.  An UnknownHostException is generated when an activity tries to resolve the hostname of a remote host and the DNS server either does not respond or does not have an entry for that host.  Another common issue occurs when your Cast Iron appliance resides behind the same firewall as the remote host and the DNS server returns the external address rather than the internal address.

Ensure DNS Servers are Properly Configured

You may specify multiple DNS servers in the networking configuration of CIOS.  This can be done via the Command Line Interface (CLI) using the net set nameserver command or under the networking panel in the Web Management Console  (WMC).  The first step in troubleshooting DNS is making sure that these settings are correct.  If you are able to resolve other hostnames and have isolated the issue to a specific remote host, there are a few other options to consider.

Use the IP Address Instead

Often you can bypass the DNS resolution process by replacing the hostname for a remote server with its DNS address.  This is the simplest solution, however, there are some drawbacks to it under certain conditions.  By bypassing the DNS system you are taking responsibility for ensuring that if the IP address of the remote host changes, the change is made in your configuration properties.  Some endpoints such as Domino connect to a gateway which redirects the connection to another hostname.  In these cases, specifying the gateways IP address will not resolve the problem unless the gateway is configured to redirect to an IP address rather than a hostname.  In this case you will need to make sure that cast iron can resolve the hostname.  Also, there are SSL implications to using the IP address instead of the DNS entry.  SSL typically checks that the Common Name of a certificate presented by a remote server matches the hostname used to resolve it.  If you use the IP address this check will fail.  You could disable hostname verification, but there is a better way . . .

Add an etc/hosts Entry

CIOS is, underneath the covers, a linux server and linux servers do have their own internal name resolution process that happens before reaching out to the DNS server.  If your DNS servers do not properly resolve a given hostname you may statically add it to the etc/hosts file.  When resolving a hostname, CIOS will first check for an etc/hosts entry and only if the address is not resolved by etc/hosts, contact the DNS server.  Again, by bypassing DNS you are taking responsibility for maintaining the hostname to IP address mapping.  However, this method has the benefit of allowing your orchestrations to use the actual hostname to connect which means that you can maintain the hostname to IP mapping in one place and SSL can perform hostname verification.  etc/hosts entries can be added via the CLI by using the net add etchost address <ip> hostname <name> command where <ip> is the remote hosts ip address and <name> is the FQDN.