Simple Proxy Administration Guide

coldwaterphewΔιακομιστές

17 Νοε 2013 (πριν από 4 χρόνια και 1 μήνα)

114 εμφανίσεις

Version:

1.1pub


Page
1

of
9


Page
1

of
9

Updated:

17
-
Nov
-
2013

Simple Proxy Administration Guide


Version:

1.1

Updated:

17
-
Nov
-
2013

Author:

Andrew Hallam

Edited by:

Jonathan Doig

Changes:

Modified for publication


sensitive inform
ation 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 enviro
nment (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

V
alidating 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.openg
eospatial.org/docs/01
-
068r3.pdf

Version:

1.1pub


Page
2

of
9


Page
2

of
9

Updated:

17
-
Nov
-
2013



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:

1.1pub


Page
3

of
9


Page
3

of
9

Updated:

17
-
Nov
-
2013

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 a
n 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 “targ
et service” is usually a remote Web Map Service that is used by the
Simple Proxy web application to fulfil WMS requests.

DMZ
Oracle/EDB
ArcSDE
ArcIMS
WMS
Connector
Simple
Proxy
Shape
files
Intranet
NRAtlas
External
Map Servers
Internet
Internal
Map Servers
External
Clients


In the CANRI environment the Simple Proxy is used for two purposes:


1.

To provide public access to selected services on intranet serve
rs. 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 al
low 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 re
quests 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 t
he 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
Target
Service
Simple
Proxy
[client request]
[target service request]
[target service response]
[proxy response]

Version:

1.1pub


Page
4

of
9


Page
4

of
9

Updated:

17
-
Nov
-
2013


The shortcuts used in this document to describe system paths are:


[PROXY_HOME]

= [TOMCAT_HOME]/webapps/proxy/



1.3

Sy
stem 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 Sola
ris, 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 we
b 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.

Unp
ack 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.x
ml file.

6.

If required, edit [TOMCAT_HOME]/conf/server.xml.

Version:

1.1pub


Page
5

of
9


Page
5

of
9

Updated:

17
-
Nov
-
2013

7.

Configure the required proxy services by editing [PROXY_HOME]/WEB
-
INF/proxy
-
services.xml. (See
4.1

-

Adding a New Proxy Service

for details).

8.

Re
start Tomcat.

9.

Restart Apache.

10.

Load
http://<hostname>[:<port>]/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 [PROX
Y_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 th
e 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 th
e context
parameter “proxy.services.file”. The “proxy.services.file” param
-
value is relative to
[PROXY_HOME].


<context
-
param>


<param
-
name>proxy.services.file</param
-
name>


<param
-
value>WEB
-
INF/proxy
-
services.xml</param
-
value>

</context
-
param>


3.2

Perf
ormance Tuning


Not applicable, Tomcat specific.


3.3

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.


3.4

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:

1.1pub


Page
6

of
9


Page
6

of
9

Updated:

17
-
Nov
-
2013

<Host name="localhost" debug="0" appBase="webapps"


unpackWARs="true" autoDeploy="true">


...


<!
--

Simple Proxy Context
--
>


<Context path="/proxy" debug="0" docBase="proxy">


<Logger className="org.apac
he.catalina.logger.FileLogger"


prefix="proxy." suffix=".log" timestamp="true" />


</Context>


...

</Host>

3.4.2

Application Logging


Simple Proxy uses the Log4j logging framework for application specific logging. Log4j
configurations are very f
lexible 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 <target_service_domain> 80” from the command line. If you don’t get a conne
ction
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 applicatio
n, 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&FOR
M
AT=JPEG&TRANSPARENT=TRUE&EXCEPTIONS=INIMAGE&BBOX=140.59999999999997%2C
-
38.11149999999999%2C153.82%2C
-
27.535499999999995&WIDTH=502&HEIGHT=400&LAYERS=dlwc_landsat_2000_mosaic&STYLES=

Version:

1.1pub


Page
7

of
9


Page
7

of
9

Updated:

17
-
Nov
-
2013


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%2C
-
27.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]/webapp
s/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 URL
s 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 purp
ose 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 cli
ent application (see examples in the next section). For
consistency we recommend naming the service using the convention:

<appreviated_organisation_name>/<target_service_name>[/<target_service_subname>]


e.g. /dipnr/nrawater, /dec/bionet, /org/service/sub
service, etc.


Version:

1.1pub


Page
8

of
9


Page
8

of
9

Updated:

17
-
Nov
-
2013

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 configu
re
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 Si
mple Proxy is:

http://it.dipnr.nsw.gov.au/proxy/


Non
-
Substitution
:


Service definition from proxy
-
services.xml:



<Service>


<Title>Pixel Pump</Title>


<Description>The Pixel Pump server
is installed at DIPNR


and provides WMS access to large image files (stored in


ECW format)</Description>


<ProxyPath>/dipnr/image</ProxyPath>


<TargetURI>http://172.24.16.68/pump/wms</TargetURI>


</Service>


A client reque
st of:

http://it.dipnr.nsw.gov.au/proxy/dipnr/image?service=WMS&request=GetCapabilities&version
=1.1.1


is translated to a target serv
ice request of:

http://<internal_host>/pump/wms?service=WMS&request=GetCapabilities&version=1.1.1


Parameter Substitution
:


Service definition from proxy
-
services.xml:



<Service>


<Title>NASA Globe</Title>


<Description>The NASA Globe dat
a 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 WGS8
4 map images from the NASA server without having


to worry about local projection.</Description>


<ProxyPath>/nasa/globe</ProxyPath>


<TargetURI>http://viz.globe.gov/viz
-
bin/wmt.cgi</TargetURI>


<Substitute>


<ParamN
ame>SRS</ParamName>


<ParamValue>EPSG:4326</ParamValue>


</Substitute>


</Service>


A client request of:

http://it.dipnr.nsw.gov.au/proxy/nasa/globe?styles=REFERENCE&WMTVER=1.0&REQUEST=map&
SRS=E
PSG:42
02&
FORMAT=PNG&TRANSPARENT=TRUE&EXCEPTIONS=INIMAGE&BBOX=140.59999999999
997,
-
38.11149999999999,153.82,
-
27.535499999999995&WIDTH=500&HEIGHT=400&LAYERS=PRAIN&STYLES=


Version:

1.1pub


Page
9

of
9


Page
9

of
9

Updated:

17
-
Nov
-
2013

is translated to a target service request of:

http://viz.globe.gov/viz
-
bin/wmt.cgi?s
tyles=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 onl
y 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 opportun
ity 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
--