1 <!-- 2 Copyright (c) 1998, 2016, Oracle and/or its affiliates. All rights reserved. 3 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 5 This code is free software; you can redistribute it and/or modify it 6 under the terms of the GNU General Public License version 2 only, as 7 published by the Free Software Foundation. Oracle designates this 8 particular file as subject to the "Classpath" exception as provided 9 by Oracle in the LICENSE file that accompanied this code. 10 11 This code is distributed in the hope that it will be useful, but WITHOUT 12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 version 2 for more details (a copy is included in the LICENSE file that 15 accompanied this code). 16 17 You should have received a copy of the GNU General Public License version 18 2 along with this work; if not, write to the Free Software Foundation, 19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 or visit www.oracle.com if you need additional information or have any 23 questions. 24 --> 25 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 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 ALIGN=CENTER>Networking Properties</H1> 33 <P ALIGN=LEFT>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 name="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 name="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: <none>)<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=”*.foo.com|localhost”</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: <none>)<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: <none>)<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=”*.foo.com|localhost”</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: <none>)<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: <none>)<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: <none>)<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 name="MiscHTTP"></a> 159 <H2>Misc HTTP properties</H2> 160 <UL> 161 <LI><P><B>http.agent</B> (default: “Java/<version>”)<BR> 162 Defines the string sent in the User-Agent request header in http 163 requests. Note that the string “Java/<version>” will 164 be appended to the one provided in the property (e.g. if 165 -Dhttp.agent=”foobar” is used, the User-Agent header will 166 contain “foobar Java/1.5.0” 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: <none>)<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 name="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 “cache forever” 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 “cache forever”, 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>