1 <!DOCTYPE HTML> 2 <!-- 3 Copyright (c) 1998, 2020, 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 lang="EN"> 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> 34 There are a few standard system properties used to 35 alter the mechanisms and behavior of the various classes of the 36 java.net package. Some are checked only once at startup of the VM, 37 and therefore are best set using the -D option of the java command, 38 while others have a more dynamic nature and can also be changed using 39 the <a href="../../lang/System.html#setProperty(java.lang.String,java.lang.String)">System.setProperty()</a> API. 40 The purpose of this document is to list 41 and detail all of these properties.</P> 42 <p> 43 If there is no special note, a property value is checked every time it is used.</P> 44 <a id="Ipv4IPv6"></a> 45 <H2>IPv4 / IPv6</H2> 46 <UL> 47 <LI><P><B>{@systemProperty java.net.preferIPv4Stack}</B> (default: false)<BR> 48 If IPv6 is available on the operating system the 49 underlying native socket will be, by default, an IPv6 socket which 50 lets applications connect to, and accept connections from, both 51 IPv4 and IPv6 hosts. However, in the case an application would 52 rather use IPv4 only sockets, then this property can be set to <B>true</B>. 53 The implication is that it will not be possible for the application 54 to communicate with IPv6 only hosts.</P> 55 <LI><P><B>{@systemProperty java.net.preferIPv6Addresses}</B> (default: false)<BR> 56 When dealing with a host which has both IPv4 57 and IPv6 addresses, and if IPv6 is available on the operating 58 system, the default behavior is to prefer using IPv4 addresses over 59 IPv6 ones. This is to ensure backward compatibility: for example, 60 for applications that depend on the representation of an IPv4 address 61 (e.g. 192.168.1.1). This property can be set to <B>true</B> to 62 change that preference and use IPv6 addresses over IPv4 ones where 63 possible, or <B>system</B> to preserve the order of the addresses as 64 returned by the operating system.</P> 65 </UL> 66 <P>Both of these properties are checked only once, at startup.</P> 67 <a id="Proxies"></a> 68 <H2>Proxies</H2> 69 <P>A proxy server allows indirect connection to network services and 70 is used mainly for security (to get through firewalls) and 71 performance reasons (proxies often do provide caching mechanisms). 72 The following properties allow for configuration of the various type 73 of proxies.</P> 74 <UL> 75 <LI><P>HTTP</P> 76 <P>The following proxy settings are used by the HTTP protocol handler.</P> 77 <UL> 78 <LI><P><B>{@systemProperty http.proxyHost}</B> (default: <none>)<BR> 79 The hostname, or address, of the proxy server. 80 </P> 81 <LI><P><B>{@systemProperty http.proxyPort}</B> (default: {@code 80})<BR> 82 The port number of the proxy server.</P> 83 <LI><P><B>{@systemProperty http.nonProxyHosts}</B> (default: {@code localhost|127.*|[::1]})<BR> 84 Indicates the hosts that should be accessed without going 85 through the proxy. Typically this defines internal hosts. 86 The value of this property is a list of hosts, 87 separated by the '|' character. In addition, the wildcard 88 character '*' can be used for pattern matching. For example, 89 {@code -Dhttp.nonProxyHosts="*.foo.com|localhost"} 90 will indicate that every host in the foo.com domain and the 91 localhost should be accessed directly even if a proxy server is 92 specified.</P> 93 <P>The default value excludes all common variations of the loopback address.</P> 94 </UL> 95 <LI><P>HTTPS<BR>This is HTTP over SSL, a secure version of HTTP 96 mainly used when confidentiality (like on payment sites) is needed.</P> 97 <P>The following proxy settings are used by the HTTPS protocol handler.</P> 98 <UL> 99 <LI><P><B>{@systemProperty https.proxyHost}</B> (default: <none>)<BR> 100 The hostname, or address, of the proxy server. 101 </P> 102 <LI><P><B>{@systemProperty https.proxyPort}</B> (default: {@code 443})<BR> 103 The port number of the proxy server.</P> 104 <P>The HTTPS protocol handler will use the same nonProxyHosts 105 property as the HTTP protocol.</P> 106 </UL> 107 <LI><P>FTP</P> 108 <P>The following proxy settings are used by the FTP protocol handler.</P> 109 <UL> 110 <LI><P><B>{@systemProperty ftp.proxyHost}</B> (default: <none>)<BR> 111 The hostname, or address, of the proxy server. 112 </P> 113 <LI><P><B>{@systemProperty ftp.proxyPort}</B> (default: {@code 80})<BR> 114 The port number of the proxy server.</P> 115 <LI><P><B>{@systemProperty ftp.nonProxyHosts}</B> (default: {@code localhost|127.*|[::1]})<BR> 116 Indicates the hosts that should be accessed without going 117 through the proxy. Typically this defines internal hosts. 118 The value of this property is a list of hosts, separated by 119 the '|' character. In addition, the wildcard character 120 '*' can be used for pattern matching. For example, 121 {@code -Dhttp.nonProxyHosts="*.foo.com|localhost"} 122 will indicate that every host in the foo.com domain and the 123 localhost should be accessed directly even if a proxy server is 124 specified.</P> 125 <P>The default value excludes all common variations of the loopback address.</P> 126 </UL> 127 <LI><P>SOCKS<BR>This is another type of proxy. It allows for lower-level 128 type of tunneling since it works at the TCP level. In effect, 129 in the Java(tm) platform setting a SOCKS proxy server will result in 130 all TCP connections to go through that proxy, unless other proxies 131 are specified. If SOCKS is supported by a Java SE implementation, the 132 following properties will be used:</P> 133 <UL> 134 <LI><P><B>{@systemProperty socksProxyHost}</B> (default: <none>)<BR> 135 The hostname, or address, of the proxy server.</P> 136 <LI><P><B>{@systemProperty socksProxyPort}</B> (default: {@code 1080})<BR> 137 The port number of the proxy server.</P> 138 <LI><P><B>{@systemProperty socksProxyVersion}</B> (default: {@code 5})<BR> 139 The version of the SOCKS protocol supported by the server. The 140 default is {@code 5} indicating SOCKS V5. Alternatively, 141 {@code 4} can be specified for SOCKS V4. Setting the property 142 to values other than these leads to unspecified behavior.</P> 143 <LI><P><B>{@systemProperty java.net.socks.username}</B> (default: <none>)<BR> 144 Username to use if the SOCKSv5 server asks for authentication 145 and no {@link java.net.Authenticator java.net.Authenticator} instance was found.</P> 146 <LI><P><B>{@systemProperty java.net.socks.password}</B> (default: <none>)<BR> 147 Password to use if the SOCKSv5 server asks for authentication 148 and no {@code java.net.Authenticator} instance was found.</P> 149 <P>Note that if no authentication is provided with either the above 150 properties or an Authenticator, and the proxy requires one, then 151 the <B>user.name</B> property will be used with no password.</P> 152 </UL> 153 <LI><P><B>{@systemProperty java.net.useSystemProxies}</B> (default: {@code false})<BR> 154 On Windows systems, macOS systems, and Gnome systems it is possible to 155 tell the java.net stack, setting this property to <B>true</B>, to use 156 the system proxy settings (all these systems let you set proxies 157 globally through their user interface). Note that this property is 158 checked only once at startup.</P> 159 </UL> 160 <a id="MiscHTTP"></a> 161 <H2>Misc HTTP URL stream protocol handler properties</H2> 162 <UL> 163 <LI><P><B>{@systemProperty http.agent}</B> (default: “Java/<version>”)<BR> 164 Defines the string sent in the User-Agent request header in http 165 requests. Note that the string “Java/<version>” will 166 be appended to the one provided in the property (e.g. if 167 {@code -Dhttp.agent="foobar"} is used, the User-Agent header will 168 contain “foobar Java/1.5.0” if the version of the VM is 169 1.5.0). This property is checked only once at startup.</P> 170 <LI><P><B>{@systemProperty http.keepAlive}</B> (default: {@code true})<BR> 171 Indicates if persistent connections should be supported. They improve 172 performance by allowing the underlying socket connection to be reused 173 for multiple HTTP requests. If this is set to true then persistent 174 connections will be requested with HTTP 1.1 servers.</P> 175 <LI><P><B>{@systemProperty http.maxConnections}</B> (default: {@code 5})<BR> 176 If HTTP keepalive is enabled (see above) this value determines the 177 maximum number of idle connections that will be simultaneously kept 178 alive, per destination.</P> 179 <LI><P><B>{@systemProperty http.maxRedirects}</B> (default: {@code 20})<BR> 180 This integer value determines the maximum number, for a given request, 181 of HTTP redirects that will be automatically followed by the 182 protocol handler.</P> 183 <LI><P><B>{@systemProperty http.auth.digest.validateServer}</B> (default: {@code false})</P> 184 <LI><P><B>{@systemProperty http.auth.digest.validateProxy}</B> (default: {@code false})</P> 185 <LI><P><B>{@systemProperty http.auth.digest.cnonceRepeat}</B> (default: {@code 5})</P> 186 <P>These 3 properties modify the behavior of the HTTP digest 187 authentication mechanism. Digest authentication provides a limited 188 ability for the server to authenticate itself to the client (i.e. 189 By proving it knows the user's password). However, not all HTTP 190 servers support this capability and by default it is turned off. The 191 first two properties can be set to true to enforce this check for 192 authentication with either an origin or proxy server, respectively.</P> 193 <P>It is usually not necessary to change the third property. It 194 determines how many times a cnonce value is re-used. This can be 195 useful when the MD5-sess algorithm is being used. Increasing this 196 value reduces the computational overhead on both client and server 197 by reducing the amount of material that has to be hashed for each 198 HTTP request.</P> 199 <LI><P><B>{@systemProperty http.auth.ntlm.domain}</B> (default: <none>)<BR> 200 NTLM is another authentication scheme. It uses the 201 {@code java.net.Authenticator} class to acquire usernames and passwords when 202 they are needed. However, NTLM also needs the NT domain name. There are 203 3 options for specifying that domain:</P> 204 <OL> 205 <LI><P>Do not specify it. In some environments the domain is 206 actually not required and the application does not have to specify 207 it.</P> 208 <LI><P>The domain name can be encoded within the username by 209 prefixing the domain name, followed by a backslash '\' before the 210 username. With this method existing applications that use the 211 authenticator class do not need to be modified, as long as users 212 are made aware that this notation must be used.</P> 213 <LI><P>If a domain name is not specified as in method 2) and this 214 property is defined, then its value will be used as the domain 215 name.</P> 216 </OL> 217 </UL> 218 <P>All these properties are checked only once at startup.</P> 219 <a id="AddressCache"></a> 220 <H2>Address Cache</H2> 221 <P>The java.net package, when doing name resolution, uses an address 222 cache for both security and performance reasons. Any address 223 resolution attempt, be it forward (name to IP address) or reverse (IP 224 address to name), will have its result cached, whether it was 225 successful or not, so that subsequent identical requests will not 226 have to access the naming service. These properties allow for some 227 tuning on how the cache is operating.</P> 228 <UL> 229 <LI><P><B>{@systemProperty networkaddress.cache.ttl}</B> (default: see below)<BR> 230 Value is an integer corresponding to the number of seconds successful 231 name lookups will be kept in the cache. A value of -1, or any other 232 negative value for that matter, indicates a “cache forever” 233 policy, while a value of 0 (zero) means no caching. The default value 234 is -1 (forever) if a security manager is installed, and implementation-specific 235 when no security manager is installed.</P> 236 <LI><P><B>{@systemProperty networkaddress.cache.negative.ttl}</B> (default: {@code 10})<BR> 237 Value is an integer corresponding to the number of seconds an 238 unsuccessful name lookup will be kept in the cache. A value of -1, 239 or any negative value, means “cache forever”, while a 240 value of 0 (zero) means no caching.</P> 241 </UL> 242 <P>Since these 2 properties are part of the security policy, they are 243 not set by either the -D option or the {@code System.setProperty()} API, 244 instead they are set as security properties.</P> 245 <a id="Unixdomain"></a> 246 <H2>Unix domain sockets</H2> 247 <p> 248 Calling {@link java.nio.channels.ServerSocketChannel#bind(SocketAddress,int) ServerSocketChannel.bind} 249 with a {@code null} address parameter will bind to an <i>automatically assigned</i> socket address. 250 For Unix domain sockets, this means a unique path in some predefined system temporary directory. 251 There are a number of system (and networking) properties that affect this behavior. 252 <p> 253 Unix domain socket addresses are limited in length to approximately 100 254 bytes (depending on the platform), it is important to ensure that the temporary directory's name 255 together with the filename used for the socket (currently a name similar to 256 {@code socket_1679697142}) does not exceed this limit. The following properties 257 can be used to control the selection of this directory: 258 <ul> 259 <li><p><b>{@systemProperty jdk.net.unixdomain.tmpdir}</b> This can be set as 260 a networking property in {@code conf/net.properties} If set, this specifies the 261 directory to use for automatically bound server socket addresses. On some platforms, 262 (eg some Unix systems) this will have a predefined default value. On others, 263 (eg Windows) there is no default value. Either way, it is always possible 264 to override the networking property with a system property of the same name 265 set on the command line. If neither of the networking nor system property 266 are set, then some systems (eg Windows) may check a commonly used environment 267 variable as temporary directory. 268 <li><p><b>{@systemProperty java.io.tmpdir}</b> If the previous step fails to locate 269 a directory to use, then the directory identified by the system property 270 {@code java.io.tmpdir} is used. 271 </ul> 272 More information about the platform specific behavior can be seen in the 273 {@code conf/net.properties} configuration file. 274 <p> 275 <i>Implicit</i> binding of a {@link java.nio.channels.SocketChannel SocketChannel} 276 <p> 277 If a client socket is connected to a remote destination without calling {@code bind} first, 278 then the socket is <i>implicitly</i> bound. In this case, <i>Unix domain</i> sockets 279 are <i>unnamed</i> (ie. their path is empty). This behavior is not affected by any 280 system or networking properties. 281 <p> 282 <a id="EnhancedExceptions"></a> 283 <H2>Enhanced exception messages</H2> 284 By default, for security reasons, exception messages do not include potentially sensitive 285 security information such as hostnames or Unix domain socket address paths. 286 The following property can be used to relax this restriction, for debugging and other 287 purposes. 288 <ul> 289 <li><p><b>{@systemProperty jdk.includeInExceptions}</b> This is typically set to 290 a comma separated list of keywords that refer to exception types whose messages 291 may be enhanced with more detailed information. If the value includes the string 292 {@code hostInfo} then socket addresses will be included in exception message 293 texts (eg hostnames, Unix domain socket address paths). 294 </ul> 295 296 </BODY> 297 </HTML> --- EOF ---