1 | <!--
|
---|
2 | Licensed to the Apache Software Foundation (ASF) under one or more
|
---|
3 | contributor license agreements. See the NOTICE file distributed with
|
---|
4 | this work for additional information regarding copyright ownership.
|
---|
5 | The ASF licenses this file to You under the Apache License, Version 2.0
|
---|
6 | (the "License"); you may not use this file except in compliance with
|
---|
7 | the License. You may obtain a copy of the License at
|
---|
8 |
|
---|
9 | http://www.apache.org/licenses/LICENSE-2.0
|
---|
10 |
|
---|
11 | Unless required by applicable law or agreed to in writing, software
|
---|
12 | distributed under the License is distributed on an "AS IS" BASIS,
|
---|
13 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
---|
14 | See the License for the specific language governing permissions and
|
---|
15 | limitations under the License.
|
---|
16 | -->
|
---|
17 | <html>
|
---|
18 |
|
---|
19 | <head>
|
---|
20 | <meta http-equiv="Content-Language" content="en-us">
|
---|
21 | <link rel="stylesheet" type="text/css" href="stylesheets/style.css">
|
---|
22 | <title>Proxy Configuration</title>
|
---|
23 | </head>
|
---|
24 |
|
---|
25 | <body>
|
---|
26 | <h2>Proxy Configuration</h2>
|
---|
27 |
|
---|
28 | <p>
|
---|
29 | This page discussing proxy issues on command-line ant.
|
---|
30 | Consult your IDE documentation for IDE-specific information upon proxy setup.
|
---|
31 | </p>
|
---|
32 |
|
---|
33 | <p>
|
---|
34 |
|
---|
35 | All tasks running in Ant's JVM share the same HTTP/FTP/Socks
|
---|
36 | proxy configuration.
|
---|
37 | </p>
|
---|
38 |
|
---|
39 | <p>
|
---|
40 | When any task tries to retrieve content from an HTTP page, including the
|
---|
41 | <code><get></code> task, any automated URL retrieval in
|
---|
42 | an XML/XSL task, or any third-party task that uses the <code>java.net.URL</code>
|
---|
43 | classes, the proxy settings may make the difference between success and failure.
|
---|
44 | </p>
|
---|
45 | <p>
|
---|
46 | Anyone authoring a build file behind a blocking firewall will immediately appreciate
|
---|
47 | the problems and may want to write a build file to deal with the problem, but
|
---|
48 | users of third party build build files may find that the build file itself
|
---|
49 | does not work behind the firewall.
|
---|
50 | </p>
|
---|
51 | <p>
|
---|
52 | This is a long standing problem with Java and Ant. The only way to fix
|
---|
53 | it is to explictly configure Ant with the proxy settings, either
|
---|
54 | by passing down the proxy details as JVM properties, or to
|
---|
55 | tell Ant on a Java1.5+ system to have the JVM work it out for itself.
|
---|
56 |
|
---|
57 | </p>
|
---|
58 |
|
---|
59 |
|
---|
60 |
|
---|
61 | <h3>Java1.5+ proxy support (new for Ant1.7)</h3>
|
---|
62 | <p>
|
---|
63 | When Ant starts up, if the <code>-autoproxy</code>
|
---|
64 | command is supplied, Ant sets the
|
---|
65 | <code>java.net.useSystemProxies</code> system property. This tells
|
---|
66 | a Java1.5+ JVM to use the current set of property settings of the host
|
---|
67 | environment. Other JVMs, such as the Kaffe and Apache Harmony runtimes,
|
---|
68 | may also use this property in future.
|
---|
69 | It is ignored on the Java1.4 and earlier runtimes.
|
---|
70 | </p>
|
---|
71 | <p>
|
---|
72 | This property maybe enough to give command-line Ant
|
---|
73 | builds network access, although in practise the results
|
---|
74 | are somewhat disappointing.
|
---|
75 | </p>
|
---|
76 | <p>
|
---|
77 | We are not entirely sure where it reads the property settings from.
|
---|
78 | For windows, it probably reads the appropriate bits of the registry. For
|
---|
79 | Unix/Linux it may use the current Gnome2 settings.
|
---|
80 |
|
---|
81 | <p>
|
---|
82 | One limitation of this feature, other than requiring a 1.5+ JVM,
|
---|
83 | is that it is not dynamic. A long-lasting build hosted on a laptop will
|
---|
84 | not adapt to changes in proxy settings.
|
---|
85 | </p>
|
---|
86 |
|
---|
87 |
|
---|
88 | <p>
|
---|
89 | It is has also been reported a breaking the IBM Java 5 JRE on AIX,
|
---|
90 | and does not appear to work reliably on Linux.
|
---|
91 | Other odd things can go wrong, like Oracle JDBC drivers or pure Java SVN clients.
|
---|
92 | </p>
|
---|
93 |
|
---|
94 | <p>
|
---|
95 | To make the <code>-autproxy</code> option the default, add it to the environment variable
|
---|
96 | <code>ANT_ARGS</code>, which contains a list of arguments to pass to Ant on every
|
---|
97 | command line run.
|
---|
98 | </p>
|
---|
99 |
|
---|
100 | <h3>JVM options</h3>
|
---|
101 | <p>
|
---|
102 | Any JVM can have its proxy options explicitly configured by passing
|
---|
103 | the appropriate <code>-D</code> system property options to the runtime.
|
---|
104 | Ant can be configured through all its shell scripts via the
|
---|
105 | <code>ANT_OPTS</code> environment variable, which is a list of options to
|
---|
106 | supply to Ant's JVM:
|
---|
107 | </p>
|
---|
108 | <p>
|
---|
109 | For bash:
|
---|
110 | </p>
|
---|
111 | <pre>
|
---|
112 | export ANT_OPTS="-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
|
---|
113 | </pre>
|
---|
114 | For csh/tcsh:
|
---|
115 | <pre>
|
---|
116 | setenv ANT_OPTS "-Dhttp.proxyHost=proxy -Dhttp.proxyPort=8080"
|
---|
117 | </pre>
|
---|
118 | <p>
|
---|
119 | For Windows, set the ANT_OPTS environment variable in the appropriate "MyComputer"
|
---|
120 | properties dialog box.
|
---|
121 | </p>
|
---|
122 | <p>
|
---|
123 | This mechanism works across Java versions, is cross-platform and reliable.
|
---|
124 | Once set, all build files run via the command line will automatically have
|
---|
125 | their proxy setup correctly, without needing any build file changes. It also
|
---|
126 | apparently overrides Ant's automatic proxy settings options.
|
---|
127 | </p>
|
---|
128 | <p>
|
---|
129 | It is limited in the following ways:
|
---|
130 | </p>
|
---|
131 | <ol>
|
---|
132 | <li>Does not work under IDEs. These need their own proxy settings changed</li>
|
---|
133 | <li>Not dynamic enough to deal with laptop configuration changes.</li>
|
---|
134 | </ol>
|
---|
135 |
|
---|
136 | <h3>SetProxy Task</h3>
|
---|
137 | <p>
|
---|
138 | The <a href="OptionalTasks/setproxy.html">setproxy task</a> can be used to
|
---|
139 | explicitly set a proxy in a build file. This manipulates the many proxy
|
---|
140 | configuration properties of a JVM, and controls the proxy settings for all
|
---|
141 | network operations in the same JVM from that moment.
|
---|
142 | </p>
|
---|
143 | <p>
|
---|
144 | If you have a build file that is only to be used in-house, behind a firewall, on
|
---|
145 | an older JVM, <i>and you cannot change Ant's JVM proxy settings</i>, then
|
---|
146 | this is your best option. It is ugly and brittle, because the build file now contains
|
---|
147 | system configuration information. It is also hard to get this right across
|
---|
148 | the many possible proxy options of different users (none, HTTP, SOCKS).
|
---|
149 | </p>
|
---|
150 |
|
---|
151 |
|
---|
152 | <p>
|
---|
153 | Note that proxy configurations set with this task will probably override
|
---|
154 | any set by other mechanisms. It can also be used with fancy tricks to
|
---|
155 | only set a proxy if the proxy is considered reachable:
|
---|
156 | </p>
|
---|
157 |
|
---|
158 | <pre>
|
---|
159 | <target name="probe-proxy" depends="init">
|
---|
160 | <condition property="proxy.enabled">
|
---|
161 | <and>
|
---|
162 | <isset property="proxy.host"/>
|
---|
163 | <isreachable host="${proxy.host}"/>
|
---|
164 | </and>
|
---|
165 | </condition>
|
---|
166 | </target>
|
---|
167 |
|
---|
168 | <target name="proxy" depends="probe-proxy" if="proxy.enabled">
|
---|
169 | <property name="proxy.port" value="80"/>
|
---|
170 | <property name="proxy.user" value=""/>
|
---|
171 | <property name="proxy.pass" value=""/>
|
---|
172 | <setproxy proxyhost="${proxy.host}" proxyport="${proxy.port}"
|
---|
173 | proxyuser="${proxy.user}" proxypassword="${proxy.pass}"/>
|
---|
174 | </target>
|
---|
175 | </pre>
|
---|
176 |
|
---|
177 | <h3>Summary and conclusions</h3>
|
---|
178 | <p>
|
---|
179 | There are three ways to set up proxies in Ant.
|
---|
180 | </p>
|
---|
181 | <ol>
|
---|
182 | <li>With Ant1.7 using the <code>-autoproxy</code> parameter.</li>
|
---|
183 | <li>Via JVM system properties -set these in the ANT_ARGS environment variable.</li>
|
---|
184 | <li>Via the <setproxy> task.</li>
|
---|
185 | </ol>
|
---|
186 |
|
---|
187 |
|
---|
188 | <h4>Further reading</h4>
|
---|
189 |
|
---|
190 | <ul>
|
---|
191 | <li><a href="http://java.sun.com/j2se/1.5.0/docs/guide/net/properties.html">
|
---|
192 | Java Networking Properties</a>. Notice how not all proxy settings are documented
|
---|
193 | there.
|
---|
194 | <li><a href="http://blogs.sun.com/roller/resources/jcc/Proxies.pdf">Proxies</a>
|
---|
195 | </li>
|
---|
196 | </ul>
|
---|
197 |
|
---|
198 | </body>
|
---|
199 | </html>
|
---|