2006-09-11 04:19:00 +00:00
|
|
|
<!--
|
|
|
|
|
Licensed to the Apache Software Foundation (ASF) under one or more
|
|
|
|
|
contributor license agreements. See the NOTICE file distributed with
|
|
|
|
|
this work for additional information regarding copyright ownership.
|
|
|
|
|
The ASF licenses this file to You under the Apache License, Version 2.0
|
|
|
|
|
(the "License"); you may not use this file except in compliance with
|
|
|
|
|
the License. You may obtain a copy of the License at
|
|
|
|
|
|
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
|
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
|
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
|
|
|
See the License for the specific language governing permissions and
|
|
|
|
|
limitations under the License.
|
|
|
|
|
-->
|
2005-08-17 13:59:28 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
|
|
|
<link rel="stylesheet" type="text/css" href="stylesheets/style.css">
|
|
|
|
|
<title>Proxy Configuration</title>
|
|
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
<h2>Proxy Configuration</h2>
|
|
|
|
|
|
2006-12-11 22:25:29 +00:00
|
|
|
<p>
|
2010-11-11 17:04:16 +00:00
|
|
|
This page discussing proxy issues on command-line Apache Ant.
|
2006-12-11 22:25:29 +00:00
|
|
|
Consult your IDE documentation for IDE-specific information upon proxy setup.
|
|
|
|
|
</p>
|
|
|
|
|
|
2005-08-17 13:59:28 +00:00
|
|
|
<p>
|
|
|
|
|
|
2007-04-13 15:24:35 +00:00
|
|
|
All tasks and threads running in Ant's JVM share the same HTTP/FTP/Socks
|
2005-08-17 13:59:28 +00:00
|
|
|
proxy configuration.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
When any task tries to retrieve content from an HTTP page, including the
|
|
|
|
|
<code><get></code> task, any automated URL retrieval in
|
|
|
|
|
an XML/XSL task, or any third-party task that uses the <code>java.net.URL</code>
|
|
|
|
|
classes, the proxy settings may make the difference between success and failure.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Anyone authoring a build file behind a blocking firewall will immediately appreciate
|
|
|
|
|
the problems and may want to write a build file to deal with the problem, but
|
|
|
|
|
users of third party build build files may find that the build file itself
|
|
|
|
|
does not work behind the firewall.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
2006-12-11 22:25:29 +00:00
|
|
|
This is a long standing problem with Java and Ant. The only way to fix
|
2012-05-26 12:14:49 +00:00
|
|
|
it is to explicitly configure Ant with the proxy settings, either
|
2006-12-11 22:25:29 +00:00
|
|
|
by passing down the proxy details as JVM properties, or to
|
|
|
|
|
tell Ant on a Java1.5+ system to have the JVM work it out for itself.
|
|
|
|
|
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
2006-12-11 22:25:29 +00:00
|
|
|
<h3>Java1.5+ proxy support (new for Ant1.7)</h3>
|
2005-08-17 13:59:28 +00:00
|
|
|
<p>
|
2006-12-11 22:25:29 +00:00
|
|
|
When Ant starts up, if the <code>-autoproxy</code>
|
|
|
|
|
command is supplied, Ant sets the
|
2005-08-17 13:59:28 +00:00
|
|
|
<code>java.net.useSystemProxies</code> system property. This tells
|
|
|
|
|
a Java1.5+ JVM to use the current set of property settings of the host
|
|
|
|
|
environment. Other JVMs, such as the Kaffe and Apache Harmony runtimes,
|
2006-12-11 22:25:29 +00:00
|
|
|
may also use this property in future.
|
|
|
|
|
It is ignored on the Java1.4 and earlier runtimes.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2006-12-11 22:25:29 +00:00
|
|
|
This property maybe enough to give command-line Ant
|
|
|
|
|
builds network access, although in practise the results
|
2007-04-13 15:24:35 +00:00
|
|
|
are inconsistent.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2007-04-13 15:24:35 +00:00
|
|
|
It is has also been reported a breaking the IBM Java 5 JRE on AIX,
|
|
|
|
|
and does not always work on Linux (presumably due to missing gconf settings)
|
|
|
|
|
Other odd things can go wrong, like Oracle JDBC drivers or pure Java SVN clients.
|
|
|
|
|
</p>
|
|
|
|
|
|
2005-08-17 13:59:28 +00:00
|
|
|
<p>
|
2007-04-13 15:24:35 +00:00
|
|
|
To make the <code>-autoproxy</code> option the default, add it to the environment variable
|
|
|
|
|
<code>ANT_ARGS</code>, which contains a list of arguments to pass to Ant on every
|
|
|
|
|
command line run.
|
2006-12-11 22:25:29 +00:00
|
|
|
</p>
|
|
|
|
|
|
2007-04-13 15:24:35 +00:00
|
|
|
<h4>How Autoproxy works</h4>
|
|
|
|
|
<p>
|
2013-09-13 13:40:23 +00:00
|
|
|
The <code>java.net.useSystemProxies</code> is checked only
|
2007-04-13 15:24:35 +00:00
|
|
|
once, at startup time, the other checks (registry, gconf, system properties) are done
|
|
|
|
|
dynamically whenever needed (socket connection, URL connection etc..).
|
|
|
|
|
</p>
|
|
|
|
|
<h5>Windows</h5>
|
2006-12-11 22:25:29 +00:00
|
|
|
|
|
|
|
|
<p>
|
2007-04-13 15:24:35 +00:00
|
|
|
The JVM goes straight to the registry, bypassing WinInet, as it is not
|
|
|
|
|
present/consistent on all supported Windows platforms (it is part of IE,
|
|
|
|
|
really). Java 7 may use the Windows APIs on the platforms when it is present.
|
2006-12-11 22:25:29 +00:00
|
|
|
</p>
|
|
|
|
|
|
2007-04-13 15:24:35 +00:00
|
|
|
<h5>Linux</h5>
|
|
|
|
|
|
2006-12-11 22:25:29 +00:00
|
|
|
<p>
|
2007-04-13 15:24:35 +00:00
|
|
|
The JVM uses the gconf library to look at specific entries.
|
|
|
|
|
The GConf-2 settings used are:
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
- /system/http_proxy/use_http_proxy boolean
|
|
|
|
|
- /system/http_proxy/use_authentication boolean
|
|
|
|
|
- /system/http_proxy/host string
|
|
|
|
|
- /system/http_proxy/authentication_user string
|
|
|
|
|
- /system/http_proxy/authentication_password string
|
|
|
|
|
- /system/http_proxy/port int
|
|
|
|
|
- /system/proxy/socks_host string
|
|
|
|
|
- /system/proxy/mode string
|
|
|
|
|
- /system/proxy/ftp_host string
|
|
|
|
|
- /system/proxy/secure_host string
|
|
|
|
|
- /system/proxy/socks_port int
|
|
|
|
|
- /system/proxy/ftp_port int
|
|
|
|
|
- /system/proxy/secure_port int
|
|
|
|
|
- /system/proxy/no_proxy_for list
|
|
|
|
|
- /system/proxy/gopher_host string
|
|
|
|
|
- /system/proxy/gopher_port int
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
|
|
|
|
If you are using KDE or another GUI than Gnome, you can still use the
|
|
|
|
|
<code>gconf-editor</code> tool to add these entries.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
|
2007-04-13 15:24:35 +00:00
|
|
|
|
|
|
|
|
<h3>Manual JVM options</h3>
|
2005-08-17 13:59:28 +00:00
|
|
|
<p>
|
|
|
|
|
Any JVM can have its proxy options explicitly configured by passing
|
|
|
|
|
the appropriate <code>-D</code> system property options to the runtime.
|
|
|
|
|
Ant can be configured through all its shell scripts via the
|
|
|
|
|
<code>ANT_OPTS</code> environment variable, which is a list of options to
|
|
|
|
|
supply to Ant's JVM:
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
For bash:
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
|
|
|
|
|
</pre>
|
|
|
|
|
For csh/tcsh:
|
|
|
|
|
<pre>
|
|
|
|
|
setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
|
|
|
|
|
</pre>
|
|
|
|
|
<p>
|
2007-04-13 15:24:35 +00:00
|
|
|
If you insert this line into the Ant shell script itself, it gets picked up
|
|
|
|
|
by all continuous integration tools running on the system that call Ant via the
|
|
|
|
|
command line.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
For Windows, set the <code>ANT_OPTS</code> environment variable in the appropriate "My Computer"
|
|
|
|
|
properties dialog box (winXP), "Computer" properties (Vista)
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
This mechanism works across Java versions, is cross-platform and reliable.
|
|
|
|
|
Once set, all build files run via the command line will automatically have
|
|
|
|
|
their proxy setup correctly, without needing any build file changes. It also
|
2006-03-16 17:17:55 +00:00
|
|
|
apparently overrides Ant's automatic proxy settings options.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
It is limited in the following ways:
|
|
|
|
|
</p>
|
|
|
|
|
<ol>
|
|
|
|
|
<li>Does not work under IDEs. These need their own proxy settings changed</li>
|
|
|
|
|
<li>Not dynamic enough to deal with laptop configuration changes.</li>
|
|
|
|
|
</ol>
|
|
|
|
|
|
2007-04-13 15:24:35 +00:00
|
|
|
|
2005-08-17 13:59:28 +00:00
|
|
|
<h3>SetProxy Task</h3>
|
|
|
|
|
<p>
|
2010-05-26 20:33:51 +00:00
|
|
|
The <a href="Tasks/setproxy.html">setproxy task</a> can be used to
|
2005-08-17 13:59:28 +00:00
|
|
|
explicitly set a proxy in a build file. This manipulates the many proxy
|
|
|
|
|
configuration properties of a JVM, and controls the proxy settings for all
|
|
|
|
|
network operations in the same JVM from that moment.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
If you have a build file that is only to be used in-house, behind a firewall, on
|
|
|
|
|
an older JVM, <i>and you cannot change Ant's JVM proxy settings</i>, then
|
|
|
|
|
this is your best option. It is ugly and brittle, because the build file now contains
|
|
|
|
|
system configuration information. It is also hard to get this right across
|
|
|
|
|
the many possible proxy options of different users (none, HTTP, SOCKS).
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Note that proxy configurations set with this task will probably override
|
|
|
|
|
any set by other mechanisms. It can also be used with fancy tricks to
|
|
|
|
|
only set a proxy if the proxy is considered reachable:
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<pre>
|
|
|
|
|
<target name="probe-proxy" depends="init">
|
|
|
|
|
<condition property="proxy.enabled">
|
|
|
|
|
<and>
|
|
|
|
|
<isset property="proxy.host"/>
|
|
|
|
|
<isreachable host="${proxy.host}"/>
|
|
|
|
|
</and>
|
|
|
|
|
</condition>
|
|
|
|
|
</target>
|
|
|
|
|
|
|
|
|
|
<target name="proxy" depends="probe-proxy" if="proxy.enabled">
|
|
|
|
|
<property name="proxy.port" value="80"/>
|
|
|
|
|
<property name="proxy.user" value=""/>
|
|
|
|
|
<property name="proxy.pass" value=""/>
|
|
|
|
|
<setproxy proxyhost="${proxy.host}" proxyport="${proxy.port}"
|
|
|
|
|
proxyuser="${proxy.user}" proxypassword="${proxy.pass}"/>
|
|
|
|
|
</target>
|
|
|
|
|
</pre>
|
|
|
|
|
|
2007-04-13 15:24:35 +00:00
|
|
|
<h3>Custom ProxySelector implementations</h3>
|
|
|
|
|
<p>
|
|
|
|
|
As Java lets developers write their own ProxySelector implementations, it
|
|
|
|
|
is theoretically possible for someone to write their own proxy selector class that uses
|
|
|
|
|
different policies to determine proxy settings. There is no explicit support
|
|
|
|
|
for this in Ant, and it has not, to the team's knowledge, been attempted.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
This could be the most flexible of solutions, as one could easily imagine
|
|
|
|
|
an Ant-specific proxy selector that was driven off ant properties, rather
|
|
|
|
|
than system properties. Developers could set proxy options in their
|
|
|
|
|
custom build.properties files, and have this propagate.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
One issue here is with concurrency: the default proxy selector is per-JVM,
|
|
|
|
|
not per-thread, and so the proxy settings will apply to all sockets opened
|
|
|
|
|
on all threads; we also have the problem of how to propagate options from
|
|
|
|
|
one build to the JVM-wide selector.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<h3>Configuring the Proxy settings of Java programs under Ant</h3>
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Any program that is executed with <code><java></code> without setting
|
|
|
|
|
<code>fork="true"</code> will pick up the Ant's settings. If you need
|
|
|
|
|
different values, set <code>fork="false"</code> and provide the values
|
|
|
|
|
in <code><sysproperty></code> elements.
|
|
|
|
|
</p>
|
|
|
|
|
If you wish to have
|
|
|
|
|
a forked process pick up the Ant's settings, use the
|
2010-05-26 20:33:51 +00:00
|
|
|
<a href="Types/propertyset.html"><code><syspropertyset></code></a>
|
2007-04-13 15:24:35 +00:00
|
|
|
element to propagate the normal proxy settings. The following propertyset
|
|
|
|
|
is a datatype which can be referenced in a <code><java></code> task to
|
|
|
|
|
pass down the current values.
|
|
|
|
|
|
|
|
|
|
</p>
|
|
|
|
|
<pre>
|
|
|
|
|
<propertyset id="proxy.properties">
|
|
|
|
|
<propertyref prefix="java.net.useSystemProxies"/>
|
|
|
|
|
<propertyref prefix="http."/>
|
|
|
|
|
<propertyref prefix="https."/>
|
|
|
|
|
<propertyref prefix="ftp."/>
|
|
|
|
|
<propertyref prefix="socksProxy"/>
|
|
|
|
|
</propertyset>
|
|
|
|
|
</pre>
|
|
|
|
|
|
2005-08-17 13:59:28 +00:00
|
|
|
<h3>Summary and conclusions</h3>
|
|
|
|
|
<p>
|
2007-04-13 15:24:35 +00:00
|
|
|
There are four ways to set up proxies in Ant.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<ol>
|
2007-04-13 15:24:35 +00:00
|
|
|
<li>With Ant1.7 and Java 1.5+ using the <code>-autoproxy</code> parameter.</li>
|
2005-08-17 13:59:28 +00:00
|
|
|
<li>Via JVM system properties -set these in the ANT_ARGS environment variable.</li>
|
|
|
|
|
<li>Via the <setproxy> task.</li>
|
2007-04-13 15:24:35 +00:00
|
|
|
<li>Custom ProxySelector implementations</li>
|
2005-08-17 13:59:28 +00:00
|
|
|
</ol>
|
2007-04-13 15:24:35 +00:00
|
|
|
<p>
|
|
|
|
|
Proxy settings are automatically shared with Java programs started under Ant <i>
|
|
|
|
|
that are not forked</i>; to pass proxy settings down to subsidiary programs, use
|
|
|
|
|
a propertyset.
|
|
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
Over time, we expect the Java 5+ proxy features to stabilize, and for Java code
|
|
|
|
|
to adapt to them. However, given the fact that it currently does break some
|
|
|
|
|
builds, it will be some time before Ant enables the automatic proxy feature by
|
|
|
|
|
default. Until then, you have to enable the <code>-autoproxy</code> option or
|
|
|
|
|
use one of the alternate mechanisms to configure the JVM.
|
2005-08-17 13:59:28 +00:00
|
|
|
|
|
|
|
|
<h4>Further reading</h4>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2013-09-13 13:40:23 +00:00
|
|
|
<li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/net/properties.html">
|
|
|
|
|
Java Networking Properties</a>.
|
2005-08-17 13:59:28 +00:00
|
|
|
</li>
|
|
|
|
|
</ul>
|
2006-09-11 04:33:25 +00:00
|
|
|
|
2005-08-17 13:59:28 +00:00
|
|
|
</body>
|
2005-08-17 19:34:57 +00:00
|
|
|
</html>
|
