1 <!DOCTYPE HTML>
   2 <!--
   3  Copyright (c) 1998, 2017, Oracle and/or its affiliates. All rights reserved.
   4  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   5 
   6  This code is free software; you can redistribute it and/or modify it
   7  under the terms of the GNU General Public License version 2 only, as
   8  published by the Free Software Foundation.  Oracle designates this
   9  particular file as subject to the "Classpath" exception as provided
  10  by Oracle in the LICENSE file that accompanied this code.
  11 
  12  This code is distributed in the hope that it will be useful, but WITHOUT
  13  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15  version 2 for more details (a copy is included in the LICENSE file that
  16  accompanied this code).
  17 
  18  You should have received a copy of the GNU General Public License version
  19  2 along with this work; if not, write to the Free Software Foundation,
  20  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  21 
  22  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  23  or visit www.oracle.com if you need additional information or have any
  24  questions.
  25 -->
  26 <HTML>
  27 <HEAD>
  28         <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
  29         <TITLE>Networking Properties</TITLE>
  30 </HEAD>
  31 <BODY LANG="en-US" DIR="LTR">
  32 <H1 style="text-align:center">Networking Properties</H1>
  33 <P>There are a few standard system properties used to
  34 alter the mechanisms and behavior of the various classes of the
  35 java.net package. Some are checked only once at startup of the VM,
  36 and therefore are best set using the -D option of the java command,
  37 while others have a more dynamic nature and can also be changed using
  38 the <a href="../../lang/System.html#setProperty(java.lang.String,%20java.lang.String)">System.setProperty()</a> API.
  39 The purpose of this document is to list
  40 and detail all of these properties.</P>
  41 <P>If there is no special note, a property value is checked every time it is used.</P>
  42 <a id="Ipv4IPv6"></a>
  43 <H2>IPv4 / IPv6</H2>
  44 <UL>
  45         <LI><P><B>java.net.preferIPv4Stack</B> (default: false)<BR>
  46         If IPv6 is available on the operating system the
  47         underlying native socket will be, by default, an IPv6 socket which
  48         lets applications connect to, and accept connections from, both
  49         IPv4 and IPv6 hosts. However, in the case an application would
  50         rather use IPv4 only sockets, then this property can be set to <B>true</B>.
  51         The implication is that it will not be possible for the application
  52         to communicate with IPv6 only hosts.</P>
  53         <LI><P><B>java.net.preferIPv6Addresses</B> (default: false)<BR>
  54         When dealing with a host which has both IPv4
  55         and IPv6 addresses, and if IPv6 is available on the operating
  56         system, the default behavior is to prefer using IPv4 addresses over
  57         IPv6 ones. This is to ensure backward compatibility, for example
  58         applications that depend on the representation of an IPv4 address
  59         (e.g. 192.168.1.1). This property can be set to <B>true</B> to
  60         change that preference and use IPv6 addresses over IPv4 ones where
  61         possible, or <B>system</B> to preserve the order of the addresses as
  62     returned by the operating system.</P>
  63 </UL>
  64 <P>Both of these properties are checked only once, at startup.</P>
  65 <a id="Proxies"></a>
  66 <H2>Proxies</H2>
  67 <P>A proxy server allows indirect connection to network services and
  68 is used mainly for security (to get through firewalls) and
  69 performance reasons (proxies often do provide caching mechanisms).
  70 The following properties allow for configuration of the various type
  71 of proxies.</P>
  72 <UL>
  73         <LI><P>HTTP</P>
  74         <P>The following proxy settings are used by the HTTP protocol handler.</P>
  75         <UL>
  76                 <LI><P><B>http.proxyHost</B> (default: &lt;none&gt;)<BR>
  77                 The hostname, or address, of the proxy server
  78                 </P>
  79                 <LI><P><B>http.proxyPort</B> (default: 80)<BR>
  80                 The port number of the proxy server.</P>
  81                 <LI><P><B>http.nonProxyHosts</B> (default:  localhost|127.*|[::1])<BR>
  82                 Indicates the hosts that should be accessed without going
  83                 through the proxy. Typically this defines internal hosts.
  84                 The value of this property is a list of hosts,
  85                 separated by the '|' character. In addition the wildcard
  86                 character '*' can be used for pattern matching. For example
  87                 <code>-Dhttp.nonProxyHosts=&rdquo;*.foo.com|localhost&rdquo;</code>
  88                 will indicate that every hosts in the foo.com domain and the
  89                 localhost should be accessed directly even if a proxy server is
  90                 specified.</P>
  91                 <P>The default value excludes all common variations of the loopback address.</P>
  92         </UL>
  93         <LI><P>HTTPS<BR>This is HTTP over SSL, a secure version of HTTP
  94         mainly used when confidentiality (like on payment sites) is needed.</P>
  95         <P>The following proxy settings are used by the HTTPS protocol handler.</P>
  96         <UL>
  97                 <LI><P><B>https.proxyHost</B>(default: &lt;none&gt;)<BR>
  98                 The hostname, or address, of the proxy server
  99                 </P>
 100                 <LI><P><B>https.proxyPort</B> (default: 443)<BR>
 101                 The port number of the proxy server.</P>
 102                 <P>The HTTPS protocol handler will use the same nonProxyHosts
 103                 property as the HTTP protocol.</P>
 104         </UL>
 105         <LI><P>FTP</P>
 106         <P>The following proxy settings are used by the FTP protocol handler.</P>
 107         <UL>
 108                 <LI><P><B>ftp.proxyHost</B>(default: &lt;none&gt;)<BR>
 109                 The hostname, or address, of the proxy server
 110                 </P>
 111                 <LI><P><B>ftp.proxyPort</B> (default: 80)<BR>
 112                 The port number of the proxy server.</P>
 113                 <LI><P><B>ftp.nonProxyHosts</B> (default: localhost|127.*|[::1])<BR>
 114                 Indicates the hosts that should be accessed without going
 115                 through the proxy. Typically this defines internal hosts.
 116                 The value of this property is a list of hosts, separated by
 117                 the '|' character. In addition the wildcard character
 118                 '*' can be used for pattern matching. For example
 119                 <code>-Dhttp.nonProxyHosts=&rdquo;*.foo.com|localhost&rdquo;</code>
 120                 will indicate that every hosts in the foo.com domain and the
 121                 localhost should be accessed directly even if a proxy server is
 122                 specified.</P>
 123                 <P>The default value excludes all common variations of the loopback address.</P>
 124         </UL>
 125         <LI><P>SOCKS<BR>This is another type of proxy. It allows for lower
 126         level type of tunneling since it works at the TCP level. In effect,
 127         in the Java(tm) platform setting a SOCKS proxy server will result in
 128         all TCP connections to go through that proxy, unless other proxies
 129         are specified. If SOCKS is supported by a Java SE implementation, the
 130         following properties will be used:</P>
 131         <UL>
 132                 <LI><P><B>socksProxyHost</B> (default: &lt;none&gt;)<BR>
 133                 The hostname, or address, of the proxy server.</P>
 134                 <LI><P><B>socksProxyPort</B> (default: 1080)<BR>
 135                 The port number of the proxy server.</P>
 136                 <LI><P><B>socksProxyVersion</B> (default: 5)<BR>
 137                 The version of the SOCKS protocol supported by the server. The
 138                 default is <code>5</code> indicating SOCKS V5, alternatively
 139                 <code>4</code> can be specified for SOCKS V4. Setting the property
 140                 to values other than these leads to unspecified behavior.</P>
 141                 <LI><P><B>java.net.socks.username</B> (default: &lt;none&gt;)<BR>
 142                 Username to use if the SOCKSv5 server asks for authentication
 143                 and no java.net.Authenticator instance was found.</P>
 144                 <LI><P><B>java.net.socks.password</B> (default: &lt;none&gt;)<BR>
 145                 Password to use if the SOCKSv5 server asks for authentication
 146                 and no java.net.Authenticator instance was found.</P>
 147                 <P>Note that if no authentication is provided with either the above
 148                 properties or an Authenticator, and the proxy requires one, then
 149                 the <B>user.name</B> property will be used with no password.</P>
 150         </UL>
 151         <LI><P><B>java.net.useSystemProxies</B> (default: false)<BR>
 152         On Windows systems, macOS systems and on Gnome systems it is possible to
 153         tell the java.net stack, setting this property to <B>true</B>, to use
 154         the system proxy settings (both these systems let you set proxies
 155         globally through their user interface). Note that this property is
 156         checked only once at startup.</P>
 157 </UL>
 158 <a id="MiscHTTP"></a>
 159 <H2>Misc HTTP properties</H2>
 160 <UL>
 161         <LI><P><B>http.agent</B> (default: &ldquo;Java/&lt;version&gt;&rdquo;)<BR>
 162         Defines the string sent in the User-Agent request header in http
 163         requests. Note that the string &ldquo;Java/&lt;version&gt;&rdquo; will
 164         be appended to the one provided in the property (e.g. if
 165         -Dhttp.agent=&rdquo;foobar&rdquo; is used, the User-Agent header will
 166         contain &ldquo;foobar Java/1.5.0&rdquo; if the version of the VM is
 167         1.5.0). This property is checked only once at startup.</P>
 168         <LI><P><B>http.keepalive</B> (default: true)<BR>
 169         Indicates if persistent connections should be supported. They improve
 170         performance by allowing the underlying socket connection to be reused
 171         for multiple http requests. If this is set to true then persistent
 172         connections will be requested with HTTP 1.1 servers.</P>
 173         <LI><P><B>http.maxConnections</B> (default: 5)<BR>
 174         If HTTP keepalive is enabled (see above) this value determines the
 175         maximum number of idle connections that will be simultaneously kept
 176         alive, per destination.</P>
 177         <LI><P><B>http.maxRedirects</B> (default: 20)<BR>
 178         This integer value determines the maximum number, for a given request,
 179         of HTTP redirects that will be automatically followed by the
 180         protocol handler.</P>
 181         <LI><P><B>http.auth.digest.validateServer</B> (default: false)</P>
 182         <LI><P><B>http.auth.digest.validateProxy</B> (default: false)</P>
 183         <LI><P><B>http.auth.digest.cnonceRepeat</B> (default: 5)</P>
 184         <P>These 3 properties modify the behavior of the HTTP digest
 185         authentication mechanism. Digest authentication provides a limited
 186         ability for the server  to authenticate itself to the client (i.e.
 187         By proving it knows the user's password). However not all HTTP
 188         servers support this capability and by default it is turned off. The
 189         first two properties can be set to true to enforce this check for
 190         authentication with either an origin or proxy server, respectively.</P>
 191         <P>It is usually not necessary to change the third property. It
 192         determines how many times a cnonce value is re-used. This can be
 193         useful when the MD5-sess algorithm is being used. Increasing this
 194         value reduces the computational overhead on both client and server
 195         by reducing the amount of material that has to be hashed for each
 196         HTTP request.</P>
 197         <LI><P><B>http.auth.ntlm.domain</B> (default: &lt;none&gt;)<BR>
 198         NTLM is another authentication scheme. It uses the
 199         java.net.Authenticator class to acquire usernames and passwords when
 200         they are needed. However NTLM also needs the NT domain name. There are
 201         3 options for specifying that domain:</P>
 202         <OL>
 203           <LI><P>Do not specify it. In some environments the domain is
 204               actually not required and the application does not have to specify
 205               it.</P>
 206           <LI><P>The domain name can be encoded within the username by
 207               prefixing the domain name, followed by a back-slash '\' before the
 208               username. With this method existing applications that use the
 209               authenticator class do not need to be modified, as long as users
 210               are made aware that this notation must be used.</P>
 211           <LI><P>If a domain name is not specified as in method 2) and these
 212               property is defined, then its value will be used a the domain
 213               name.</P>
 214         </OL>
 215 </UL>
 216 <P>All these properties are checked only once at startup.</P>
 217 <a id="AddressCache"></a>
 218 <H2>Address Cache</H2>
 219 <P>The java.net package, when doing name resolution, uses an address
 220 cache for both security and performance reasons. Any address
 221 resolution attempt, be it forward (name to IP address) or reverse (IP
 222 address to name), will have its result cached, whether it was
 223 successful or not, so that subsequent identical requests will not
 224 have to access the naming service. These properties allow for some
 225 tuning on how the cache is operating.</P>
 226 <UL>
 227         <LI><P><B>networkaddress.cache.ttl</B> (default: see below)<BR>
 228         Value is an integer corresponding to the number of seconds successful
 229         name lookups will be kept in the cache. A value of -1, or any  other
 230         negative value for that matter, indicates a &ldquo;cache forever&rdquo;
 231         policy, while a value of 0 (zero) means no caching. The default value
 232         is -1 (forever) if a security manager is installed, and implementation
 233         specific when no security manager is installed.</P>
 234         <LI><P><B>networkaddress.cache.negative.ttl</B> (default: 10)<BR>
 235         Value is an integer corresponding to the number of seconds an
 236         unsuccessful name lookup will be kept in the cache. A value of -1,
 237         or any negative value, means &ldquo;cache forever&rdquo;, while a
 238         value of 0 (zero) means no caching.</P>
 239 </UL>
 240 <P>Since these 2 properties are part of the security policy, they are
 241 not set by either the -D option or the System.setProperty() API,
 242 instead they are set as security properties.</P>
 243 </BODY>
 244 </HTML>