<!--
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.
-->
<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>
<p>
This page discussing proxy issues on command-line Apache Ant.
Consult your IDE documentation for IDE-specific information upon proxy setup.
</p>
<p>
All tasks and threads running in Ant's JVM share the same HTTP/FTP/Socks
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>
This is a long standing problem with Java and Ant. The only way to fix
it is to explicitly configure Ant with the proxy settings, either
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.
</p>
<h3>Java1.5+ proxy support (new for Ant1.7)</h3>
<p>
When Ant starts up, if the <code>-autoproxy</code>
command is supplied, Ant sets the
<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,
may also use this property in future.
It is ignored on the Java1.4 and earlier runtimes.
</p>
<p>
This property maybe enough to give command-line Ant
builds network access, although in practise the results
are inconsistent.
</p>
<p>
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>
<p>
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.
</p>
<h4>How Autoproxy works</h4>
<p>
The <code>java.net.useSystemProxies</code> is checked only
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>
<p>
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.
</p>
<h5>Linux</h5>
<p>
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.
</p>
<h3>Manual JVM options</h3>
<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>
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)
</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
apparently overrides Ant's automatic proxy settings options.
</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>
<h3>SetProxy Task</h3>
<p>
The <a href="Tasks/setproxy.html">setproxy task</a> can be used to
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>
<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
<a href="Types/propertyset.html"><code><syspropertyset></code></a>
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>
<h3>Summary and conclusions</h3>
<p>
There are four ways to set up proxies in Ant.
</p>
<ol>
<li>With Ant1.7 and Java 1.5+ using the <code>-autoproxy</code> parameter.</li>
<li>Via JVM system properties -set these in the ANT_ARGS environment variable.</li>
<li>Via the <setproxy> task.</li>
<li>Custom ProxySelector implementations</li>
</ol>
<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.
<h4>Further reading</h4>
<ul>
<li><a href="http://docs.oracle.com/javase/7/docs/technotes/guides/net/properties.html">
Java Networking Properties</a>.
</li>
</ul>
</body>
</html>
