Simple Proxy Administration Guide

Simple Proxy Administration Guide Version: Updated: Author: Edited by: Changes: 1.1 10-Jan-2009 Andrew Hallam Jonathan Doig Modified for publication – sensitive information removed Document Purpose To describe the administration of the Simple Proxy as used in the New South Wales Government’s Community Access to Natural Resources Information (CANRI) framework. Familiarity with your organisation’s web application environment (intranet and Internet) and the HTTP protocol basics are assumed. Table of Contents 1 System ............................................................................................................................................... 3 1.1 System Overview .......................................................................................................................... 3 1.2 Terminology Used ........................................................................................................................ 3 1.3 System Data Model ...................................................................................................................... 4 1.4 System Requirements ................................................................................................................... 4 1.5 Release Information...................................................................................................................... 4 2 Installation ......................................................................................................................................... 4 2.1 New Install .................................................................................................................................... 4 2.2 Upgrade ......................................................................................................................................... 5 3 Systems Administration ................................................................................................................... 5 3.1 Configuration Options .................................................................................................................. 5 3.2 Performance Tuning ..................................................................................................................... 5 3.3 Routine Maintenance Procedures ................................................................................................ 5 3.4 Logging ......................................................................................................................................... 5 3.4.1 Tomcat Logging ................................................................................................................... 5 3.4.2 Application Logging ............................................................................................................ 6 3.5 Troubleshooting ............................................................................................................................ 6 3.6 Sample URLs for Testing............................................................................................................. 6 3.7 Files and Directories ..................................................................................................................... 7 4 Application Management ................................................................................................................. 7 4.1 Adding a New Proxy Service....................................................................................................... 7 4.1.1 Examples: ............................................................................................................................. 8 4.1.2 Validating proxy-services.xml ............................................................................................ 9 References    The Simple Proxy software (source or compiled) is available on request from the NSW Natural Resource Atlas Coordinator at nratlas@dipnr.nsw.gov.au HTTP Protocol http://www.ietf.org/rfc/rfc2068.txt Web Map Service 1.1.1 Specification (Open Geospatial Consortium) http://www.opengeospatial.org/docs/01-068r3.pdf 1.1pub Page 1 of 9 Version: Updated: 10-Jan-2009   Short Introduction to Log4j http://logging.apache.org/log4j/docs/manual.html Tomcat 4.1 Documentation http://jakarta.apache.org/tomcat/tomcat-4.1-doc/ Version: Updated: 1.1pub Page 2 of 9 10-Jan-2009 1 System Section Purpose: System documentation describes the system at a component level and conveys how it fits into the overall CANRI framework architecture and the dependencies on other applications. (A “component” is executable code that can be installed as an individual unit.) 1.1 System Overview The Simple Proxy is a generic HTTP proxy that acts as the access point for services that are accessed using HTTP GET requests. It is not Web Map Service (WMS) specific, but that is why it was initially written. A “target service” is usually a remote Web Map Service that is used by the Simple Proxy web application to fulfil WMS requests. Intranet DMZ Internet ArcSDE ArcIMS WMS Connector Simple Proxy External Map Servers Shape files Internal Map Servers NRAtlas External Clients Oracle/EDB In the CANRI environment the Simple Proxy is used for two purposes: 1. To provide public access to selected services on intranet servers. External applications are not allowed to make connections directly with intranet applications for security reasons so they connect to the proxy and the proxy connects to the intranet application on their behalf. Put another way, the proxy is a trusted application that is used to hide the details of intranet applications. 2. To provide access to the external map services (the “target services”) that require minor changes to their URLs in order to provide interoperability. The two classic cases are: a) To allow AGD66 (EPSG:4202) requests to WGS84 (EPSG:4326) map servers (where the data provided can be used interchangeably between the two coordinate systems). b) To force ESRI WMS Connectors to return content types of “text/xml” in response to GetFeatureInfo requests from the NRAtlas. The ability to modify request URLs is done by substituting HTTP GET query parameter values. e.g. An incoming request containing “SRS=EPSG:4202&” could be modified to “SRS=EPSG:4326&” before is passed on to the target service. If the specified query parameter does not exist it will not be appended. The Simple Proxy is a Java servlet application. 1.2 Terminology Used Client Application [client request] [proxy response] Simple Proxy [target service request] [target service response] Target Service Version: Updated: 1.1pub Page 3 of 9 10-Jan-2009 The shortcuts used in this document to describe system paths are: [PROXY_HOME] = [TOMCAT_HOME]/webapps/proxy/ 1.3 System Data Model Not applicable - all data access is managed by the services used by the proxy. 1.4 System Requirements The Simple Proxy is a Java application. It should run on any Servlet 2.3 container, but has only been tested on:     Tomcat 4.1.27-LE on Solaris, Tomcat 4.1.30 on Windows XP J2SDK 1.4.2 Apache 1.3 or 2.0 (if the servlet container is not running on port 80) Mod_jk RAM and CPU requirements are minimal. 1.5 Release Information The currently installed version is 1.3.2. See the readme.txt and licence.txt files included in the distribution. 2 Installation Section Purpose: Installation documentation should provide the details required to install the software with the default configuration. 2.1 New Install Installing the Simple Proxy is a typical Tomcat web application process. Root access is required. Only high level steps will be described here. For more details refer to the Tomcat documentation. 1. Copy the simpleproxy.war file to [TOMCAT_HOME]/webapps/. 2. Create a [TOMCAT_HOME]/webapps/proxy directory. 3. Unpack the WAR file using “jar -xvf ../wmsproxy.war” from inside [TOMCAT_HOME]/webapps/proxy directory. 4. Configure Apache to use mod_jk to pass through requests to Tomcat. JkMount /proxy ajp13 JkMount /proxy/* ajp13 5. If required, edit [PROXY_HOME]/WEB-INF/web.xml file. 6. If required, edit [TOMCAT_HOME]/conf/server.xml. Version: Updated: 1.1pub Page 4 of 9 10-Jan-2009 7. Configure the required proxy services by editing [PROXY_HOME]/WEB-INF/proxyservices.xml. (See 4.1 - Adding a New Proxy Service for details). 8. Restart Tomcat. 9. Restart Apache. 10. Load http://[:]/proxy/ in your web browser and if you see a web page stating “Simple Proxy is Alive” the proxy should be working. 2.2 Upgrade Make a copy of [PROXY_HOME]/WEB-INF/proxy-services.xml, remove the existing web application context from Tomcat, then perform the steps described in the section above. Root access is required. 3 Systems Administration Section Purpose: Systems administration documentation is the information required by the person responsible for configuring and maintaining the application after it has been installed with the default settings. 3.1 Configuration Options Depending on the installation paths used, you may need to change the value of the context parameter “proxy.services.file”. The “proxy.services.file” param-value is relative to [PROXY_HOME]. proxy.services.file WEB-INF/proxy-services.xml 3.2 Performance Tuning Not applicable, Tomcat specific. 3.3   3.4 Routine Maintenance Procedures Archive the application log files on a regular basis. These are located in the [TOMCAT_HOME]/logs directory (unless configured otherwise – see 3.4 - Logging). Store all changes to the proxy-services.xml file in VSS. Logging 3.4.1 Tomcat Logging If you want Tomcat to produce a Simple Proxy specific log file you will need to modify the [TOMCAT_HOME]/conf/server.xml file by adding a context element as follows. Version: Updated: 1.1pub Page 5 of 9 10-Jan-2009  ... ... 3.4.2 Application Logging Simple Proxy uses the Log4j logging framework for application specific logging. Log4j configurations are very flexible so please refer to the Short Introduction to Log4j document for options. 3.5 Troubleshooting No valid response from target service   Ensure the Simple Proxy TargetURI value and other configuration parameters are correct in the proxy-services.xml file. Ensure the Simple Proxy can make outbound HTTP connections to the target service. The DIPNR firewall may be blocking such connections. You can check this on Unix by running “telnet 80” from the command line. If you don’t get a connection there is a security issue at either DIPNR or remote end of the connection. Try making a request directly to the target service from your browser. A GetCapabilities request is usually easiest. Load http://is2.dipnr.nsw.gov.au/proxy in your web browser. If you do not see a web page stating “Simple Proxy is Alive” check if Tomcat and Apache are running. You can bypass Apache by going direct to Tomcat at http://is2.dipnr.nsw.gov.au:8080/proxy/ Check the log files for Java stack traces.    “Invalid service name” error  If the target service you are trying to use is new, make sure you have restarted the Simple Proxy context, using the Tomcat Manager application, after modifying the proxy-services.xml file. Other HTTP errors If the Simple Proxy sends a request to a target service, and that target service returns an HTTP error, the Simple Proxy will forward that error response back to the requesting client. I.e. the error is most likely coming from the remote target service, not the Simple Proxy web application. 3.6 Sample URLs for Testing Pixel Pump: http://it.dipnr.nsw.gov.au/proxy/dipnr/image?WMTVER=1.0&SRS=EPSG%3A4202&REQUEST=map&FORM AT=JPEG&TRANSPARENT=TRUE&EXCEPTIONS=INIMAGE&BBOX=140.59999999999997%2C38.11149999999999%2C153.82%2C27.535499999999995&WIDTH=502&HEIGHT=400&LAYERS=dlwc_landsat_2000_mosaic&STYLES= Version: Updated: 1.1pub Page 6 of 9 10-Jan-2009 Local Government Areas from EDBT: http://it.dipnr.nsw.gov.au/proxy/dipnr/wms_boundaries?VERSION=1.1.1&SERVICE=WMS&REQUEST=Get Map&SRS=EPSG%3A4202&FORMAT=PNG&TRANSPARENT=TRUE&EXCEPTIONS=INIMAGE&BBOX=1 40.59999999999997%2C-38.11149999999999%2C153.82%2C27.535499999999995&WIDTH=500&HEIGHT=400&LAYERS=lga&STYLES= 3.7 Files and Directories Simple Proxy is currently installed on IT (test) and IS (production). The shortcuts used in this document to describe system paths are: [TOMCAT_HOME] = /opt/tomcat4.1.27-LE/ [PROXY_HOME] = [TOMCAT_HOME]/webapps/proxy/ Useful system files and directories: [PROXY_HOME]/WEB-INF/proxy-services.xml (plus the matching XSD) This is the only Simple Proxy service configuration file. It is used to define all the services provided by the proxy, their target resource URLs and any parameter substitutions. [WMS_HOME]/WEB-INF/web.xml Standard Java web application configuration file. 4 Application Management Section Purpose: Application management documentation describes how to use and administer the application for the purpose for which it was developed. 4.1 Adding a New Proxy Service It is recommended that you make all changes to the proxy-services.xml file using an XML aware editor. Note: There is also quite a lot of documentation in the proxy-services.xsd file. When adding a new target service to the Simple Proxy installation you need the following information: Proxy Service Title (Title): A plain English service title of a few words. This is optional, but recommended to make it easy to find the service you are looking for. Proxy Service Description (Description): A plain English description of the service, and any supporting information. Service Name (ProxyPath): The service name is provided in the form of a directory path. It is used in the request URL sent from the client application (see examples in the next section). For consistency we recommend naming the service using the convention: /[/] e.g. /dipnr/nrawater, /dec/bionet, /org/service/subservice, etc. Version: Updated: 1.1pub Page 7 of 9 10-Jan-2009 Target Service (TargetURI): The domain and path values of the target service, to which any additional path and query parameters will be appended. Parameter Substitutions: If a parameter value needs to be set to a fixed value you can configure this in the proxy-services.xml file by providing the parameter name and parameter value to use. If the specified parameter name is not found in the query string it will not be appended. 4.1.1 Examples: Assume that the Internet address (ResourceURL) of the Simple Proxy is: http://it.dipnr.nsw.gov.au/proxy/ Non-Substitution: Service definition from proxy-services.xml: The Pixel Pump server is installed at DIPNR and provides WMS access to large image files (stored in ECW format) /dipnr/image http://172.24.16.68/pump/wms A client request of: http://it.dipnr.nsw.gov.au/proxy/dipnr/image?service=WMS&request=GetCapabilities&version=1.1.1 is translated to a target service request of: http:///pump/wms?service=WMS&request=GetCapabilities&version=1.1.1 Parameter Substitution: Service definition from proxy-services.xml: The NASA Globe data is provided in WGS84 and is suitable for viewing at small scale. Therefore, a small spatial error in the display of the map is acceptable in most circumstances. This Service element allows any WMS client to request WGS84 map images from the NASA server without having to worry about local projection. /nasa/globe http://viz.globe.gov/viz-bin/wmt.cgi SRS EPSG:4326 A client request of: http://it.dipnr.nsw.gov.au/proxy/nasa/globe?styles=REFERENCE&WMTVER=1.0&REQUEST=map&SRS=E PSG:4202&FORMAT=PNG&TRANSPARENT=TRUE&EXCEPTIONS=INIMAGE&BBOX=140.59999999999 997,-38.11149999999999,153.82,27.535499999999995&WIDTH=500&HEIGHT=400&LAYERS=PRAIN&STYLES= Version: Updated: 1.1pub Page 8 of 9 10-Jan-2009 is translated to a target service request of: http://viz.globe.gov/vizbin/wmt.cgi?styles=REFERENCE&WMTVER=1.0&REQUEST=map&SRS=EPSG:4326&FORMAT=PNG&T RANSPARENT=TRUE&EXCEPTIONS=INIMAGE&BBOX=140.59999999999997,38.11149999999999,153.82,27.535499999999995&WIDTH=500&HEIGHT=400&LAYERS=PRAIN&STYLES= In this example, the NASA Globe server only accepts GetMap requests for maps in the WGS84/Geographic projection (EPSG:4326). However, the NRAtlas is configured to ask for the AGD66/Geographic projection (EPSG:4202) in all GetMap requests. Sending requests via the Simple Proxy provides the opportunity to satisfy both parties. 4.1.2 Validating proxy-services.xml The proxy-services.xml file must be well formed XML at all times. An XML editor can be used to validate the proxy-services.xml file using the XML Schema: [PROXY_HOME]/WEB-INF/proxy-services.xsd -- EOF -- Version: Updated: 1.1pub Page 9 of 9 10-Jan-2009