Hostname resolution in the Endeca Server

This topic discusses how Endeca Server performs hostname resolution.

The Endeca Server Java application running in WebLogic relies on the hostname resolution by checking the network configuration on your machine. In the majority of network configurations, your machine is already set up properly and the Endeca Server can resolve its hostname correctly through DNS lookup, at startup. If this is the case, you can ignore this topic.

In some instances, however, additional troubleshooting might be required. This topic discusses the details.

The Endeca Server uses a Java System call to obtain the mapping between an externally-resolvable IP address and the machine's hostname. The Java System call is specific to the operating system and to the network setup on your machine. For example, if DNS is configured in an enterprise-wide domain by the IT department, the hostname resolution works fine (even if the /etc/hosts file on your machine is empty). However, if your /etc/hosts file includes any entries, Endeca Server uses this file (overriding what it finds from the DNS lookup), and this may prevent the Endeca Server to properly resolve its hostname. In such cases, you receive the "Could not connect to Endeca Server" error.

The summary is that Endeca Server relies on the hostname resolution by ultimately checking the network configuration on your machine which is done through /etc/hosts. That is, in the end, Endeca Server does not use any other OS-specific methods for determining the host name, but relies on /etc/hosts. In the /etc/hosts file, Endeca Server looks for the hostname that is mapped to the site-local IP address. It is important to know that Endeca Server cannot use a mapping to localhost. Therefore, to ensure host name resolution in the Endeca Server, check that your /etc/hosts file includes as its first entry the mapping from the machine-specific IP address to the full name of your machine. (This file can also include a mapping to localhost, as long as this entry is not the first, that is, it is listed after the mapping to the full name of your machine).

The following statements describe the Endeca Server’s hostname resolution logic in detail.

To resolve the hostname to the IP address that Endeca Server will use at startup, Endeca Server does the following:

It checks the DNS lookup first and compares it with /etc/hosts.
If it finds conflicting information, it uses /etc/hosts as the final source of truth. That is, Endeca Server relies on the /etc/hosts file, and does not rely on /etc/hostname and DNS lookup. Endeca Server relies on the fact that the /etc/hosts file contains an unambiguous mapping between either:
- The site-local IP address and the Fully Qualified Domain Name (FQDN) of this machine, or
- The site-local IP address and the first portion of the FQDN.
If Endeca Server finds such a mapping, it uses the first part of the FQDN as the hostname, at startup time. For example, if the mapping in /etc/hosts is:
```
192.168.0.1 myname.example.com
```
Endeca Server will use myname as the hostname, at startup. Similarly, if the mapping is:
```
192.168.0.1 myname
```
Endeca Server will use myname as the hostname, at startup.
If the /etc/hosts file contains several entries for the same site-local IP address, Endeca Server uses the first hostname it finds in the file.
Important: The mapping from a site-local IP address to localhost is not accepted by the Endeca Server and does not allow it to resolve the host name. If /etc/hosts contains this mapping it should not be the first one listed. If it is the only mapping or the first mapping, Endeca Server issues an error indicating that it cannot resolve an IP address to the host name for its operations.
For example, this mapping in /etc/hosts is not resolvable by the Endeca Server:
```
192.168.0.1 localhost
```
Similarly, this mapping is also not resolvable by the Endeca Server:
```
127.0.0.1 localhost.localdomain localhost 
::1 localhost6.localdomain localhost
```
These mappings are resolvable (myhostname is listed first, before localhost, and it is first mapped to the site-local externally-resolvable IP address):
```
192.168.0.45 myhostname localhost.localdomain localhost
```
```
127.0.0.1 myhostname localhost.localdomain localhost 
::1 myhostname localhost6.localdomain localhost
```
Next, if Endeca Server cannot find the site-local IP address in /etc/hosts, it looks for any other address that is from the Ethernet network adapter configured on the system (this is another non-loopback address that the system might have), mapped to the hostname, and attempts to use it.
Finally, if it cannot find either of these addresses, Endeca Server falls back to using the first IP loopback address it can find on the system (this address is typically of the type 127.0.0.1).

To conclude, if you observe connection problems with the Endeca Sever, reconfigure networking configuration on the Endeca Server machines, so that /etc/hosts includes a mapping from the site-local IP address to FQDN, or the first portion of the correct, Fully Qualified Domain Name. If /etc/hosts includes a mapping to localhost, it should not be the only entry, and should not be the first entry in this file. Do not use any other OS-specific methods for determining the hostname — only use the configuration in /etc/hosts, because ultimately, this is the configuration that Endeca Server relies on.