Proxy Configuration

All tasks running in Ant's JVM share the same HTTP/FTP/Socks proxy configuration.

When any task tries to retrieve content from an HTTP page, including the <get> task, any automated URL retrieval in an XML/XSL task, or any third-party task that uses the java.net.URL classes, the proxy settings may make the difference between success and failure.

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.

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 java.net.useSystemProxies system property, telling the JVM to switch to the OS-configured proxy settings.This is automatic, but it can be disabled.

When running Ant on older JVMs, this property is ignored. There are two other ways to configure Ant's proxy settings in these cases.

Java1.5 automatic proxy support (new for Ant1.7)

When Ant starts up, it automatically sets the java.net.useSystemProxies 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.

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.

To disable this automatic feature, set the command line option -noproxy, or set a JVM or Ant property java.net.useSystemProxies to a value other than true or on. 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.

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.

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 an adaptive laptop, the host's proxy settings will not-automatically adapt to changes in network context. The -noproxy option may be a useful one to use when roaming.

JVM options

Any JVM can have its proxy options explicitly configured by passing the appropriate -D system property options to the runtime. Ant can be configured through all its shell scripts via the ANT_OPTS environment variable, which is a list of options to supply to Ant's JVM:

For bash:

    export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"

For csh/tcsh:

    setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"

For Windows, set the ANT_OPTS environment variable in the appropriate "MyComputer" properties dialog box.

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.

It is limited in the following ways:

Does not work under IDEs. These need their own proxy settings changed
Not dynamic enough to deal with laptop configuration changes.

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.

SetProxy Task

The setproxy task 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.

If you have a build file that is only to be used in-house, behind a firewall, on an older JVM, and you cannot change Ant's JVM proxy settings, 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).

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:

  <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>

Summary and conclusions

There are three ways to set up proxies in Ant.

Automatically, with Ant1.7 -use -noproxy to disable this.
Via JVM system properties -set these in the ANT_ARGS environment variable.
Via the <setproxy> task.

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.