Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / libcore / 319a3b994703aac84df7bcde272adfcb3cdbbbf0 / . / jdk / src / share / classes / java / net / doc-files / net-properties.html
blob: e6b6330ba42aa3e00ae63ca478b1ca523fc809e6 [file] [log] [blame]
J. Duke319a3b92007-12-01 00:00:00 +0000[diff] [blame^]1<!--
2 Copyright 1998-2007 Sun Microsystems, Inc. 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. Sun designates this
8 particular file as subject to the "Classpath" exception as provided
9 by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
22 CA 95054 USA or visit www.sun.com if you need additional information or
23 have any 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
34alter the mechanisms and behavior of the various classes of the
35java.net package. Some are checked only once at startup of the VM,
36and therefore are best set using the -D option of the java command,
37while others have a more dynamic nature and can also be changed using
38the <a href="../../lang/System.html#setProperty(java.lang.String, java.lang.String)">System.setProperty()</a> API. The purpose of this document is to list
39and detail all of these properties.</P>
40<P>If there is no special note, a property value is checked every time it is used.</P>
41<a name="Ipv4IPv6"></a>
42<H2>IPv4 / IPv6</H2>
43<UL>
44 <LI><P><B>java.net.preferIPv4Stack</B> (default: false)<BR>
45 If IPv6 is available on the operating system the
46 underlying native socket will be, by default, an IPv6 socket which
47 lets applications connect to, and accept connections from, both
48 IPv4 and IPv6 hosts. However, in the case an application would
49 rather use IPv4 only sockets, then this property can be set to <B>true</B>.
50 The implication is that it will not be possible for the application
51 to communicate with IPv6 only hosts.</P>
52 <LI><P><B>java.net.preferIPv6Addresses</B> (default: false)<BR>
53 When dealing with a host which has both IPv4
54 and IPv6 addresses, and if IPv6 is available on the operating
55 system, the default behavior is to prefer using IPv4 addresses over
56 IPv6 ones. This is to ensure backward compatibility, for example
57 applications that depend on the representation of an IPv4 address
58 (e.g. 192.168.1.1). This property can be set to <B>true</B> to
59 change that preference and use IPv6 addresses over IPv4 ones where
60 possible.</P>
61</UL>
62<P>Both of these properties are checked only once, at startup.</P>
63<a name="Proxies"></a>
64<H2>Proxies</H2>
65<P>A proxy server allows indirect connection to network services and
66is used mainly for security (to get through firewalls) and
67performance reasons (proxies often do provide caching mechanisms).
68The following properties allow for configuration of the various type
69of proxies.</P>
70<UL>
71 <LI><P>HTTP</P>
72 <P>The following proxy settings are used by the HTTP protocol handler.</P>
73 <UL>
74 <LI><P><B>http.proxyHost</FONT></B> (default: &lt;none&gt;)<BR>
75 The hostname, or address, of the proxy server
76 </P>
77 <LI><P><B>http.proxyPort</B> (default: 80)<BR>
78 The port number of the proxy server.</P>
79 <LI><P><B>http.nonProxyHosts</B> (default: &lt;none&gt;)<BR>
80 Indicates the hosts that should be accessed without going
81 through the proxy. Typically this defines internal hosts.
82 The value of this property is a list of hosts,
83 separated by the '|' character. In addition the wildcard
84 character '*' can be used for pattern matching. For example
85 <code>-Dhttp.nonProxyHosts=&rdquo;*.foo.com|localhost&rdquo;</code>
86 will indicate that every hosts in the foo.com domain and the
87 localhost should be accessed directly even if a proxy server is
88 specified.</P>
89 </UL>
90 <LI><P>HTTPS<BR>This is HTTP over SSL, a secure version of HTTP
91 mainly used when confidentiality (like on payment sites) is needed.</P>
92 <P>The following proxy settings are used by the HTTPS protocol handler.</P>
93 <UL>
94 <LI><P><B>https.proxyHost</B>(default: &lt;none&gt;)<BR>
95 The hostname, or address, of the proxy server
96 </P>
97 <LI><P><B>https.proxyPort</B> (default: 443)<BR>
98 The port number of the proxy server.</P>
99 <P>The HTTPS protocol handler will use the same nonProxyHosts
100 property as the HTTP protocol.</P>
101 </UL>
102 <LI><P>FTP</P>
103 <P>The following proxy settings are used by the FTP protocol handler.</P>
104 <UL>
105 <LI><P><B>ftp.proxyHost</B>(default: &lt;none&gt;)<BR>
106 The hostname, or address, of the proxy server
107 </P>
108 <LI><P><B>ftp.proxyPort</B> (default: 80)<BR>
109 The port number of the proxy server.</P>
110 <LI><P><B>ftp.nonProxyHosts</B> (default: &lt;none&gt;)<BR>
111 Indicates the hosts that should be accessed without going
112 through the proxy. Typically this defines internal hosts.
113 The value of this property is a list of hosts, separated by
114 the '|' character. In addition the wildcard character
115 '*' can be used for pattern matching. For example
116 <code>-Dhttp.nonProxyHosts=&rdquo;*.foo.com|localhost&rdquo;</code>
117 will indicate that every hosts in the foo.com domain and the
118 localhost should be accessed directly even if a proxy server is
119 specified.</P>
120 </UL>
121 <LI><P>SOCKS<BR>This is another type of proxy. It allows for lower
122 level type of tunneling since it works at the TCP level. In effect,
123 in the Java(tm) platform setting a SOCKS proxy server will result in
124 all TCP connections to go through that proxy, unless other proxies
125 are specified. If SOCKS is supported by a Java SE implementation, the
126 following properties will be used:</P>
127 <UL>
128 <LI><P><B>socksProxyHost</B> (default: &lt;non&gt;)<BR>
129 The hostname, or address, of the proxy server.</P>
130 <LI><P><B>socksProxyPort</B> (default: 1080)<BR>
131 The port number of the proxy server.</P>
132 <LI><P><B>java.net.socks.username</B> (default: &lt;none&gt;)<BR>
133 Username to use if the SOCKSv5 server asks for authentication
134 and no java.net.Authenticator instance was found.</P>
135 <LI><P><B>java.net.socks.password</B> (default: &lt;none&gt;)<BR>
136 Password to use if the SOCKSv5 server asks for authentication
137 and no java.net.Authenticator instance was found.</P>
138 <P>Note that if no authentication is provided with either the above
139 properties or an Authenticator, and the proxy requires one, then
140 the <B>user.name</B> property will be used with no password.</P>
141 </UL>
142 <LI><P><B>java.net.useSystemProxies</B> (default: false)<BR>
143 On recent Windows systems and on Gnome 2.x systems it is possible to
144 tell the java.net stack, setting this property to <B>true</B>, to use
145 the system proxy settings (both these systems let you set proxies
146 globally through their user interface). Note that this property is
147 checked only once at startup.</P>
148</UL>
149<a name="MiscHTTP"></a>
150<H2>Misc HTTP properties</H2>
151<UL>
152 <LI><P><B>http.agent</B> (default: &ldquo;Java/&lt;version&gt;&rdquo;)<BR>
153 Defines the string sent in the User-Agent request header in http
154 requests. Note that the string &ldquo;Java/&lt;version&gt;&rdquo; will
155 be appended to the one provided in the property (e.g. if
156 -Dhttp.agent=&rdquo;foobar&rdquo; is used, the User-Agent header will
157 contain &ldquo;foobar Java/1.5.0&rdquo; if the version of the VM is
158 1.5.0). This property is checked only once at startup.</P>
159 <LI><P><B>http.keepalive</B> (default: true)<BR>
160 Indicates if persistent connections should be supported. They improve
161 performance by allowing the underlying socket connection to be reused
162 for multiple http requests. If this is set to true then persistent
163 connections will be requested with HTTP 1.1 servers.</P>
164 <LI><P><B>http.maxConnections</B> (default: 5)<BR>
165 If HTTP keepalive is enabled (see above) this value determines the
166 maximum number of idle connections that will be simultaneously kept
167 alive, per destination.</P>
168 <LI><P><B>http.maxRedirects</B> (default: 20)<BR>
169 This integer value determines the maximum number, for a given request,
170 of HTTP redirects that will be automatically followed by the
171 protocol handler.</P>
172 <LI><P><B>http.auth.digest.validateServer</B> (default: false)</P>
173 <LI><P><B>http.auth.digest.validateProxy</B> (default: false)</P>
174 <LI><P><B>http.auth.digest.cnonceRepeat</B> (default: 5)</P>
175 <P>These 3 properties modify the behavior of the HTTP digest
176 authentication mechanism. Digest authentication provides a limited
177 ability for the server to authenticate itself to the client (i.e.
178 By proving it knows the user's password). However not all HTTP
179 servers support this capability and by default it is turned off. The
180 first two properties can be set to true to enforce this check for
181 authentication with either an origin or proxy server, respectively.</P>
182 <P>It is usually not necessary to change the third property. It
183 determines how many times a cnonce value is re-used. This can be
184 useful when the MD5-sess algorithm is being used. Increasing this
185 value reduces the computational overhead on both client and server
186 by reducing the amount of material that has to be hashed for each
187 HTTP request.</P>
188 <LI><P><B>http.auth.ntlm.domain</B> (default: &lt;none&gt;)<BR>
189 NTLM is another authentication scheme. It uses the
190 java.net.Authenticator class to acquire usernames and passwords when
191 they are needed. However NTLM also needs the NT domain name. There are
192 3 options for specifying that domain:</P>
193 <OL>
194 <LI><P>Do not specify it. In some environments the domain is
195 actually not required and the application does not have to specify
196 it.</P>
197 <LI><P>The domain name can be encoded within the username by
198 prefixing the domain name, followed by a back-slash '\' before the
199 username. With this method existing applications that use the
200 authenticator class do not need to be modified, as long as users
201 are made aware that this notation must be used.</P>
202 <LI><P>If a domain name is not specified as in method 2) and these
203 property is defined, then its value will be used a the domain
204 name.</P>
205 </OL>
206</UL>
207<P>All these properties are checked only once at startup.</P>
208<a name="AddressCache"></a>
209<H2>Address Cache</H2>
210<P>The java.net package, when doing name resolution, uses an address
211cache for both security and performance reasons. Any address
212resolution attempt, be it forward (name to IP address) or reverse (IP
213address to name), will have its result cached, whether it was
214successful or not, so that subsequent identical requests will not
215have to access the naming service. These properties allow for some
216tuning on how the cache is operating.</P>
217<UL>
218 <LI><P><B>networkaddress.cache.ttl</B> (default: see below)<BR>
219 Value is an integer corresponding to the number of seconds successful
220 name lookups will be kept in the cache. A value of -1, or any other
221 negative value for that matter, indicates a &ldquo;cache forever&rdquo;
222 policy, while a value of 0 (zero) means no caching. The default value
223 is -1 (forever) if a security manager is installed, and implementation
224 specific when no security manager is installed.</P>
225 <LI><P><B>networkaddress.cache.negative.ttl</B> (default: 10)<BR>
226 Value is an integer corresponding to the number of seconds an
227 unsuccessful name lookup will be kept in the cache. A value of -1,
228 or any negative value, means &ldquo;cache forever&rdquo;, while a
229 value of 0 (zero) means no caching.</P>
230</UL>
231<P>Since these 2 properties are part of the security policy, they are
232not set by either the -D option or the System.setProperty() API,
233instead they are set in the JRE security policy file <code>lib/security/java.security</code>.</P>
234</BODY>
235</HTML>