source: release-kits/lirk3/bin/ant-installer/web/manual/manual/proxy.html@ 14982

Last change on this file since 14982 was 14982, checked in by oranfry, 16 years ago

initial import of LiRK3
File size: 6.9 KB
Line 
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>
29This page discussing proxy issues on command-line ant.
30Consult your IDE documentation for IDE-specific information upon proxy setup.
31</p>
32
33<p>
34
35All tasks running in Ant's JVM share the same HTTP/FTP/Socks
36proxy configuration.
37</p>
38
39<p>
40 When any task tries to retrieve content from an HTTP page, including the
41 <code>&lt;get&gt;</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 &lt;target name="probe-proxy" depends="init"&gt;
160 &lt;condition property="proxy.enabled"&gt;
161 &lt;and&gt;
162 &lt;isset property="proxy.host"/&gt;
163 &lt;isreachable host="${proxy.host}"/&gt;
164 &lt;/and&gt;
165 &lt;/condition&gt;
166 &lt;/target&gt;
167
168 &lt;target name="proxy" depends="probe-proxy" if="proxy.enabled"&gt;
169 &lt;property name="proxy.port" value="80"/&gt;
170 &lt;property name="proxy.user" value=""/&gt;
171 &lt;property name="proxy.pass" value=""/&gt;
172 &lt;setproxy proxyhost="${proxy.host}" proxyport="${proxy.port}"
173 proxyuser="${proxy.user}" proxypassword="${proxy.pass}"/&gt;
174 &lt;/target&gt;
175</pre>
176
177<h3>Summary and conclusions</h3>
178<p>
179There 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 &lt;setproxy&gt; 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">
192Java Networking Properties</a>. Notice how not all proxy settings are documented
193there.
194<li><a href="http://blogs.sun.com/roller/resources/jcc/Proxies.pdf">Proxies</a>
195</li>
196</ul>
197
198</body>
199</html>
Note: See TracBrowser for help on using the repository browser.