| author | chegar |
| Fri, 15 Mar 2019 14:50:57 +0000 | |
| changeset 54146 | 81605c74b980 |
| parent 52708 | 1ffff60c9f54 |
| child 58031 | 5aaf53d4fe63 |
| permissions | -rw-r--r-- |
| 45433 | 1 |
<!DOCTYPE HTML> |
| 2 | 2 |
<!-- |
| 54146 | 3 |
Copyright (c) 1998, 2019, Oracle and/or its affiliates. All rights reserved. |
| 2 | 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 |
|
| 5506 | 8 |
published by the Free Software Foundation. Oracle designates this |
| 2 | 9 |
particular file as subject to the "Classpath" exception as provided |
| 5506 | 10 |
by Oracle in the LICENSE file that accompanied this code. |
| 2 | 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 |
||
| 5506 | 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. |
|
| 2 | 25 |
--> |
|
46152
51d10b05c78e
8186156: Fix a11y and HTML issues in java.net and javax.net packages
jjg
parents:
45433
diff
changeset
|
26 |
<HTML lang="EN"> |
| 2 | 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"> |
|
| 45433 | 32 |
<H1 style="text-align:center">Networking Properties</H1> |
33 |
<P>There are a few standard system properties used to |
|
| 2 | 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 |
|
| 49522 | 38 |
the <a href="../../lang/System.html#setProperty(java.lang.String,java.lang.String)">System.setProperty()</a> API. |
|
23720
7d5147c21927
8039172: Tidy warnings cleanup for java.net, java.math, java.time, java.rmi
yan
parents:
14775
diff
changeset
|
39 |
The purpose of this document is to list |
| 2 | 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> |
|
| 45433 | 42 |
<a id="Ipv4IPv6"></a> |
| 2 | 43 |
<H2>IPv4 / IPv6</H2> |
44 |
<UL> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
45 |
<LI><P><B>{@systemProperty java.net.preferIPv4Stack}</B> (default: false)<BR>
|
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
53 |
<LI><P><B>{@systemProperty java.net.preferIPv6Addresses}</B> (default: false)<BR>
|
| 2 | 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 |
|
|
38552
ca398af91529
8016521: InetAddress should not always re-order addresses returned from name service
vtewari
parents:
25859
diff
changeset
|
61 |
possible, or <B>system</B> to preserve the order of the addresses as |
|
ca398af91529
8016521: InetAddress should not always re-order addresses returned from name service
vtewari
parents:
25859
diff
changeset
|
62 |
returned by the operating system.</P> |
| 2 | 63 |
</UL> |
64 |
<P>Both of these properties are checked only once, at startup.</P> |
|
| 45433 | 65 |
<a id="Proxies"></a> |
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
76 |
<LI><P><B>{@systemProperty http.proxyHost}</B> (default: <none>)<BR>
|
|
38552
ca398af91529
8016521: InetAddress should not always re-order addresses returned from name service
vtewari
parents:
25859
diff
changeset
|
77 |
The hostname, or address, of the proxy server |
| 2 | 78 |
</P> |
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
79 |
<LI><P><B>{@systemProperty http.proxyPort}</B> (default: 80)<BR>
|
| 2 | 80 |
The port number of the proxy server.</P> |
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
81 |
<LI><P><B>{@systemProperty http.nonProxyHosts}</B> (default: localhost|127.*|[::1])<BR>
|
| 2 | 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> |
|
|
3855
653df3a7256d
6737819: sun.misc.net.DefaultProxySelector doesn't use proxy setting to localhost
jccollet
parents:
2
diff
changeset
|
91 |
<P>The default value excludes all common variations of the loopback address.</P> |
|
653df3a7256d
6737819: sun.misc.net.DefaultProxySelector doesn't use proxy setting to localhost
jccollet
parents:
2
diff
changeset
|
92 |
</UL> |
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
97 |
<LI><P><B>{@systemProperty https.proxyHost}</B>(default: <none>)<BR>
|
|
38552
ca398af91529
8016521: InetAddress should not always re-order addresses returned from name service
vtewari
parents:
25859
diff
changeset
|
98 |
The hostname, or address, of the proxy server |
| 2 | 99 |
</P> |
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
100 |
<LI><P><B>{@systemProperty https.proxyPort}</B> (default: 443)<BR>
|
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
108 |
<LI><P><B>{@systemProperty ftp.proxyHost}</B>(default: <none>)<BR>
|
|
38552
ca398af91529
8016521: InetAddress should not always re-order addresses returned from name service
vtewari
parents:
25859
diff
changeset
|
109 |
The hostname, or address, of the proxy server |
| 2 | 110 |
</P> |
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
111 |
<LI><P><B>{@systemProperty ftp.proxyPort}</B> (default: 80)<BR>
|
| 2 | 112 |
The port number of the proxy server.</P> |
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
113 |
<LI><P><B>{@systemProperty ftp.nonProxyHosts}</B> (default: localhost|127.*|[::1])<BR>
|
| 2 | 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> |
|
|
3855
653df3a7256d
6737819: sun.misc.net.DefaultProxySelector doesn't use proxy setting to localhost
jccollet
parents:
2
diff
changeset
|
123 |
<P>The default value excludes all common variations of the loopback address.</P> |
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
132 |
<LI><P><B>{@systemProperty socksProxyHost}</B> (default: <none>)<BR>
|
| 2 | 133 |
The hostname, or address, of the proxy server.</P> |
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
134 |
<LI><P><B>{@systemProperty socksProxyPort}</B> (default: 1080)<BR>
|
| 2 | 135 |
The port number of the proxy server.</P> |
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
136 |
<LI><P><B>{@systemProperty socksProxyVersion}</B> (default: 5)<BR>
|
|
7982
65f5328a67a2
6964547: Impossible to set useV4 in SocksSocketImpl
chegar
parents:
5506
diff
changeset
|
137 |
The version of the SOCKS protocol supported by the server. The |
|
65f5328a67a2
6964547: Impossible to set useV4 in SocksSocketImpl
chegar
parents:
5506
diff
changeset
|
138 |
default is <code>5</code> indicating SOCKS V5, alternatively |
|
65f5328a67a2
6964547: Impossible to set useV4 in SocksSocketImpl
chegar
parents:
5506
diff
changeset
|
139 |
<code>4</code> can be specified for SOCKS V4. Setting the property |
|
65f5328a67a2
6964547: Impossible to set useV4 in SocksSocketImpl
chegar
parents:
5506
diff
changeset
|
140 |
to values other than these leads to unspecified behavior.</P> |
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
141 |
<LI><P><B>{@systemProperty java.net.socks.username}</B> (default: <none>)<BR>
|
| 2 | 142 |
Username to use if the SOCKSv5 server asks for authentication |
143 |
and no java.net.Authenticator instance was found.</P> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
144 |
<LI><P><B>{@systemProperty java.net.socks.password}</B> (default: <none>)<BR>
|
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
151 |
<LI><P><B>{@systemProperty java.net.useSystemProxies}</B> (default: false)<BR>
|
|
43501
243c346dc905
8170868: DefaultProxySelector should use system defaults on Windows, MacOS and Gnome
clanger
parents:
38552
diff
changeset
|
152 |
On Windows systems, macOS systems and on Gnome systems it is possible to |
| 2 | 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> |
|
| 45433 | 158 |
<a id="MiscHTTP"></a> |
| 49765 | 159 |
<H2>Misc HTTP URL stream protocol handler properties</H2> |
| 2 | 160 |
<UL> |
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
161 |
<LI><P><B>{@systemProperty http.agent}</B> (default: “Java/<version>”)<BR>
|
| 2 | 162 |
Defines the string sent in the User-Agent request header in http |
163 |
requests. Note that the string “Java/<version>” will |
|
|
38552
ca398af91529
8016521: InetAddress should not always re-order addresses returned from name service
vtewari
parents:
25859
diff
changeset
|
164 |
be appended to the one provided in the property (e.g. if |
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
168 |
<LI><P><B>{@systemProperty http.keepalive}</B> (default: true)<BR>
|
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
173 |
<LI><P><B>{@systemProperty http.maxConnections}</B> (default: 5)<BR>
|
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
177 |
<LI><P><B>{@systemProperty http.maxRedirects}</B> (default: 20)<BR>
|
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
181 |
<LI><P><B>{@systemProperty http.auth.digest.validateServer}</B> (default: false)</P>
|
|
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
182 |
<LI><P><B>{@systemProperty http.auth.digest.validateProxy}</B> (default: false)</P>
|
|
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
183 |
<LI><P><B>{@systemProperty http.auth.digest.cnonceRepeat}</B> (default: 5)</P>
|
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
197 |
<LI><P><B>{@systemProperty http.auth.ntlm.domain}</B> (default: <none>)<BR>
|
| 2 | 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> |
|
| 54146 | 211 |
<LI><P>If a domain name is not specified as in method 2) and this |
| 2 | 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> |
|
| 45433 | 217 |
<a id="AddressCache"></a> |
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
227 |
<LI><P><B>{@systemProperty networkaddress.cache.ttl}</B> (default: see below)<BR>
|
| 2 | 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> |
|
|
52708
1ffff60c9f54
8213921: Use {@systemProperty} tag for properties listed in "Networking Properties"
pmuthuswamy
parents:
49765
diff
changeset
|
234 |
<LI><P><B>{@systemProperty networkaddress.cache.negative.ttl}</B> (default: 10)<BR>
|
| 2 | 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, |
|
|
14775
2ed01c760aea
8004064: Downgrade normative references to ${java.home}/lib/security/java.security
mullan
parents:
9035
diff
changeset
|
242 |
instead they are set as security properties.</P> |
| 2 | 243 |
</BODY> |
244 |
</HTML> |