Networking Properties

There are a few standard system properties used to alter the mechanisms and behavior of the various classes of the java.net package. Some are checked only once at startup of the VM, and therefore are best set using the -D option of the java command, while others have a more dynamic nature and can also be changed using the System.setProperty() API. The purpose of this document is to list and detail all of these properties.

If there is no special note, a property value is checked every time it is used.

IPv4 / IPv6

• java.net.preferIPv4Stack (default: false)
  If IPv6 is available on the operating system the underlying native socket will be, by default, an IPv6 socket which lets applications connect to, and accept connections from, both IPv4 and IPv6 hosts. However, in the case an application would rather use IPv4 only sockets, then this property can be set to true. The implication is that it will not be possible for the application to communicate with IPv6 only hosts.

• java.net.preferIPv6Addresses (default: false)
  When dealing with a host which has both IPv4 and IPv6 addresses, and if IPv6 is available on the operating system, the default behavior is to prefer using IPv4 addresses over IPv6 ones. This is to ensure backward compatibility: for example, for applications that depend on the representation of an IPv4 address (e.g. 192.168.1.1). This property can be set to true to change that preference and use IPv6 addresses over IPv4 ones where possible, or system to preserve the order of the addresses as returned by the system-wide resolver.

Both of these properties are checked only once, at startup.

Proxies

A proxy server allows indirect connection to network services and is used mainly for security (to get through firewalls) and performance reasons (proxies often do provide caching mechanisms).

Applications may use the ProxySelector.select(URI) method to determine the proxy that should be used for connecting to a given URI.

The following properties are used to configure the JDK default ProxySelector implementation. This is the ProxySelector returned by ProxySelector.getDefault() when no default ProxySelector was installed by ProxySelector.setDefault(ProxySelector)

• HTTP

  The following properties are used to configure the proxy that is selected for URIs with the http:// scheme.

  • http.proxyHost (default: <none>)
    The hostname, or address, of the proxy server.

  • http.proxyPort (default: 80)
    The port number of the proxy server.

  • http.nonProxyHosts (default: localhost|127.*|[::1])
    Indicates the hosts that should be accessed without going through the proxy. Typically this defines internal hosts. The value of this property is a list of hosts, separated by the '|' character. In addition, the wildcard character '*' can be used for pattern matching. For example, -Dhttp.nonProxyHosts="*.example.com|localhost" will indicate that every host in the example.com domain (including sub-domains) and the localhost should be accessed directly even if a proxy server is specified.

    The default value excludes all common variations of the loopback address.

• HTTPS

  The following properties are used to configure the proxy that is selected for URIs with the https:// scheme.

  • https.proxyHost (default: <none>)
    The hostname, or address, of the proxy server.

  • https.proxyPort (default: 443)
    The port number of the proxy server.

    The HTTPS protocol uses the same nonProxyHosts property as the HTTP protocol.

• FTP

  The following properties are used to configure the proxy that is selected for URIs with the ftp:// scheme.

  • ftp.proxyHost (default: <none>)
    The hostname, or address, of the proxy server.

  • ftp.proxyPort (default: 80)
    The port number of the proxy server.

  • ftp.nonProxyHosts (default: localhost|127.*|[::1])
    Indicates the hosts that should be accessed without going through the proxy. Typically this defines internal hosts. The value of this property is a list of hosts, separated by the '|' character. In addition, the wildcard character '*' can be used for pattern matching. For example, -Dftp.nonProxyHosts="*.example.com|localhost" will indicate that every host in the example.com domain (including sub-domains) and the localhost should be accessed directly even if a proxy server is specified.

    The default value excludes all common variations of the loopback address.

• SOCKS

  This is a lower-level proxy that is selected for all of the above URI schemes unless a scheme-specific proxy is configured. It is also selected for the socket:// URI scheme.

  • socksProxyHost (default: <none>)
    The hostname, or address, of the proxy server.

  • socksProxyPort (default: 1080)
    The port number of the proxy server.

  • socksNonProxyHosts (default: localhost|127.*|[::1])
    Indicates the hosts that should be accessed without going through the proxy. Typically this defines internal hosts. The value of this property is a list of hosts, separated by the '|' character. In addition, the wildcard character '*' can be used for pattern matching. For example, -DsocksNonProxyHosts="*.example.com|localhost" will indicate that every host in the example.com domain (including sub-domains) and the localhost should be accessed directly even if a proxy server is specified.

    The default value excludes all common variations of the loopback address.

  • socksProxyVersion (default: 5)
    The version of the SOCKS protocol supported by the server. The default is 5 indicating SOCKS V5. Alternatively, 4 can be specified for SOCKS V4. Setting the property to values other than these leads to unspecified behavior.

• java.net.useSystemProxies (default: false)
  On Windows systems, macOS systems, and Gnome systems it is possible to tell the java.net stack, setting this property to true, to use the system proxy settings (all these systems let you set proxies globally through their user interface). Note that this property is checked only once at startup.

Misc HTTP URL stream protocol handler properties

• http.agent (default: “Java/<version>”)
  Defines the string sent in the User-Agent request header in http requests. Note that the string “Java/<version>” will be appended to the one provided in the property (e.g. if -Dhttp.agent="foobar" is used, the User-Agent header will contain “foobar Java/1.5.0” if the version of the VM is 1.5.0). This property is checked only once at startup.

• http.keepAlive (default: true)
  Indicates if persistent connections should be supported. They improve performance by allowing the underlying socket connection to be reused for multiple HTTP requests. If this is set to true then persistent connections will be requested with HTTP 1.1 servers.

• http.maxConnections (default: 5)
  If HTTP keepalive is enabled (see above) this value determines the maximum number of idle connections that will be simultaneously kept alive, per destination.

• http.keepAlive.time.server and http.keepAlive.time.proxy

  These properties modify the behavior of the HTTP keepalive cache in the case where the server (or proxy) has not specified a keepalive time. If the property is set in this case, then idle connections will be closed after the specified number of seconds. If the property is set, and the server does specify a keepalive time in a "Keep-Alive" response header, then the time specified by the server is used. If the property is not set and also the server does not specify a keepalive time, then connections are kept alive for an implementation defined time, assuming http.keepAlive is true.

• http.maxRedirects (default: 20)
  This integer value determines the maximum number, for a given request, of HTTP redirects that will be automatically followed by the protocol handler.

• http.auth.digest.validateServer (default: false)

• http.auth.digest.validateProxy (default: false)

  These properties modify the behavior of the HTTP digest authentication mechanism. Digest authentication provides a limited ability for the server to authenticate itself to the client (i.e. By proving it knows the user's password). However, not all HTTP servers support this capability and by default it is turned off. The properties can be set to true to enforce this check for authentication with either an origin or proxy server, respectively.

• http.auth.ntlm.domain (default: <none>)
  NTLM is another authentication scheme. It uses the java.net.Authenticator class to acquire usernames and passwords when they are needed. However, NTLM also needs the NT domain name. There are 3 options for specifying that domain:

  1. Do not specify it. In some environments the domain is actually not required and the application does not have to specify it.

  2. The domain name can be encoded within the username by prefixing the domain name, followed by a backslash '\' before the username. With this method existing applications that use the authenticator class do not need to be modified, as long as users are made aware that this notation must be used.

  3. If a domain name is not specified as in method 2) and this property is defined, then its value will be used as the domain name.

• http.auth.digest.reEnabledAlgorithms (default: <none>)
  By default, certain message digest algorithms are disabled for use in HTTP Digest authentication due to their proven security limitations. This only applies to proxy authentication and plain-text HTTP server authentication. Disabled algorithms are still usable for HTTPS server authentication. The default list of disabled algorithms is specified in the java.security properties file and currently comprises MD5 and SHA-1. If it is still required to use one of these algorithms, then they can be re-enabled by setting this property to a comma separated list of the algorithm names.

• jdk.https.negotiate.cbt (default: <never>)
  This controls the generation and sending of TLS channel binding tokens (CBT) when Kerberos or the Negotiate authentication scheme using Kerberos are employed over HTTPS with HttpsURLConnection. There are three possible settings:

  1. "never". This is also the default value if the property is not set. In this case, CBTs are never sent.

  2. "always". CBTs are sent for all Kerberos authentication attempts over HTTPS.

  3. "domain:<comma separated domain list>" Each domain in the list specifies destination host or hosts for which a CBT is sent. Domains can be single hosts like foo, or foo.com, or literal IP addresses as specified in RFC 2732, or wildcards like *.foo.com which matches all hosts under foo.com and its sub-domains. CBTs are not sent to any destinations that don't match one of the list entries

  The channel binding tokens generated are of the type "tls-server-end-point" as defined in RFC 5929.

• jdk.http.maxHeaderSize (default: 393216 or 384kB)
  This is the maximum header field section size that a client is prepared to accept. This is computed as the sum of the size of the uncompressed header name, plus the size of the uncompressed header value, plus an overhead of 32 bytes for each field section line. If a peer sends a field section that exceeds this size a ProtocolException will be raised. This applies to all versions of the HTTP protocol. A value of zero or a negative value means no limit. If left unspecified, the default value is 393216 bytes.

All these properties are checked only once at startup.

Address Cache

The java.net package, when doing name resolution, uses an address cache for both security and performance reasons. Any address resolution attempt, be it forward (name to IP address) or reverse (IP address to name), will have its result cached, whether it was successful or not, so that subsequent identical requests will not have to access the naming service. These properties allow for some tuning on how the cache is operating.

• networkaddress.cache.ttl (default: see below)
  Value is an integer corresponding to the number of seconds successful name lookups will be kept in the cache. A value of -1, or any other negative value for that matter, indicates a “cache forever” policy, while a value of 0 (zero) means no caching. The default value is -1 (forever) if a security manager is installed, and implementation-specific when no security manager is installed.

• networkaddress.cache.stale.ttl (default: see below)
  Value is an integer corresponding to the number of seconds that stale names will be kept in the cache. A name is considered stale if the TTL has expired and an attempt to lookup the host name again was not successful. This property is useful if it is preferable to use a stale name rather than fail due to an unsuccessful lookup. A value of 0 (zero) or if the property is not set means do not use stale names. Negative values are ignored. The default value is implementation-specific.

• networkaddress.cache.negative.ttl (default: 10)
  Value is an integer corresponding to the number of seconds an unsuccessful name lookup will be kept in the cache. A value of -1, or any negative value, means “cache forever”, while a value of 0 (zero) means no caching.

Since these 3 properties are part of the security policy, they are not set by either the -D option or the System.setProperty() API, instead they are set as security properties.

Unix domain sockets

Calling ServerSocketChannel.bind with a null address parameter will bind to an automatically assigned socket address. For Unix domain sockets, this means a unique path in some predefined system temporary directory. There are a number of system (and networking) properties that affect this behavior.

Unix domain socket addresses are limited in length to approximately 100 bytes (depending on the platform), it is important to ensure that the temporary directory's name together with the filename used for the socket (currently a name similar to socket_1679697142) does not exceed this limit. The following properties can be used to control the selection of this directory:

• jdk.net.unixdomain.tmpdir This can be set as a networking property in conf/net.properties If set, this specifies the directory to use for automatically bound server socket addresses. On some platforms, (eg some Unix systems) this will have a predefined default value. On others, (eg Windows) there is no default value. Either way, it is always possible to override the networking property with a system property of the same name set on the command line. If neither of the networking nor system property are set, then some systems (eg Windows) may check a commonly used environment variable as temporary directory.

• java.io.tmpdir If the previous step fails to locate a directory to use, then the directory identified by the system property java.io.tmpdir is used.

More information about the platform specific behavior can be seen in the conf/net.properties configuration file.

Implicit binding of a SocketChannel

If a client socket is connected to a remote destination without calling bind first, then the socket is implicitly bound. In this case, Unix domain sockets are unnamed (ie. their path is empty). This behavior is not affected by any system or networking properties.

Enhanced exception messages

By default, for security reasons, exception messages do not include potentially sensitive security information such as hostnames or Unix domain socket address paths. The following property can be used to relax this restriction, for debugging and other purposes.

• jdk.includeInExceptions This is typically set to a comma separated list of keywords that refer to exception types whose messages may be enhanced with more detailed information. If the value includes the string hostInfo then socket addresses will be included in exception message texts (eg hostnames, Unix domain socket address paths).