|
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: <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 id="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 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 “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> |