Overview
|
|
The Enterprise Gateway uses HTTP Services to service traffic from
various HTTP-based sources. The following list summarizes the list of available
HTTP Services:
HTTP Interfaces
HTTP Interfaces are used in the Enterprise Gateway to define
the ports and IP addresses on which the Enterprise Gateway Process listens for incoming
requests. You can also add HTTPS Interfaces and select the
SSL certificate to use to authenticate to clients, and also which certificates
are considered trusted for establishing SSL connections with clients.
Relative Path
While HTTP and HTTPS Interfaces open sockets and listen for traffic,
you can configure Relative Paths so that when a
request is received on that path, the Enterprise Gateway Process can map it to
a specific policy or chain of policies.
Static Content Provider
You can use a Static Content Provider to serve static
HTTP content from a particular directory. In this case, the Enterprise Gateway
Process is effectively acting as a Web Server.
Servlet Applications
The Enterprise Gateway Process can act as a servlet container, which enables you
to drop servlets into the HTTP Services configuration. This should only be
used by developers with very specific requirements and under strict advice
from the Oracle support team.
Packet Sniffer
Finally, you can add a Packet Sniffer to intercept
network packets from the client, assemble these packets into complete
HTTP messages, and log these messages to an audit trail. Because the
Packet Sniffer operates at the network layer (unlike an HTTP-based
traffic monitor at the application layer), the packets are intercepted
transparently to the client. Because of this, the Packet Sniffer is a
passive service, which is typically used for SOA
management and monitoring instead of general policy enforcement.
This topic describes how to configure the available HTTP Services.
|
HTTP Services Groups
|
|
An HTTP Services Group is a container around one or
more HTTP Services. Usually, an HTTP Services Group is configured for a
particular type of HTTP Service. For example, it would be typical to have
an HTTP Interfaces Group that contains the configured HTTP
Interfaces, and another Static Providers Group to manage Static
Content Providers. While organizing HTTP Services by type eases the task of
managing Services, the Enterprise Gateway is flexible enough to enable administrators
to organize Services into Groups according to whatever scheme best suits their
requirements.
This section describes a scenario where HTTP Services Groups can prove
useful. It first considers an HTTP Service Group that handles HTTP traffic,
and then shows how you can use a second SSL Service Group to process SSL
traffic on a separate channel.
HTTP Interfaces and Relative Paths
HTTP Services Groups should consist of at least one HTTP Interface together
with at least one Relative Path. The HTTP Interface determines which TCP port
the Process listens on, while you can use the Relative Path to map a request
received on a particular path (request URI) to specific policies. You can add
several HTTP Interfaces to the Groups, in which case requests received on any
one of the opened ports are processed in the same manner. For example,
http://[HOST]:8080/test and http://[HOST]:8081/test
requests can both be processed by the same policy (mapped to the /test
Relative Path).
Similarly, you can add multiple Relative Paths to this HTTP Services Group, where
each Path is bound to a specific policy or chain of policies. For example, if a
request is made to http://[HOST]:8080/a, it is processed by Policy A;
whereas if a request is made to http://[HOST]:8080/b, it is handled
by Policy B. As a side-effect of this configuration, requests made to the other
Interface are also processed by the same policy, meaning that a request made to
http://[HOST]:8081/b is also handled by Policy B.
Effectively, this means that the Relative Paths configured under the HTTP Services
Group are bound to all HTTP Interfaces configured for that Group. In other words,
if you have two Interfaces listening on ports 8080 and 8081, requests to
http://[HOST]:8080/a and
http://[HOST]:8081/a are handled identically by the Process.
Example HTTP Service Group
But what happens if you want to make a distinction between receiving
requests on the two different ports? For example, say you want requests
to http://[HOST]:443/a to be processed by an
SSL Validation policy, while requests for
http://[HOST]:8080/a to be handled by a standard
Schema Validation policy. How can you achieve this?
The addition of a new HTTP Services Group can resolve this issue. The new
SSL HTTP Services Group opens a single HTTPS Interface that listens
on port 443, and is configured with a Relative Path of /a to handle
requests on this path. The configuration is summarized in the following table:
| Services Group |
HTTP Port |
Relative Path |
Policy |
HTTP Services Group |
8080 |
/a |
Schema Validation Policy |
SSL HTTP Services Group |
443 |
/a |
SSL Validation Policy |
With this configuration, when you receive a request on http://[HOST]:8080/a,
it is handled by the Schema Validation Policy. But when you get a request
to the SSL port on http://[HOST]:443/a it is processed by the SSL
Validation Policy. Using HTTP Services Groups in this way, you can configure the
Process to dispatch requests received on the same path (for example, /a) to
different policies depending on the port on which the request was accepted.
Default HTTP Service Groups
By default, the Enterprise Gateway ships with two pre-configured HTTP Services Groups (Default
Services and Management Services). By default, Management
Services are not visible in the Policy Studio, but can be made visible using the
Preferences menu in the Policy Studio. The Default Services
Group contains some general purpose default policies for use with an out-of-the-box installation
of the Enterprise Gateway. In addition to these two pre-configured Service Groups, you can add new HTTP
Services Groups for situations like the one described above where you want to dispatch requests
to different policies, based on the port on which the requests are received.
For more details on the default Management Services Group, see the
Note on Management Services.
Adding an HTTP Service Group
To add a Service Group, right-click the Process, and select the
Add HTTP Services menu option. Enter a name for
the group in the HTTP Services dialog. If you want
to monitor traffic processed by this Service Group using Service Monitor,
check the Include in real time monitoring checkbox.
For details on configuring the Enterprise Gateway to store real-time monitoring
data, which can be used to produce graphical reports in a web-based
interface, see the
Service Monitor Install Guide.
When a Service Group has been created, the following types of HTTP
Services can be associated with it.
|
HTTP and HTTPS Interfaces
|
|
An HTTP Interface defines the address and port that the Enterprise Gateway Process
listens on. There are two types of Interface: HTTP and HTTPS. The HTTP interface
handles standard non-authenticated HTTP requests, while the HTTPS interface can
accept mutually authenticated SSL connections.
To create an HTTP Interface, right-click the name of the HTTP Service Group
(for example, Default Services) in the tree view of the Policy Studio,
and select Add Interface from the menu options. To create an HTTP
Interface, select the HTTP menu option. To create an HTTPS Interface,
select the HTTPS menu option.
Configuring Network Settings
The following fields on the Network tab are common to both the
HTTP Interface and HTTPS Interface dialogs,
and must be configured for both types of interface:
Port:
The port number that the Enterprise Gateway Process listens on for incoming
HTTP requests.
Address:
The IP address or host of the network interface on which the Enterprise Gateway
Process listens. For example, you can configure the Process to listen on
port 80 on the external IP address of a machine, while having a Web server
running on the same port but on the internal IP address of the same machine.
By entering *, the Process listens on all interfaces
available on the machine hosting the Enterprise Gateway.
Protocol:
Select the Internet Protocol version that this Interface uses. You can select
IPv4, IPv6, or both of these protocol versions.
Defaults to IPv4.
Trace level:
The level of trace output. The possible values in order of least verbose
to most verbose output are:
-
FATAL
-
ERROR
-
INFO
-
DEBUG
-
DATA
The default trace level is read from the system settings.
Enable interface:
Unselect this setting to disable this HTTP interface. This setting is
enabled by default.
Configuring Traffic Monitor Settings
The fields on the Traffic Monitor tab are common to both the
HTTP Interface and HTTPS Interface dialogs.
To override the system-level settings at the HTTP or HTTPS interface level,
select Override settings for this port, and configure the
following options:
| Record inbound transactions |
Select whether to record inbound message transactions received by the
Enterprise Gateway. This is enabled by default.
|
| Record outbound transactions |
Select whether to record outbound message transactions sent from
the Enterprise Gateway to remote hosts. This is enabled by default.
|
| Record circuit path |
Select whether to record the circuit path for the message transaction,
which shows the filters that the message passes through. This is enabled
by default.
|
| Record trace |
Select whether to record the trace output for the message transaction.
This is enabled by default.
|
For more details, see Configuring Traffic
Monitor Settings.
Configuring Advanced Settings
The following fields on the Advanced tab are common to both the
HTTP Interface and HTTPS Interface dialogs,
and must be configured for both types of interface:
Backlog:
When the Process is busy handling concurrent requests, the operating
system can accept additional incoming connections. In such cases, a
backlog of connections can build up while the operating system waits
for the Process to finish handling current requests.
The specified Backlog value is the maximum number
of connections that the Process allows the operating system to accept
and queue up until the Process is ready to read them. There is a trade
off: the larger the backlog, the larger the memory usage; the smaller
the backlog, the greater the potential for dropped connections.
Idle Timeout:
The Enterprise Gateway supports the use of HTTP 1.1 persistent connections.
The Idle Timeout is the time that the Process waits
after sending a response over a persistent connection before it closes
the connection. Defaults to 60000 milliseconds (60 seconds).
Typically, a client tells the Process that it wants to use a persistent
connection. The Process acknowledges this instruction and decides to keep
the connection open for a certain amount of time after sending the response
to the client. If the client does not reuse the connection by sending up
another request within the Idle Timeout period, the Process
closes the connection.
Active Timeout:
When the Process receives a large HTTP request, it reads the request off the
network as it becomes available. If the time between reading successive blocks
of data exceeds the Active Timeout, the Process closes the
connection. Defaults to 60000 milliseconds (60 seconds).
This guards against a client closing the connection while
in the middle of sending data. Imagine the client's network connection
is pulled out of the machine while in the middle of sending data to
the Process. When the Process has read all the available data off the
network, it waits the Active Timeout period of time
before closing the connection.
Maximum Memory per Request:
The maximum amount of memory that the Process allocates to each
request, not including the HTTP body.
Input Encodings:
Click the browse button to specify the HTTP content encodings that the Enterprise Gateway
can accept from peers. The available content encodings include gzip and
deflate. By default, the content encodings configured in the Default
Settings are used. You can override this setting at the HTTP interface level
and in the Remote Host Settings. For more details, see the topic on
Compressed Content Encoding.
Output Encodings:
Click the browse button to specify the HTTP content encodings that the Enterprise Gateway can
apply to outgoing messages. The available content encodings include gzip and
deflate. By default, the content encodings configured in the Default
Settings are used. You can override this setting at the HTTP interface level
and in the Remote Host Settings. For more details, see the topic on
Compressed Content Encoding.
Transparent Proxy - allow bind to foreign address:
Enables the use of the Enterprise Gateway as a transparent proxy on Linux
systems with the TPROXY kernel option set. When selected, the value in the
Address field can specify any IP address, and incoming traffic for the
configured address/port combinations is handled by the gateway. For more details and an
example, see Configuring a Transparent
Proxy.
Configuring Conditions for an HTTP Interface
You can configure the Enterprise Gateway to bring down an active HTTP Interface if certain
conditions fail to hold. For example, the HTTP Interface can
be brought down if a Remote Host is not available or if a physical network interface
on the machine on which the Enterprise Gateway is running loses connectivity to the network.
For more information on configuring conditions for
HTTP Interfaces, see the
Configuring Conditions for HTTP Interfaces
help page.
|
HTTPS Interfaces Only
|
|
You must complete the same fields for an HTTPS Interface on the
Network tab as for an HTTP Interface, with the
addition of the following setting:
X.509 Certificate:
Click the X.509 Certificate button to select the
certificate that the Enterprise Gateway uses to authenticate itself to clients
during the SSL handshake. The list of certificates currently stored in
the Certificate Store is displayed. Select a single
certificate from this list.
Configuring Mutual Authentication Settings
You can configure clients to authenticate to the Enterprise Gateway on the
Mutual Authentication tab. The following options
are available:
-
Ignore Client Certificates
The Enterprise Gateway ignores client certificates if they are
presented during the SSL handshake.
-
Accept Client Certificates
Client certificates are accepted when presented to the
Enterprise Gateway, but clients that do not present certificates are not
rejected.
-
Require Client Certificates
The Enterprise Gateway only accepts connections from clients that
present a certificate during the SSL handshake.
Client certificates are typically issued by a Certificate Authority (CA).
In most cases, the CA includes a copy of its certificate in the
client certificate so that consumers of the certificate can decide
whether or not to trust the client based on the issuer of the certificate.
It is also possible that a chain of CAs were involved in issuing
the client certificate. For example, a top-level organization-wide CA (for example,
Company CA) may have issued department-wide CAs (for example, Sales CA, QA CA, and so
on), and each department CA would then be responsible for issuing all department members
with a client certificate. In such cases, the client certificate may contain a chain of
one or more CA certificates.
Maximum depth of client certificate chain:
You can use this field to configure how many CA certificates in a chain of one or more
are trusted when validating the client certificate. By default, only one issuing CA
certificate is used, and this certificate must be checked in the list of trusted root
certificates. If more than one certificate is used, only the top-level CA must be
considered trusted, while the intermediate CA certificates are not.
Root Certificate Authorities trusted for mutual authentication:
Select the root CA certificates that the Enterprise Gateway considers trusted when authenticating
clients during the SSL handshake. Only certificates signed by the CAs selected here are
accepted.
Configuring Advanced SSL Settings
You can complete the following settings on the Advanced (SSL) tab:
SSL Server Name Identifier (SNI):
You can specify the hostnames that are requested by clients in the SSL Server Name
Identifier (SNI) table. SNI is an optional TLS feature whereby the client indicates
to the server the hostname used to resolve the server's address. This enables a server to
present different certificates for clients to ensure the correct site is contacted.
For example, the server IP address is 192.168.0.1. The DNS
is consulted by clients to resolve a hostname to an address, and the server address
is contacted using TCP/IP. If both www.acme.com and
www.anvils.com resolve to 192.168.0.1,
without SNI, the server does not know which hostname the client uses to resolve
the address, because it is not party to the client's DNS name resolution. The server
may be able to certify itself as either service, but when the connection is established,
it does not know which hostname the client connects to.
With SNI, the client provides the name of the host (for example,
www.anvils.com) in the initial SSL exchange,
before the server presents its certificate in its distinguished name
(for example, CN=www.anvils.com). This enables the
server to certify itself correctly as providing a service for the client's
requested hostname.
To specify an SNI, perform the following steps:
- Click the Add button to configure
a server hostname in the SSL Server Name Identifier (SNI) dialog.
- Specify the server hostname in the Client requests server
name field.
- Click the Server assumes identity button to import a
Certificate Authority certificate into the Certificate Store.
-
Click OK.
Ciphers:
You can specify the ciphers that the server supports in the Ciphers
field. The server selects the highest strength cipher (that is also supported by the
client) from this list as part of the SSL handshake. For more information on the syntax
of this setting, please see the
OpenSSL documentation.
SSL session cache size:
Specifies the number of idle SSL sessions that can be kept in memory. You can use this setting
to improve performance because it caches the slowest part of establishing the SSL connection.
A new connection does not need to go through full authentication if it finds its target in the
cache. Defaults to 32. If there are more than 32 simultaneous SSL sessions, this
does not prevent another SSL connection from being established, but means that no more SSL
sessions are cached. A cache size of 0 means the cache size is unlimited.
Ephemeral DH key parameters:
The Diffie Hellman (DH) key agreement algorithm is used to negotiate a shared secret between
two SSL peers. This enables two parties without prior knowledge of each other to jointly
establish a shared secret key over an insecure communication channel. The Ephemeral
DH key parameters setting specifies the parameters used to generate the DH keys.
When DH key parameters are not specified, the SSL client uses the public RSA key in the
server's certificate to encrypt data sent to the SSL server, and establish a shared secret
with the server. However, if the RSA key is ever discovered, any previously recorded encrypted
conversations can be decrypted. DH key agreement offers Perfect Forward Secrecy (PFS) because
there is no such key to be compromised.
There are two options when setting the DH parameters: you can enter a number (for example,
512), and the server automatically generates DH parameters with a prime number
of the correct size. Alternatively, you can paste the Base64 encoding of an existing
serialized DH parameters file. You can use standard DH parameters based on known good prime
numbers. OpenSSL ships with the dh512.pem and dh1024.pem files.
For example, you can set the DH parameters to the following Base64-encoded string in
pdh512.pem:
|
| | |
|
-----BEGIN DH PARAMETERS-----
MEYCQQD1Kv884bEpQBgRjXyEpwpy1obEAxnIByl6ypUM2Zafq9AKUJsCRtMIPWakXUGfnHy9iUsiGSa6q6Jew1XpKgVfAgEC
-----END DH PARAMETERS-----
| |
| | |
|
The DH parameters setting is required if the server is using a DSA-keyed certificate, but also
has an effect when using RSA-based certificates. DH (or similar) key agreement is required for
DSA-based certificates because DSA keys cannot be trivially used to encrypt data like RSA keys
can.
Use EDH key once only:
This setting creates a new key from the DH parameters for every SSL session. This is not strictly
necessary for security if you are sure about the quality of the prime number in the DH key parameters.
When using well-known DH parameters like the example above, you can safely leave this option unselected.
However, given a bad prime number in the parameters, gathering enough key exchanges from a single DH
key can allow an eavesdropper to work out the DH key used. Selecting this option slows down the SSL
session establishment and has a negative impact on performance.
|
Relative Paths
|
|
A Relative Path binds policies to a specific relative path location (for example
/healthcheck). When the Enterprise Gateway receives a request on this relative
path, it invokes the specified policies. For details on how to configure policies,
see Policy Configuration.
To configure a Relative Path for a given HTTP Service Group, right-click the Service
Group in the tree view, and select Add Relative Path. Alternatively,
you can also click the Add Relative Path button at the bottom of the
policy canvas beside the Context drop-down list. Complete the following
settings on the Configure Relative Path dialog:
Enable this path resolver:
You can specify whether to enable listening on the specified path. This is enabled
by default.
Policy:
On the Policy tab, specify the relative path and the policies that are
called. The Enterprise Gateway invokes the selected policies when it receives a request on the
specified path. You can specify a single policy or a chain of policies. Policies are
called in the order displayed on this tab. Complete the following fields:
| When a request arrives that matches the path: |
Enter a relative path (for example, /test) for the selected
HTTP Service Group. Requests received on this relative path are processed
by the policies selected on this tab.
|
| Global Request Policy |
If a global request policy is configured, when you select this setting, the
global request policy is called first in the policy chain. For more details,
see Configuring Global Policies.
|
| Path Specific Policy |
To configure a path-specific policy, select the checkbox, and click the
browse button to select a policy from the dialog. You can search for a
specific policy by entering its name in the text box, and the policy tree
is filtered automatically. The Path Specific Policy field
is auto-populated with the currently selected policy when the dialog is
launched using the Add Relative Path button at the bottom
of the policy canvas.
|
| Global Response Policy |
If a global response policy is configured, when you select this
setting, the global response policy is called last in the policy chain. For
more details, see Configuring Global
Policies.
|
When you select multiple policies to form a policy chain, the behavior is the same as
for a policy shortcut chain filter. Policies are only evaluated when selected, and when
the policy can be reached. If any reachable policy fails, the chain fails, and no more
policies are evaluated.
Audit:
The Audit tab enables you to configure the logging level
for all filters executed on the relative path, and to configure when message
payloads are logged.
You can configure the following Logging Level settings
on all filters executed on the specified relative path:
| Logging Level |
Description |
| Fatal |
Logs Fatal log points that occur on all filters executed.
|
| Failure |
Logs Failure log points that occur on all filters executed.
This is the default logging
level.
|
| Success |
Logs Success log points that occur on all filters executed.
|
For more details on logging levels, and on how to configure logging for
a specific filter, see the Log Level and
Message topic.
You can configure the following Payload Logging settings on the
specified relative path:
| Payload Logging |
Description |
| On receive request from client |
Log the message payload when a request arrives from the client.
|
| On send response to client |
Log the message payload before the response is sent back to the
client.
|
| On send request to remote server |
Log the message payload before the request is sent using any
Connection or Connect to URL
filters deployed in any policies executed.
|
| On receive response from remote server |
Log the message payload when the response is received using any
Connection or Connect to URL
filters deployed in any policies executed.
|
For details on how to log message payloads at any point in a specific policy,
see the Log Message Payload topic.
|
Web Service Resolvers
|
|
A Web Service Resolver is used to identify messages destined for a Web Service, and to
map them to the Service Handler (Web Service Filter)
for that Web Service. When you import a WSDL file, a new Web Service Resolver node is
created for each imported Web Service in the Services tree view. You
can edit the Web Service Resolver settings by right-clicking this tree node, and selecting
Edit.
The following settings are available in the Web Service Resolver dialog:
Enable this web service resolver:
Specify whether to enable this Web Service resolver. This is enabled by default.
Name:
You can edit the name of the Web Service Resolver.
Web Service:
Click the browse button to select a Web Service to resolve to. Defaults to the Web Service
imported into the Web Services Repository when this resolver was created.
Policy:
On the Policy tab, select the path and the policies to use for the Web
Service. You can specify a single policy or a chain of policies. Policies are called in
the order displayed on this tab. The global request policy, the policy automatically
generated when the WSDL file is imported, and the global response policy are all selected
in a chain by default. Complete the following fields:
| matches the paths in the WSDL: |
Select this option if you want the Web Service Resolver to
use the paths specified in the WSDL file. This is the default.
|
| matches this path: |
Select this option if you want to specify a different path
from the WSDL file, and enter the path.
|
| Global Request Policy |
If a global request policy is configured, when you select this
setting, the global request policy is called first in the policy chain. For
more details, see Configuring Global
Policies.
|
| Path Specific Policy |
To configure a path-specific policy, select the checkbox, and click the browse
button to select a policy from the dialog.
|
| Global Response Policy |
If a global response policy is configured, when you select this
setting, the global response policy is called last in the policy chain. For
more details, see Configuring Global
Policies.
|
Policies are only evaluated when selected, and when the policy can be reached. If any
selected policy fails, the chain fails, and no more policies are evaluated.
Audit:
The Audit tab enables you to configure the logging level for all filters
executed on the Web Service, and to configure when message payloads are logged. The default
logging level for all filters on the Web Service is Failure. These logging
settings are the same as those already described for the Audit tab used
for the Relative Path. For more details, see Relative
Paths.
Editing Service Handler Options
You also edit options for the Service Handler for the Web Service. Right-click
the Web Service Resolver node, and select Quick-Edit Policy to display a dialog
that enables you to configure the following options:
|
Validation
|
If you wish to use a dedicated validation policy for all messages sent to the
Web Service, select this checkbox, and click the browse button to configure a
policy in the dialog. For example, this enables you to delegate to a custom
validation policy used by multiple Web Services.
|
|
Routing
|
If you wish to use a dedicated routing policy to send all messages on to the
Web Service, select this checkbox, and click the browse button to configure a
policy in the dialog. For example, this enables you to delegate to a custom
routing policy used by multiple Web Services.
|
|
WSDL Access Options
|
Select whether to make the WSDL for this Web Service available to clients. The
Allow the Enterprise Gateway to publish WSDL to clients checkbox is
selected by default. The published WSDL represents a virtualized view of the
Web Service. Clients can retrieve the WSDL from the Enterprise Gateway, generate SOAP
requests, and send them to the Enterprise Gateway, which routes them on to the Web
Service.
|
These options enable you to configure the underlying auto-generated Service Handler (Web
Service Filter) without navigating to it in the Policies tree. These are
the most commonly modified Web Service Filter options after importing a WSDL file.
Changes made in this dialog are visible in the underlying Web Service Filter. For
more details, see the Web Service Filter topic.
|
Static Content Provider
|
|
A Static Content Provider can be used in
conjunction with an HTTP Interface to serve static content from a
specified directory. A relative path is associated with each Static
Content Provider so that requests received on this path are
dispatched directly to the Provider and are not mapped to a Policy
in the usual manner.
For example, you can configure a Static Content Provider to
serve content from the c:\docs folder (on a Windows
system) when it receives requests on the relative path /docs.
To add a Static Content Provider, right-click the Service Group
under the Process, and select the Static Content Provider
menu option. Complete the following fields on the Static Content
Provider dialog:
Relative Path:
Enter the path that you want to receive requests for static content on.
Content Directory:
Enter or browse to the location of the directory that you want to serve
static content from.
Index File:
Enter the name of the file that you want to use as the index file for
content retrieved from the directory specified in the field above. This
file is retrieved by default if no resource is explicitly specified in the
request URI. For example, if the client requests
http://[HOST]:8080/docs (with only a relative
path specified as opposed to a specific resource), the file specified
here will be retrieved. This file must exist in the directory specified
in the previous field.
Allow Directory Listings:
If this option is selected, the Static Content Provider returns
full directory listings for requests specifying a relative path only.
For example, if this option is selected, and if a request is received
for http://[HOST]:8080/docs/samples, the list
of directories under this directory is returned, assuming that this
directory exists on the file system. This option can be turned off to
prevent attacks where a hacker can send up different request URIs in
the hope that the server returns some information about the directory
structure of the server.
|
Servlet Applications
|
|
Developers may wish to write their own Java servlets and deploy them
under the Enterprise Gateway to serve HTTP traffic. Conversely, they
may wish to remove some of the default servlets from the out-of-the-box
configuration (for example, to remove the ability to view logging
remotely). This pairing down of unwanted functionality may be required
to further lock down the machine on which the Enterprise Gateway is running.
Note:
Adding and removing Servlet Applications should be performed only by developers
with very specific requirements and under strict guidance from the Oracle
Support team. These instructions simply outline how to configure the fields on
the dialogs used to set up Servlet Applications. For more detailed instructions,
please contact the Oracle Support Team.
There are a few default Servlet Applications available under the
Management Services group. By default, this services
group is not visible, but can be displayed using the Preferences
dialog on the Policy Studio. The following table describes the default servlets:
| Servlet Application |
Use |
| /configuration/ |
Updates configuration information for the Enterprise Gateway.
|
| /runtime/ |
Deploys to the server after an update has been made to a policy.
|
| /monitoring/ |
Displays real-time monitoring of server transactions.
|
Please note that deleting any of these Servlet Applications may prevent
the Enterprise Gateway from functioning correctly. Default Servlet Applications
should only be deleted under strict supervision of the Oracle
Support team.
To add a new Servlet Application, right-click the Services Group that
you wish to add the servlet to, and select Add Servlet Application.
Configure the following fields on the Servlet Application dialog:
Relative Path:
Enter the servlet context in this field. You can add multiple
servlets under this context, where each servlet is mapped to a unique URI.
Session Timeout:
Enter the timeout in seconds after which an inactive session is
closed. Click OK.
The new Servlet Application now appears in the Policy Studio tree view.
To add a new servlet, right-click the new Servlet Application,
and select Add Servlet. Configure the following
fields on the Servlet dialog:
URI:
The path entered here maps incoming requests on a particular request URI
to the Java servlet class entered in the field below. This path must be
unique across all Servlets that are added under this Servlet Application
(servlet context).
Class:
Enter the fully qualified class name of the servlet class. This class
can be added to the server runtime by adding the JAR, class file, or
package hierarchy to the [VINSTDIR]/ext/lib folder,
where VINSTDIR points to the root of your Enterprise Gateway
installation.
Read Timeout:
Specify the time in seconds that the servlet should wait before closing
an idle connection.
Servlet Properties:
You can configure properties for each servlet by clicking the
Add button, and entering a name and value
in the fields provided on the Properties dialog.
|
Packet Sniffers
|
|
Packet Sniffers are a type of passive service.
Rather than opening up a TCP port and actively
listening for requests, the Packet Sniffer passively
reads raw data packets off the network interface. The Sniffer assembles
these packets into complete messages that can then be passed into an
associated policy.
Because the Packet Sniffer operates passively (does not listen on a
TCP port) and, therefore, completely transparently to the client, it is
most useful for monitoring and managing Web Services. For example,
the Sniffer can be deployed on a machine running a Web Server
acting as a container for Web Services. Assuming that the Web Server
is listening on TCP port 80 for traffic, the Packet Sniffer can be
configured to read all packets destined for port 80 (or any other port, if
necessary). The packets can then be marshaled into complete HTTP/SOAP
messages by the Sniffer and passed into a policy that logs the message to
a database, for example.
Important Note:
On Linux and Solaris platforms, the Enterprise Gateway must be started by the root user
to gain access to the raw packets.
Because Packet Sniffers are mainly for use as passive monitoring agents,
they are usually created in their own HTTP Service Group. For example,
you can create a new Service Group for this purpose by right-clicking the
Process, selecting the Add HTTP Services menu option,
and entering Packet Sniffer Group on the HTTP
Services dialog.
You can then add a Relative Path Service to this Group by right-clicking
the Packet Sniffer Group, and selecting the Add
Relative Path menu option. Enter a path in the field provided,
and select the policy that you want to dispatch messages to when the Packet
Sniffer detects a request for this path (after it assembles the packets). For
example, if the Relative Path is configured as /a, and the
Packet Sniffer assembles packets into a request for this path, the request
is dispatched to the policy selected in the Relative Path service.
Finally, you can add the Packet Sniffer itself by right-clicking the
Packet Sniffer Group node, selecting
Packet Sniffer, and then the Add
menu option. Complete the following fields on the
Packet Sniffer dialog:
Device to Monitor:
Enter the name or identifier of the network interface that the Packet
Sniffer will monitor. The default entry is any, but it is
important to note that this is only valid on Linux. On UNIX-based systems,
network interfaces are usually identified using names like eth0,
eth1, and so on. On Windows, these names are more complicated
(for example, \Device\NPF_{00B756E0-518A-4144 ... }).
Filter:
You can configure the Packet Sniffer to only intercept certain types of
packets. For example, it can ignore all UDP packets, only intercept
packets destined for port 80 on the network interface, ignore packets
from a certain IP address, listen for all packets on the network, and so
on.
The Packet Sniffer uses the libpcap library filter
language to achieve this. This language has a complicated but powerful
syntax that enables you to filter what packets are
intercepted and what packets are ignored. As a general rule, the syntax
consists of one or more expressions combined with conjunctions, such
as and, or, and not.
The following table lists a few examples of common filters and explains what
they filter:
| Filter Expression |
What does it filter? |
| port 80 |
Capture only traffic for the HTTP Port (80). |
| host 192.168.0.1 |
Capture traffic to and from IP address 192.168.0.1. |
| tcp |
Capture only TCP traffic. |
| host 192.168.0.1 and port 80 |
Capture traffic to and from port 80 on IP address 192.168.0.1.
|
| tcp portrange 8080-8090 |
Capture all TCP traffic destined for ports from 8080 through
to 8090.
|
| tcp port 8080 and not src host 192.168.0.1 |
Capture all TCP traffic destined for port 8080 but not from
IP address 192.168.0.1.
|
The default tcp filter simply captures all TCP packets
arriving on the network interface. For more information on how to configure
filter expressions like these, see the
tcpdump
man pages.
Promiscuous Mode:
When listening in promiscuous mode, the Packet Sniffer captures
all packets on the same Ethernet network, regardless of whether or not the packets
are addressed to the network interface that the Sniffer is monitoring.
|
Management Services
|
|
The Management Services group exposes a number of services
that are used for remote configuration and monitoring. By default, this group
is not visible in the Policy Studio tree view. However, you can view it by selecting
the Window -> Preferences main menu option,
and selecting the Show Management Services checkbox. Click the
Apply button to view the services. This setting also displays
the Management Services under the Policies
node in the Policy Studio tree view.
By default, the Management Services group consists of the
following:
HTTP Interface: Port 8090
By default, the Enterprise Gateway exposes all its management services on port 8090 so
that they can be configured remotely. At startup, the Policy Studio can connect
to this port to read and write Enterprise Gateway configuration data. For more details,
see Changing the Management
Services Port below.
Relative Path: /
The / Relative Path is mapped to a default management policy
called Protect Management Interface, which is available under the
Management Services Policy Container. This policy performs
HTTP Basic Authentication and passes control to the Call Internal
Service filter. This is a special filter that dispatches a
message to a Servlet Application or Static Content Provider based on
the path on which the request was received.
For example, with the default configuration, assume that a request is received on
http://localhost:8090/configuration. The following
steps summarize the request processing cycle:
-
When a Relative Path of
/ is configured, it matches all incoming
requests, and requests are dispatched to whatever policy the Relative Path is mapped to.
In this case, the Relative Path is mapped to the Protect Management Interface
policy, and so the request is passed to this policy.
-
The Protect Management Interface policy performs
HTTP basic authentication on the originator of the request.
Authentication is necessary because all configuration operations are
considered privileged operations and should only be carried out by
those with the authority to do so. If the originator can be
successfully authenticated, the Call Internal Service
filter is invoked.
-
The Call Internal Service filter is a special filter that
passes messages to a Servlet Application or Static Content Provider. In this
case, because the message is received on the management interface (port 8090),
the filter attempts to match the Relative Path on which the request was received
against all the Servlets and Content Providers configured in the same Services
Group as this interface.
-
The configured Servlets and Content Providers for the Management
Services group include
/configuration/, /runtime/,
and /monitoring/. Because the request is received on the
/configuration/ path, this matches the /configuration/
Servlet Application, which is invoked.
Servlet Application: /configuration/
The Policy Studio running on a different host to the Enterprise Gateway can connect to this URL
to remotely configure the Enterprise Gateway. For example if the Enterprise Gateway is running on
a host called SERVER, the Policy Studio can connect to
http://SERVER:8090/configuration/ on startup so that it can
remotely configure policies running at the Enterprise Gateway on the SERVER
host.
Servlet Application: /runtime/
This application is used to receive remote requests to deploy to the server
(for example, by the Policy Studio). When policy updates are made
by the Policy Studio, it is necessary to deploy them to the server so that
the policy updates can take effect immediately. Policy deployment requests
are sent to this application.
Static Content: /monitoring/
You can remotely view real-time traffic analysis of the Enterprise Gateway. To do this,
open a browser, and point it at http://SERVER:8090/monitoring/,
where the Enterprise Gateway is running on a host named SERVER. The
/monitoring/ Static Content Provider then serves a HTML page containing
an embedded flash component that displays real-time monitoring.
Important Note:
Changing the Interfaces, Relative Path, Servlet Applications, or Static Content
Provider exposed under the Management Services group may prevent
the Enterprise Gateway from functioning correctly. Because of this, the Management
Services group is hidden by default, and should only be modified under strict
supervision from the Oracle Support team.
|
Changing the Management Services Port
|
|
The default Management Services port is 8090. To specify a different port,
perform the following steps:
- In the Policy Studio main menu, select Window ->
Preferences, and ensure that the Show Management Services
checkbox is selected.
- Under the Listeners node in the Policy Studio tree,
right-click the Management Services HTTP Interface, and select
Edit.
- Specify an updated value in the Port field (for example,
8091), and click OK.
- Click the Deploy button in the Policy Studio toolbar,
or press F6 to deploy the update.
- Restart Policy Studio. You must restart Policy Studio when Management
Services are updated.
- If you were connected to the Policy Center server, you can use the same URL
to reconnect Policy Studio. If you were connected to the Enterprise Gateway server, you must use the
updated port number in the URL to reconnect Policy Studio (for example,
http://localhost:8091/configuration/deployments/DeploymentService).
- In the Policy Studio, on the Oracle Enterprise Gateway Dashboard,
the Enterprise Gateway Process is displayed as uncontactable because it still uses the original port
number.
- Click the Manage Processes button, select the Enterprise Gateway
Process in the Processes list, and click the Connection
tab.
- Specify the updated port number in the URL field,
click Update, and click OK.
- Wait for the server to be notified about the process URL change (for
example, 60 seconds), and then refresh the Oracle Enterprise Gateway
Dashboard.
- The Process is now displayed as deployed, and you can edit its
configuration.
Important Note:
As stated earlier, you should only modify Management Services under
strict advice and supervision from the Oracle Support team.
|
|