deegree3 proxy configuration
Status: draft
This page discusses the configuration of proxy parameters in deegree3 services and applications.
1. Identified goals
- All http (and possibly ftp) connections initiated by deegree subsystems must respect the proxy settings.
- External libs (e.g. Xerces) used by deegree may also invoke network connections -- these must also respect the settings.
- Configuration must be user-friendly and should especially integrate well with the configuration of deegree services.
2. Intended approach
The Java VM respects a set of system properties (proxyHost, proxyPort, etc.) that allows network-related classes (e.g. java.net.URLConnection) to connect through a proxy:
Description of networking properties from Sun (not all properties are described here)
2.1. General concept
The obvious approach is to ultimately rely on the Java VM system properties to configure the proxy settings for deegree3. This ensures that we can rely on the correct behaviour of the standard java.net classes, such as java.net.URLConnection. This is especially important as we depend on third-party libraries (such as Xerces for XML schema processing) that make network accesses using these classes themselves. If the system properties are set up correctly, then these components should always behave correctly in a proxy environment (although this needs to be tested in each case).
In order to make the proxy configuration more comfortable and easily accessible to users, it should be possible to change the system properties without the need to setup the system's environment variables manually. These is especially useful when a deegree3 service is deployed in a servlet container that is administered by a third party: in this case it's not always feasible to change the environment variables in the startup script of the container (or globally for the machine).
Technically, there should be a class org.deegree.commons.utils.ProxyUtils with methods for setting up the proxy configuration and other proxy related tasks (e.g. logging the current proxy configuration).
2.2. Known limitations / caveats
- deegree must alter the system properties of the VM to apply the proxy settings. If other applications are running in the same VM (e.g. webapps inside a servlet container), then the proxy settings for them are affected as well.
- Different proxy configurations are not supported. Proxy settings are global to all deegree3 subsystem. It's also not possible to have multiple deegree3 webapps in the same servlet container that use different settings.
Apache commons HttpClient is used by deegree3 and does not respect the settings from the proxy system properties. Care must be taken that each use of HttpClient in deegree3 applies the proxy configuration from the system properties (there are helper methods provided in org.deegree.commons.utils.ProxyUtils).
Apparently, proxy authentication (proxies that require username and password) in the java.net classes does not work out of the box. org.deegree.commons.utils.ProxyUtils provides a static method (ProxyUtils#openURLConnection(URL)) to cope with this. Hence, this method should always be used instead of URL#openConnection(). Another (and possibly better) way to make proxy authentication just work, could be the use of a java.net.Authenticator: http://blog.vinodsingh.com/2008/05/proxy-authentication-in-java.html
3. Configuration format
If the settings are not performed using environment variables (which of course is also possible), deegree3 provides an easy mechanism for setting up the proxy from an XML snippet:
<ProxyConfiguration xmlns="http://www.deegree.org/commons" overrideSystemSettings="true">
<ProxyHost>10.19.3.1</ProxyHost>
<ProxyPort>3129</ProxyPort>
<ProxyUser>proxyuser</ProxyUser>
<ProxyPassword>proxyuser</ProxyPassword>
<NonProxyHosts>127.0.0.1|localhost</NonProxyHosts>
</ProxyConfiguration>
Here's the schema fragment that documents all possible options:
<xs:element name="ProxyConfiguration">
<xs:complexType>
<xs:annotation>
<xs:documentation>Parameters that deegree uses to connect to
other resources on the network.</xs:documentation>
</xs:annotation>
<xs:sequence>
<xs:element name="ProxyHost" type="xs:string" minOccurs="0"/>
<xs:element name="HttpProxyHost" type="xs:string" minOccurs="0"/>
<xs:element name="FtpProxyHost" type="xs:string" minOccurs="0"/>
<xs:element name="ProxyPort" type="xs:positiveInteger" minOccurs="0"/>
<xs:element name="HttpProxyPort" type="xs:positiveInteger" minOccurs="0"/>
<xs:element name="FtpProxyPort" type="xs:positiveInteger" minOccurs="0"/>
<xs:element name="ProxyUser" type="xs:string" minOccurs="0"/>
<xs:element name="HttpProxyUser" type="xs:string" minOccurs="0"/>
<xs:element name="FtpProxyUser" type="xs:string" minOccurs="0"/>
<xs:element name="ProxyPassword" type="xs:string" minOccurs="0"/>
<xs:element name="HttpProxyPassword" type="xs:string" minOccurs="0"/>
<xs:element name="FtpProxyPassword" type="xs:string" minOccurs="0"/>
<xs:element name="NonProxyHosts" type="xs:string" minOccurs="0"/>
<xs:element name="HttpNonProxyHosts" type="xs:string" minOccurs="0"/>
<xs:element name="FtpNonProxyHosts" type="xs:string" minOccurs="0"/>
</xs:sequence>
<xs:attribute name="overrideSystemSettings" type="xs:boolean" use="optional"/>
</xs:complexType>
</xs:element>
Note that each settings is available in three flavours, just as in the VM's system properties, e.g. for ProxyHost:
ProxyHost: set the proxy host for all protocols (http and ftp)
HttpProxyHost: set the proxy host for the http protocol (overrides ProxyHost)
FtpProxyHost: set the proxy host for the ftp protocol (overrides ProxyHost)
4. Integration with service configuration
In order to minimize the number of configuration files that have to be edited by a user, the ProxyConfiguration element could be integrated into the main configuration file of the OGCWebServiceConfiguration.
5. Integration with standalone applications
For standalone applications, the setting of the environment variable is generally more feasible (e.g. in a starter script). Additionally, applications may choose to initialize the settings using the same xml element (either integrated the application configuration or as a separate file). Therefore, the following code can be used:
Integrated into XML configuration of application (ProxyConfiguration is a JAXB bean):
... ProxyConfiguration proxyConfig = appConfig.getProxyConfiguration(); ProxyUtils.setupProxyParameters( proxyConfig ); ...
From separate file:
...
ProxyUtils.setupProxyParameters (fileName);
...