mirror of
https://github.com/apache/ant.git
synced 2025-05-18 14:04:48 +00:00
782372dee5
git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@442093 13f79535-47bb-0310-9956-ffa450edef68
212 lines
8.1 KiB
HTML
212 lines
8.1 KiB
HTML
<!--
|
|
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>
|
|
|
|
All tasks 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 longstanding problem with Java and Ant, which Java1.5 finally
|
|
addresses. When Ant is run under Java1.5, it automatically sets the
|
|
<code>java.net.useSystemProxies</code> system property, telling the JVM to
|
|
switch to the OS-configured proxy settings.This is automatic, but it can be disabled.
|
|
</p>
|
|
<p>
|
|
When running Ant on older JVMs, this property is ignored. There are two other
|
|
ways to configure Ant's proxy settings in these cases.
|
|
</p>
|
|
|
|
|
|
|
|
<h3>Java1.5 automatic proxy support (new for Ant1.7)</h3>
|
|
<p>
|
|
When Ant starts up, it automatically 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, which is why Ant always sets the
|
|
property -it is ignored on the Java1.4 and earlier runtimes.
|
|
</p>
|
|
<p>
|
|
This property should be enough to automatically give Ant hosted
|
|
builds network access. It may also work under an IDE, though that depends
|
|
upon the IDE and how it starts ant. If it bypasses Ant's Main entry point,
|
|
the proxy setup may be skipped, and if networking has already started up
|
|
by the time ant is run, the option may be ignored. Consult your IDE
|
|
documentation for IDE-specific information upon proxy setup.
|
|
</p>
|
|
<p>
|
|
To disable this automatic feature, set the command line option
|
|
<tt>-noproxy</tt>, or set a JVM or Ant property
|
|
<code>java.net.useSystemProxies</code> to a value other than
|
|
<code>true</code> or <code>on</code>. If the JVM option is already set,
|
|
Ant will not touch it; if an Ant property of that name is set, Ant will
|
|
pass the value of that property down to the JVM.
|
|
</p>
|
|
<p>
|
|
We are not entirely sure where it reads the property settings from.
|
|
For windows, it probably reads the appropriate bits of the registry. For
|
|
Unix/Linux it may use the current Gnome2 settings.
|
|
|
|
<p>
|
|
The biggest limitation of this feature, other than requiring a 1.5+ JVM,
|
|
is that it is not dynamic. A long-lasting build hosted on a laptop will
|
|
not adapt to changes in proxy settings. Furthermore, unless the user
|
|
is running <a
|
|
href="http://www.hpl.hp.com/techreports/2001/HPL-2001-158.html">an adaptive
|
|
laptop</a>, the host's proxy settings will not-automatically adapt to
|
|
changes in network context. The <code>-noproxy</code> option may be a useful
|
|
one to use when roaming.
|
|
</p>
|
|
|
|
<h3>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>
|
|
For Windows, set the ANT_OPTS environment variable in the appropriate "MyComputer"
|
|
properties dialog box.
|
|
</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>
|
|
<p>
|
|
If you are using Ant on a pre-Java1.5 machine behind a firewall, this is
|
|
the simplest and best way to configure your runtime to work with build files
|
|
that go beyond the firewall.
|
|
</p>
|
|
|
|
<h3>SetProxy Task</h3>
|
|
<p>
|
|
The <a href="OptionalTasks/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>Summary and conclusions</h3>
|
|
<p>
|
|
There are three ways to set up proxies in Ant.
|
|
</p>
|
|
<ol>
|
|
<li>Automatically, with Ant1.7 -use <code>-noproxy</code> to disable this.</li>
|
|
<li>Via JVM system properties -set these in the ANT_ARGS environment variable.</li>
|
|
<li>Via the <setproxy> task.</li>
|
|
</ol>
|
|
|
|
<p>
|
|
As Java1.5 adoption increases, automatic proxy support should become more
|
|
widespread. For this reason, we would encourage users not to try and
|
|
second-guess network configurations with setproxy, and instead to encourage
|
|
users to move up to Ant1.7/Java1.5, and if they cannot, to set proxy options
|
|
in the ANT_ARGS environment variable.
|
|
</p>
|
|
|
|
<h4>Further reading</h4>
|
|
|
|
<ul>
|
|
<li><a href="http://java.sun.com/j2se/1.5.0/docs/guide/net/properties.html">
|
|
Java Networking Properties</a>. Notice how not all proxy settings are documented
|
|
there.
|
|
<li><a href="http://blogs.sun.com/roller/resources/jcc/Proxies.pdf">Proxies</a>
|
|
</li>
|
|
</ul>
|
|
|
|
</body>
|
|
</html>
|