src/java.base/share/classes/java/net/doc-files/net-properties.html
changeset 47216 71c04702a3d5
parent 46152 51d10b05c78e
child 49522 3930c4d4f805
child 56316 c65662728983
equal deleted inserted replaced
47215:4ebc2e2fb97c 47216:71c04702a3d5
       
     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 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>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-java.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>