Proxy Configuration

From 753a6c60f47f3ac4f270005b65e9d6481de8eb68 Mon Sep 17 00:00:00 2001 From: Ashlee Young Date: Fri, 23 Oct 2015 10:00:02 -0700 Subject: Adding maven and ant source trees Change-Id: I0a39b9add833a31b9c3f98d193983ae2f3a5a445 Signed-off-by: Ashlee Young --- .../src/ant/apache-ant-1.9.6/manual/proxy.html | 292 +++++++++++++++++++++ 1 file changed, 292 insertions(+) create mode 100644 framework/src/ant/apache-ant-1.9.6/manual/proxy.html (limited to 'framework/src/ant/apache-ant-1.9.6/manual/proxy.html') diff --git a/framework/src/ant/apache-ant-1.9.6/manual/proxy.html b/framework/src/ant/apache-ant-1.9.6/manual/proxy.html new file mode 100644 index 00000000..13ef6e8e --- /dev/null +++ b/framework/src/ant/apache-ant-1.9.6/manual/proxy.html @@ -0,0 +1,292 @@ + + + + + + +Proxy Configuration + + + +

Proxy Configuration

+ +

+This page discussing proxy issues on command-line Apache Ant. +Consult your IDE documentation for IDE-specific information upon proxy setup. +

+ +

+ +All tasks and threads 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 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 Java1.5+ system to have the JVM work it out for itself. + +

+ + + +

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

+ When Ant starts up, if the -autoproxy + command is supplied, Ant 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. + It is ignored on the Java1.4 and earlier runtimes. +

+ This property maybe enough to give command-line Ant + builds network access, although in practise the results + are inconsistent. +

+ It is has also been reported a breaking the IBM Java 5 JRE on AIX, + and does not always work on Linux (presumably due to missing gconf settings) + Other odd things can go wrong, like Oracle JDBC drivers or pure Java SVN clients. +

+ +

+ To make the -autoproxy option the default, add it to the environment variable + ANT_ARGS, which contains a list of arguments to pass to Ant on every + command line run. +

+ +

How Autoproxy works

+The java.net.useSystemProxies is checked only +once, at startup time, the other checks (registry, gconf, system properties) are done +dynamically whenever needed (socket connection, URL connection etc..). +

Windows

+ +

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

+ +

Linux

+ +

+The JVM uses the gconf library to look at specific entries. +The GConf-2 settings used are: +

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

+If you are using KDE or another GUI than Gnome, you can still use the +gconf-editor tool to add these entries. +

+ + +

Manual 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"
+

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

+ For Windows, set the ANT_OPTS environment variable in the appropriate "My Computer" + properties dialog box (winXP), "Computer" properties (Vista) +

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

+ + +

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

+ +

Custom ProxySelector implementations

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

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

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

+ +

Configuring the Proxy settings of Java programs under Ant

+ +

+ Any program that is executed with <java> without setting + fork="true" will pick up the Ant's settings. If you need + different values, set fork="false" and provide the values + in <sysproperty> elements. +

+ If you wish to have + a forked process pick up the Ant's settings, use the + <syspropertyset> + element to propagate the normal proxy settings. The following propertyset + is a datatype which can be referenced in a <java> task to + pass down the current values. + +

+<propertyset id="proxy.properties">
+  <propertyref prefix="java.net.useSystemProxies"/>
+  <propertyref prefix="http."/>
+  <propertyref prefix="https."/>
+  <propertyref prefix="ftp."/>
+  <propertyref prefix="socksProxy"/>
+</propertyset>
+

+ +

Summary and conclusions

+There are four ways to set up proxies in Ant. +

With Ant1.7 and Java 1.5+ using the -autoproxy parameter.
Via JVM system properties -set these in the ANT_ARGS environment variable.
Via the <setproxy> task.
Custom ProxySelector implementations

+Proxy settings are automatically shared with Java programs started under Ant +that are not forked; to pass proxy settings down to subsidiary programs, use +a propertyset. +

+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 to enable the -autoproxy option or +use one of the alternate mechanisms to configure the JVM. + +