IBM Support

Understanding, Tuning, and Testing the InetAddress Class and Cache

Troubleshooting


Problem

The java.net.InetAddress class provides methods to resolve hostnames to their IP addresses. This class also has a cache where successful and unsuccessful hostname resolutions may be stored. The following provides information on this class and this cache in the context of a WebSphere Application Server environment.

Resolving The Problem

 

Background

The InetAddress class provides methods to resolve hostnames to their IP addresses. These methods rely on the operating system to perform resolution. The operating system will attempt to resolve a given hostname by executing a lookup on either a file, a DNS server, or some other name service. Once the operating system completes the lookup, it will pass the result back to the JVM. The result, successful or unsuccessful, may then be stored in the InetAddress Cache.

How the operating system performs the resolution is not controlled by the JVM, and the JVM does not directly query any file, DNS server, or name service. Further, the JVM does not cache the address of any DNS server that might be used in the lookup process, and the JVM is not involved in DNS failover. Finally, the InetAddress Cache may not be the only name service cache involved; many operating systems have their own name service cache that may be used.
 

InetAddress Cache Default Behavior

The default behavior for the InetAddress Cache successful name resolutions varies depending on whether or not Java 2 Security is enabled:
 
   If Java 2 Security is enabled, then successful name resolutions are cached forever.
   If Java 2 Security is disabled, then successful name resolutions are cached for 30 seconds.
   Unsuccessful name resolutions are cached for 10 seconds, regardless of the state of Java 2 Security.
 

InetAddress Cache Tuning

The InetAddress Cache can be tuned in two ways: the time to cache successful name resolutions and the time to cache unsuccessful name resolutions can both be modified. When tuning the InetAddress Cache, values are expressed as integers with a unit of seconds. A value of -1 is interpreted as 'cache forever', and a value of 0 is interpreted as 'never cache'.

There are two different methods by which the InetAddress Cache can be tuned:

Method One: Security Properties via java.security file

  • To set the time to cache successful name resolutions for the InetAddress Cache,
    edit the following in the java.security file to reflect the desired value:
     
    • networkaddress.cache.ttl=value

    To set the time to cache unsuccessful name resolutions for the InetAddress Cache,
    edit the following in the java.security file to reflect the desired value:
     
    • networkaddress.cache.negative.ttl=value

Method Two: System Properties via Generic JVM arguments

  • To set the time to cache successful name resolutions for the InetAddress Cache,
    add the following Generic JVM argument with the desired value:
     
    • -Dsun.net.inetaddr.ttl=value

    To set the time to cache unsuccessful name resolutions for the InetAddress Cache,
    add the following Generic JVM argument with the desired value:
     
    • -Dsun.net.inetaddr.negative.ttl=value

Note: Security Properties set by the java.security file take precedence over System Properties set by Generic JVM arguments.

To disable address caching for Web services, you need to set an additional JVM custom property disableWSAddressCaching to true. Use this property to disable address caching for Web services. If your system typically runs with lots of client threads, and you encounter lock contention on the wsAddrCache cache, you can set this custom property to true, to prevent caching of the Web services data.

If you specify networkaddress.cache.ttl with a value of zero or any other positive integer, this property must be set to true to avoid caching of an IP address in the webservice engine.

 

Caching InetAddress.getLocalHost() Results

The InetAddress class contains a method called getLocalHost. This method is used to return the local host as an InetAddress object. By default, the result of executing the getLocalHost method will not be cached.

To reverse the default behavior and cache the result of getLocalHost, add the following Generic JVM argument:
 
  • -Dcom.ibm.cacheLocalHost=true

This tuning will improve performance but is only advised if the local host address will not change. Please note that this tuning is only available on the IBM Java SDK. As such, this tuning is only available with WebSphere Application Server on AIX, Linux, and Windows. This tuning is not available with WebSphere Application Server on Solaris or HP-UX.
 

Performance Issues with InetAddress Resolutions

By default, InetAddress resolutions requiring the network will be carried out over IPv6 if the operating system supports both IPv4 and IPv6. However, if the name service does not support IPv6, then a performance issue may be perceived as the doomed IPv6 query must first timeout before a successful IPv4 query can be made.

To reverse the default behavior and use IPv4 over IPv6, add the following Generic JVM argument:
 
  • -Djava.net.preferIPv4Stack=true
 

Recommendations

As every environment is different, recommendations beyond those provided above are not available. When tuning parameters such as these, consider the following:
 
  • Reliability of the name service (file, DNS server, etc)
  • Impact of name service traffic (DNS or otherwise) on the network
  • Lease time for dynamic IP addresses
  • DNS time-to-live value
  • Operating system cache of name service results

This list is by no means exhaustive.
 

Testcases: Inspecting Configuration & Behavior

In some situations, it may be necessary to inspect the configuration or behavior of the InetAddress Cache within a running JVM; the following describes methodologies that may be helpful.

Both cases below make use of either the attached JSP (InetAddressInfoTest.jsp) or the attached application (InetAddressInfoTest.ear). Functionally, the JSP and the application are identical. The JSP is the preferred choice for most scenarios given its simplicity. However, if Java 2 Security is enabled, then the application is suggested over the JSP as the application is pre-configured with the necessary security permissions to allow successful execution.
  • InetAddressInfoTest.jspInetAddressInfoTest.ear
     
  • JSP Instructions:
    Simply place the JSP into an already deployed application on the application server of interest, then browse to the JSP.

    Application Instructions:
    Deploy the application to the application server of interest taking all the defaults, start the application, then browse to http://<host>:<port>/InetAddr/InetAddressInfoTest.jsp.

Inspecting Configuration:
  • Some of the tuning discussed above involves setting Security Properties. Unlike System Properties, inspecting the Security Properties of a running JVM is a non-trivial task. The attached seeks to make this task easier by outputting the values of all System and Security Properties discussed above, sample output follows:
     
    • Security Property: networkaddress.cache.ttl = null; default: null
      Security Property: networkaddress.cache.negative.ttl = 10; default: 10
      System Property: sun.net.inetaddr.ttl = null; default: null
      System Property: sun.net.inetaddr.negative.ttl = null; default: null
      System Property: com.ibm.cacheLocalHost = null; default: null
      System Property: java.net.preferIPv4Stack = null; default: null

Inspecting Behavior:
  • Going a step further, the attached has the ability to trigger InetAddress resolutions any number of times, at a given interval, and for a given host. The InetAddress Cache behavior can be inspected by combining the attached with diagnostics for the name service.

    In the case of an unencrypted DNS serving as the name service, a simple packet trace can be collected at the time of the test to determine when queries are actually being made. When looking at either the packet trace or the test results, please note that DNS queries often generate a list of more than one address for a given hostname. Load balancing is often achieved by a DNS server through the reordering of this list over time. While there is no standard for how a list of DNS results may be used, typically the list is used in order until communication is established.

    In order for the test to be successful and serve as a reflection of the behavior of just the InetAddress Cache, all other name service caches will need to be disabled which includes but is not limited to any operating system name service cache that may exist.

    For more information on packet traces, see the following TechNote:
     
 

[{"Product":{"code":"SSEQTP","label":"WebSphere Application Server"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Not Applicable","Platform":[{"code":"PF002","label":"AIX"},{"code":"PF010","label":"HP-UX"},{"code":"PF016","label":"Linux"},{"code":"PF027","label":"Solaris"},{"code":"PF033","label":"Windows"}],"Version":"9.0;8.5.5;8.5;8.0;7.0","Edition":"Edition Independent","Line of Business":{"code":"LOB45","label":"Automation"}},{"Product":{"code":"SSNVBF","label":"Runtimes for Java Technology"},"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Component":"Java SDK","Platform":[{"code":"","label":""}],"Version":"","Edition":"","Line of Business":{"code":"LOB36","label":"IBM Automation"}}]

Document Information

Modified date:
10 January 2024

UID

swg21207534