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>
|
2018-02-28 07:58:59 +01:00
|
|
|
This page discussing proxy issues on command-line Apache Ant.
|
|
|
|
|
Consult your IDE documentation for IDE-specific information upon
|
|
|
|
|
proxy setup.
|
2006-12-11 22:25:29 +00:00
|
|
|
</p>
|
|
|
|
|
|
2005-08-17 13:59:28 +00:00
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
All tasks and threads running in Ant's JVM share the same
|
|
|
|
|
HTTP/FTP/Socks proxy configuration.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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 Java 5+ system to have the JVM work it out for itself.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
|
2018-03-04 15:17:41 +01:00
|
|
|
<h3>Java 5+ proxy support</h3>
|
|
|
|
|
<p><em>Since Ant 1.7</em></p>
|
2005-08-17 13:59:28 +00:00
|
|
|
<p>
|
2018-03-10 20:17:33 +01:00
|
|
|
When Ant starts up, if the <kbd>-autoproxy</kbd> command is
|
2018-02-28 07:58:59 +01:00
|
|
|
supplied, Ant sets the <code>java.net.useSystemProxies</code> system
|
2018-02-28 17:00:47 +01:00
|
|
|
property. This tells a Java 5+ runtime to use the current set of
|
|
|
|
|
property settings of the host environment. Other JVMs, such as
|
|
|
|
|
Kaffe and Apache Harmony, may also use this property in
|
2018-02-28 07:58:59 +01:00
|
|
|
future. It is ignored on the Java 1.4 and earlier runtimes.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
This property maybe enough to give command-line Ant builds network
|
|
|
|
|
access, although in practise the results are inconsistent.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-03-04 10:36:45 +01:00
|
|
|
It is has also been reported a breaking the IBM Java 5 runtime on AIX,
|
2018-02-28 07:58:59 +01:00
|
|
|
and does not always work on Linux (presumably due to
|
|
|
|
|
missing <code>gconf</code> settings) Other odd things can go wrong,
|
|
|
|
|
like Oracle JDBC drivers or pure Java SVN clients.
|
2007-04-13 15:24:35 +00:00
|
|
|
</p>
|
2005-08-17 13:59:28 +00:00
|
|
|
<p>
|
2018-03-10 20:17:33 +01:00
|
|
|
To make the <kbd>-autoproxy</kbd> option the default, add it to
|
2018-02-28 07:58:59 +01:00
|
|
|
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>
|
2018-02-28 07:58:59 +01:00
|
|
|
The <code>java.net.useSystemProxies</code> is checked only once, at
|
|
|
|
|
startup time, the other checks (registry, <code>gconf</code>, system
|
|
|
|
|
properties) are done dynamically whenever needed (socket connection,
|
|
|
|
|
URL connection etc..).
|
2007-04-13 15:24:35 +00:00
|
|
|
</p>
|
2006-12-11 22:25:29 +00:00
|
|
|
|
2018-02-08 22:52:33 +01:00
|
|
|
<h5>Windows</h5>
|
2006-12-11 22:25:29 +00:00
|
|
|
<p>
|
2018-02-28 07:58:59 +01: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>
|
2018-02-28 07:58:59 +01:00
|
|
|
The JVM uses the <code>gconf</code> library to look at specific
|
|
|
|
|
entries. The <code>GConf-2</code> settings used are:
|
2007-04-13 15:24:35 +00:00
|
|
|
</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>
|
2018-02-28 07:58:59 +01:00
|
|
|
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>
|
2018-02-28 07:58:59 +01:00
|
|
|
Any JVM can have its proxy options explicitly configured by passing
|
2018-03-10 20:17:33 +01:00
|
|
|
the appropriate <kbd>-D</kbd> system property options to the
|
2018-02-28 07:58:59 +01:00
|
|
|
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:
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
|
|
|
|
For bash:
|
2018-02-08 22:52:33 +01:00
|
|
|
</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre>export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"</pre>
|
|
|
|
|
<p>
|
|
|
|
|
For csh/tcsh:
|
|
|
|
|
</p>
|
|
|
|
|
<pre>setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"</pre>
|
2005-08-17 13:59:28 +00:00
|
|
|
<p>
|
2018-02-28 07:58:59 +01: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.
|
2007-04-13 15:24:35 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
For Windows, set the <code>ANT_OPTS</code> environment variable in
|
|
|
|
|
the appropriate "My Computer" properties dialog box (XP), "Computer"
|
|
|
|
|
properties (Vista)
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
2018-02-08 22:52:33 +01:00
|
|
|
<p>
|
2005-08-17 13:59:28 +00:00
|
|
|
It is limited in the following ways:
|
2018-02-08 22:52:33 +01:00
|
|
|
</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<ol>
|
2005-08-17 13:59:28 +00:00
|
|
|
<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>
|
2018-02-28 07:58:59 +01:00
|
|
|
</ol>
|
2005-08-17 13:59:28 +00:00
|
|
|
|
|
|
|
|
<h3>SetProxy Task</h3>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
If you have a build file that is only to be used in-house, behind a
|
|
|
|
|
firewall, on an older JVM, <em>and you cannot change Ant's JVM proxy
|
|
|
|
|
settings</em>, 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).
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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:
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<target name="probe-proxy" depends="init">
|
|
|
|
|
<condition property="proxy.enabled">
|
|
|
|
|
<and>
|
|
|
|
|
<isset property="proxy.host"/>
|
|
|
|
|
<isreachable host="${proxy.host}"/>
|
|
|
|
|
</and>
|
|
|
|
|
</condition>
|
|
|
|
|
</target>
|
2005-08-17 13:59:28 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<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>
|
2005-08-17 13:59:28 +00:00
|
|
|
|
2007-04-13 15:24:35 +00:00
|
|
|
<h3>Custom ProxySelector implementations</h3>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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.
|
2007-04-13 15:24:35 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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.
|
2007-04-13 15:24:35 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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.
|
2007-04-13 15:24:35 +00:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
<h3>Configuring the Proxy settings of Java programs under Ant</h3>
|
|
|
|
|
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
Any program that is executed with <code><java></code> without
|
2018-03-08 07:43:53 +01:00
|
|
|
setting <var>fork</var>=<q>true</q> will pick up the Ant's
|
|
|
|
|
settings. If you need different values,
|
|
|
|
|
set <var>fork</var>=<q>false</q> and provide the values
|
|
|
|
|
in <code><sysproperty></code> elements.
|
2018-02-08 22:52:33 +01:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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.
|
2007-04-13 15:24:35 +00:00
|
|
|
</p>
|
|
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<propertyset id="proxy.properties">
|
|
|
|
|
<propertyref prefix="java.net.useSystemProxies"/>
|
|
|
|
|
<propertyref prefix="http."/>
|
|
|
|
|
<propertyref prefix="https."/>
|
|
|
|
|
<propertyref prefix="ftp."/>
|
|
|
|
|
<propertyref prefix="socksProxy"/>
|
|
|
|
|
</propertyset></pre>
|
2007-04-13 15:24:35 +00:00
|
|
|
|
2005-08-17 13:59:28 +00:00
|
|
|
<h3>Summary and conclusions</h3>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
There are four ways to set up proxies in Ant.
|
2005-08-17 13:59:28 +00:00
|
|
|
</p>
|
|
|
|
|
<ol>
|
2018-03-10 20:17:33 +01:00
|
|
|
<li>With Ant 1.7 and Java 5+ using the <kbd>-autoproxy</kbd> parameter.</li>
|
2018-02-28 16:36:20 +01:00
|
|
|
<li>Via JVM system properties—set these in the <code>ANT_ARGS</code> environment variable.</li>
|
|
|
|
|
<li>Via the <code><setproxy></code> task.</li>
|
2018-02-28 07:58:59 +01:00
|
|
|
<li>Custom ProxySelector implementations</li>
|
2005-08-17 13:59:28 +00:00
|
|
|
</ol>
|
2007-04-13 15:24:35 +00:00
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
Proxy settings are automatically shared with Java programs started
|
|
|
|
|
under Ant <em>that are not forked</em>; to pass proxy settings down
|
|
|
|
|
to subsidiary programs, use a propertyset.
|
2007-04-13 15:24:35 +00:00
|
|
|
</p>
|
|
|
|
|
<p>
|
2018-02-28 07:58:59 +01:00
|
|
|
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
|
2018-03-10 20:17:33 +01:00
|
|
|
to enable the <kbd>-autoproxy</kbd> option or use one of the
|
2018-02-28 07:58:59 +01:00
|
|
|
alternate mechanisms to configure the JVM.
|
|
|
|
|
</p>
|
2005-08-17 13:59:28 +00:00
|
|
|
|
|
|
|
|
<h4>Further reading</h4>
|
|
|
|
|
|
|
|
|
|
<ul>
|
2018-03-08 07:43:53 +01:00
|
|
|
<li><a href="https://docs.oracle.com/javase/8/docs/technotes/guides/net/properties.html"
|
|
|
|
|
target="_top">Java Networking Properties</a>.</li>
|
2005-08-17 13:59:28 +00:00
|
|
|
</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>
|
