236 lines
12 KiB
HTML
236 lines
12 KiB
HTML
|
<!--
|
||
|
|
Copyright 1998-2007 Sun Microsystems, Inc. All Rights Reserved.
|
||
|
|
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
||
|
|
|
||
|
|
This code is free software; you can redistribute it and/or modify it
|
||
|
|
under the terms of the GNU General Public License version 2 only, as
|
||
|
|
published by the Free Software Foundation. Sun designates this
|
||
|
|
particular file as subject to the "Classpath" exception as provided
|
||
|
|
by Sun in the LICENSE file that accompanied this code.
|
||
|
|
|
||
|
|
This code is distributed in the hope that it will be useful, but WITHOUT
|
||
|
|
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
||
|
|
FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
||
|
|
version 2 for more details (a copy is included in the LICENSE file that
|
||
|
|
accompanied this code).
|
||
|
|
|
||
|
|
You should have received a copy of the GNU General Public License version
|
||
|
|
2 along with this work; if not, write to the Free Software Foundation,
|
||
|
|
Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
||
|
|
|
||
|
|
Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
|
||
|
|
CA 95054 USA or visit www.sun.com if you need additional information or
|
||
|
|
have any questions.
|
||
|
|
-->
|
||
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
|
||
|
|
<HTML>
|
||
|
|
<HEAD>
|
||
|
|
<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=iso-8859-1">
|
||
|
|
<TITLE>Networking Properties</TITLE>
|
||
|
|
</HEAD>
|
||
|
|
<BODY LANG="en-US" DIR="LTR">
|
||
|
|
<H1 ALIGN=CENTER>Networking Properties</H1>
|
||
|
|
<P ALIGN=LEFT>There are a few standard system properties used to
|
||
|
|
alter the mechanisms and behavior of the various classes of the
|
||
|
|
java.net package. Some are checked only once at startup of the VM,
|
||
|
|
and therefore are best set using the -D option of the java command,
|
||
|
|
while others have a more dynamic nature and can also be changed using
|
||
|
|
the <a href="../../lang/System.html#setProperty(java.lang.String, java.lang.String)">System.setProperty()</a> API. The purpose of this document is to list
|
||
|
|
and detail all of these properties.</P>
|
||
|
|
<P>If there is no special note, a property value is checked every time it is used.</P>
|
||
|
|
<a name="Ipv4IPv6"></a>
|
||
|
|
<H2>IPv4 / IPv6</H2>
|
||
|
|
<UL>
|
||
|
|
<LI><P><B>java.net.preferIPv4Stack</B> (default: false)<BR>
|
||
|
|
If IPv6 is available on the operating system the
|
||
|
|
underlying native socket will be, by default, an IPv6 socket which
|
||
|
|
lets applications connect to, and accept connections from, both
|
||
|
|
IPv4 and IPv6 hosts. However, in the case an application would
|
||
|
|
rather use IPv4 only sockets, then this property can be set to <B>true</B>.
|
||
|
|
The implication is that it will not be possible for the application
|
||
|
|
to communicate with IPv6 only hosts.</P>
|
||
|
|
<LI><P><B>java.net.preferIPv6Addresses</B> (default: false)<BR>
|
||
|
|
When dealing with a host which has both IPv4
|
||
|
|
and IPv6 addresses, and if IPv6 is available on the operating
|
||
|
|
system, the default behavior is to prefer using IPv4 addresses over
|
||
|
|
IPv6 ones. This is to ensure backward compatibility, for example
|
||
|
|
applications that depend on the representation of an IPv4 address
|
||
|
|
(e.g. 192.168.1.1). This property can be set to <B>true</B> to
|
||
|
|
change that preference and use IPv6 addresses over IPv4 ones where
|
||
|
|
possible.</P>
|
||
|
|
</UL>
|
||
|
|
<P>Both of these properties are checked only once, at startup.</P>
|
||
|
|
<a name="Proxies"></a>
|
||
|
|
<H2>Proxies</H2>
|
||
|
|
<P>A proxy server allows indirect connection to network services and
|
||
|
|
is used mainly for security (to get through firewalls) and
|
||
|
|
performance reasons (proxies often do provide caching mechanisms).
|
||
|
|
The following properties allow for configuration of the various type
|
||
|
|
of proxies.</P>
|
||
|
|
<UL>
|
||
|
|
<LI><P>HTTP</P>
|
||
|
|
<P>The following proxy settings are used by the HTTP protocol handler.</P>
|
||
|
|
<UL>
|
||
|
|
<LI><P><B>http.proxyHost</FONT></B> (default: <none>)<BR>
|
||
|
|
The hostname, or address, of the proxy server
|
||
|
|
</P>
|
||
|
|
<LI><P><B>http.proxyPort</B> (default: 80)<BR>
|
||
|
|
The port number of the proxy server.</P>
|
||
|
|
<LI><P><B>http.nonProxyHosts</B> (default: <none>)<BR>
|
||
|
|
Indicates the hosts that should be accessed without going
|
||
|
|
through the proxy. Typically this defines internal hosts.
|
||
|
|
The value of this property is a list of hosts,
|
||
|
|
separated by the '|' character. In addition the wildcard
|
||
|
|
character '*' can be used for pattern matching. For example
|
||
|
|
<code>-Dhttp.nonProxyHosts=”*.foo.com|localhost”</code>
|
||
|
|
will indicate that every hosts in the foo.com domain and the
|
||
|
|
localhost should be accessed directly even if a proxy server is
|
||
|
|
specified.</P>
|
||
|
|
</UL>
|
||
|
|
<LI><P>HTTPS<BR>This is HTTP over SSL, a secure version of HTTP
|
||
|
|
mainly used when confidentiality (like on payment sites) is needed.</P>
|
||
|
|
<P>The following proxy settings are used by the HTTPS protocol handler.</P>
|
||
|
|
<UL>
|
||
|
|
<LI><P><B>https.proxyHost</B>(default: <none>)<BR>
|
||
|
|
The hostname, or address, of the proxy server
|
||
|
|
</P>
|
||
|
|
<LI><P><B>https.proxyPort</B> (default: 443)<BR>
|
||
|
|
The port number of the proxy server.</P>
|
||
|
|
<P>The HTTPS protocol handler will use the same nonProxyHosts
|
||
|
|
property as the HTTP protocol.</P>
|
||
|
|
</UL>
|
||
|
|
<LI><P>FTP</P>
|
||
|
|
<P>The following proxy settings are used by the FTP protocol handler.</P>
|
||
|
|
<UL>
|
||
|
|
<LI><P><B>ftp.proxyHost</B>(default: <none>)<BR>
|
||
|
|
The hostname, or address, of the proxy server
|
||
|
|
</P>
|
||
|
|
<LI><P><B>ftp.proxyPort</B> (default: 80)<BR>
|
||
|
|
The port number of the proxy server.</P>
|
||
|
|
<LI><P><B>ftp.nonProxyHosts</B> (default: <none>)<BR>
|
||
|
|
Indicates the hosts that should be accessed without going
|
||
|
|
through the proxy. Typically this defines internal hosts.
|
||
|
|
The value of this property is a list of hosts, separated by
|
||
|
|
the '|' character. In addition the wildcard character
|
||
|
|
'*' can be used for pattern matching. For example
|
||
|
|
<code>-Dhttp.nonProxyHosts=”*.foo.com|localhost”</code>
|
||
|
|
will indicate that every hosts in the foo.com domain and the
|
||
|
|
localhost should be accessed directly even if a proxy server is
|
||
|
|
specified.</P>
|
||
|
|
</UL>
|
||
|
|
<LI><P>SOCKS<BR>This is another type of proxy. It allows for lower
|
||
|
|
level type of tunneling since it works at the TCP level. In effect,
|
||
|
|
in the Java(tm) platform setting a SOCKS proxy server will result in
|
||
|
|
all TCP connections to go through that proxy, unless other proxies
|
||
|
|
are specified. If SOCKS is supported by a Java SE implementation, the
|
||
|
|
following properties will be used:</P>
|
||
|
|
<UL>
|
||
|
|
<LI><P><B>socksProxyHost</B> (default: <non>)<BR>
|
||
|
|
The hostname, or address, of the proxy server.</P>
|
||
|
|
<LI><P><B>socksProxyPort</B> (default: 1080)<BR>
|
||
|
|
The port number of the proxy server.</P>
|
||
|
|
<LI><P><B>java.net.socks.username</B> (default: <none>)<BR>
|
||
|
|
Username to use if the SOCKSv5 server asks for authentication
|
||
|
|
and no java.net.Authenticator instance was found.</P>
|
||
|
|
<LI><P><B>java.net.socks.password</B> (default: <none>)<BR>
|
||
|
|
Password to use if the SOCKSv5 server asks for authentication
|
||
|
|
and no java.net.Authenticator instance was found.</P>
|
||
|
|
<P>Note that if no authentication is provided with either the above
|
||
|
|
properties or an Authenticator, and the proxy requires one, then
|
||
|
|
the <B>user.name</B> property will be used with no password.</P>
|
||
|
|
</UL>
|
||
|
|
<LI><P><B>java.net.useSystemProxies</B> (default: false)<BR>
|
||
|
|
On recent Windows systems and on Gnome 2.x systems it is possible to
|
||
|
|
tell the java.net stack, setting this property to <B>true</B>, to use
|
||
|
|
the system proxy settings (both these systems let you set proxies
|
||
|
|
globally through their user interface). Note that this property is
|
||
|
|
checked only once at startup.</P>
|
||
|
|
</UL>
|
||
|
|
<a name="MiscHTTP"></a>
|
||
|
|
<H2>Misc HTTP properties</H2>
|
||
|
|
<UL>
|
||
|
|
<LI><P><B>http.agent</B> (default: “Java/<version>”)<BR>
|
||
|
|
Defines the string sent in the User-Agent request header in http
|
||
|
|
requests. Note that the string “Java/<version>” will
|
||
|
|
be appended to the one provided in the property (e.g. if
|
||
|
|
-Dhttp.agent=”foobar” is used, the User-Agent header will
|
||
|
|
contain “foobar Java/1.5.0” if the version of the VM is
|
||
|
|
1.5.0). This property is checked only once at startup.</P>
|
||
|
|
<LI><P><B>http.keepalive</B> (default: true)<BR>
|
||
|
|
Indicates if persistent connections should be supported. They improve
|
||
|
|
performance by allowing the underlying socket connection to be reused
|
||
|
|
for multiple http requests. If this is set to true then persistent
|
||
|
|
connections will be requested with HTTP 1.1 servers.</P>
|
||
|
|
<LI><P><B>http.maxConnections</B> (default: 5)<BR>
|
||
|
|
If HTTP keepalive is enabled (see above) this value determines the
|
||
|
|
maximum number of idle connections that will be simultaneously kept
|
||
|
|
alive, per destination.</P>
|
||
|
|
<LI><P><B>http.maxRedirects</B> (default: 20)<BR>
|
||
|
|
This integer value determines the maximum number, for a given request,
|
||
|
|
of HTTP redirects that will be automatically followed by the
|
||
|
|
protocol handler.</P>
|
||
|
|
<LI><P><B>http.auth.digest.validateServer</B> (default: false)</P>
|
||
|
|
<LI><P><B>http.auth.digest.validateProxy</B> (default: false)</P>
|
||
|
|
<LI><P><B>http.auth.digest.cnonceRepeat</B> (default: 5)</P>
|
||
|
|
<P>These 3 properties modify the behavior of the HTTP digest
|
||
|
|
authentication mechanism. Digest authentication provides a limited
|
||
|
|
ability for the server to authenticate itself to the client (i.e.
|
||
|
|
By proving it knows the user's password). However not all HTTP
|
||
|
|
servers support this capability and by default it is turned off. The
|
||
|
|
first two properties can be set to true to enforce this check for
|
||
|
|
authentication with either an origin or proxy server, respectively.</P>
|
||
|
|
<P>It is usually not necessary to change the third property. It
|
||
|
|
determines how many times a cnonce value is re-used. This can be
|
||
|
|
useful when the MD5-sess algorithm is being used. Increasing this
|
||
|
|
value reduces the computational overhead on both client and server
|
||
|
|
by reducing the amount of material that has to be hashed for each
|
||
|
|
HTTP request.</P>
|
||
|
|
<LI><P><B>http.auth.ntlm.domain</B> (default: <none>)<BR>
|
||
|
|
NTLM is another authentication scheme. It uses the
|
||
|
|
java.net.Authenticator class to acquire usernames and passwords when
|
||
|
|
they are needed. However NTLM also needs the NT domain name. There are
|
||
|
|
3 options for specifying that domain:</P>
|
||
|
|
<OL>
|
||
|
|
<LI><P>Do not specify it. In some environments the domain is
|
||
|
|
actually not required and the application does not have to specify
|
||
|
|
it.</P>
|
||
|
|
<LI><P>The domain name can be encoded within the username by
|
||
|
|
prefixing the domain name, followed by a back-slash '\' before the
|
||
|
|
username. With this method existing applications that use the
|
||
|
|
authenticator class do not need to be modified, as long as users
|
||
|
|
are made aware that this notation must be used.</P>
|
||
|
|
<LI><P>If a domain name is not specified as in method 2) and these
|
||
|
|
property is defined, then its value will be used a the domain
|
||
|
|
name.</P>
|
||
|
|
</OL>
|
||
|
|
</UL>
|
||
|
|
<P>All these properties are checked only once at startup.</P>
|
||
|
|
<a name="AddressCache"></a>
|
||
|
|
<H2>Address Cache</H2>
|
||
|
|
<P>The java.net package, when doing name resolution, uses an address
|
||
|
|
cache for both security and performance reasons. Any address
|
||
|
|
resolution attempt, be it forward (name to IP address) or reverse (IP
|
||
|
|
address to name), will have its result cached, whether it was
|
||
|
|
successful or not, so that subsequent identical requests will not
|
||
|
|
have to access the naming service. These properties allow for some
|
||
|
|
tuning on how the cache is operating.</P>
|
||
|
|
<UL>
|
||
|
|
<LI><P><B>networkaddress.cache.ttl</B> (default: see below)<BR>
|
||
|
|
Value is an integer corresponding to the number of seconds successful
|
||
|
|
name lookups will be kept in the cache. A value of -1, or any other
|
||
|
|
negative value for that matter, indicates a “cache forever”
|
||
|
|
policy, while a value of 0 (zero) means no caching. The default value
|
||
|
|
is -1 (forever) if a security manager is installed, and implementation
|
||
|
|
specific when no security manager is installed.</P>
|
||
|
|
<LI><P><B>networkaddress.cache.negative.ttl</B> (default: 10)<BR>
|
||
|
|
Value is an integer corresponding to the number of seconds an
|
||
|
|
unsuccessful name lookup will be kept in the cache. A value of -1,
|
||
|
|
or any negative value, means “cache forever”, while a
|
||
|
|
value of 0 (zero) means no caching.</P>
|
||
|
|
</UL>
|
||
|
|
<P>Since these 2 properties are part of the security policy, they are
|
||
|
|
not set by either the -D option or the System.setProperty() API,
|
||
|
|
instead they are set in the JRE security policy file <code>lib/security/java.security</code>.</P>
|
||
|
|
</BODY>
|
||
|
|
</HTML>
|