Modifying the configuration settings of the HTTP/TCP proxy
Before you begin
- The HTTP/TCP proxy default port settings for HTTP and TCP proxy are set during the installation process.
- The HTTP/TCP proxy can work either as a standard proxy or a reverse proxy by using forwarding rules. For an explanation of when to use a reverse proxy versus a standard proxy, see Virtualizing HTTP.
- The HTTP/TCP proxy’s HTTPS function supports mutual authentication of any connections between the proxy and any intended target servers. That is, if a server is configured to authenticate any clients that are connecting to it, the server requires HTTP/TCP proxy to present a client certificate to the server for authentication. The keystore that contains this certificate is specified in outboundKeyStoreFile.
- The HTTP/TCP proxy also supports inbound plain text communications from clients and secure onward connections. Although this configuration is unusual, it enables the HTTP/TCP proxy to be used to switch from a client that can use only plaintext (HTTP) communication to a server that accepts only secured (HTTPS) communication. If this function is required, the client must be set to use the plainCommsPort port on the HTTP/TCP proxy, which is configurable.
About this task
The registration.xml file in RTCP_install_directory\httptcp contains the configuration settings for the HTTP/TCP proxy.
Procedure
- Use a text editor to open the registration.xml file.
- Edit the general, HTTP, HTTPS, and TCP configuration
settings.
- General configuration settings
- HTTP configuration settings
- Chained proxy configuration settings
- HTTPS configuration settings
- TCP proxy and reverse proxy configuration settings
General configuration settings
Table 1. HTTP/TCP proxy, Example general configuration settings <server base-url="http://rtcp1.company.com:7819/RTCP"/> <logger level="info"/> <identifier http-name="identifier" tcp-name="identifier2" /> <statistics http-initial-state="on" tcp-initial-state="on"/> <domains> <domain name="testDomain"> <environment name="testEnvironment" /> </domain> </domains> <observed-resources> <exclude extension="htm.?"/> <exclude extension="css"/> <exclude extension="js.?"/> <exclude extension="jpg|gif|png"/> </observed-resources>
Table 2. HTTP/TCP proxy, general configuration settings Element Description server This setting defines the address of the Rational® Test Control Panel instance. The host name and port number are specified as part of the installation process. The default is port 7819. If your Rational Test Control Panel installation is using a different host name or port number, edit the base-url attribute. logger level This setting defines the activity logging level to present to the Rational Test Control Panel instance. The level attribute must be set to one of the following values: debug, error, info, or warning. identifier This setting is for specifying a name for this proxy. This setting makes it easier to identify a specific proxy when there are two or more proxies of the same type are registered with Rational Test Control Panel. By default, this setting is commented out. Therefore, to use this setting, you must first uncomment it and then edit the identifier name. . statistics The initial statistics gathering state for the proxy. HTTP (http-initial-state) and TCP (tcp-initial-state) initial states are controlled separately. If the initial state is on, the Observation level for this intercept in Rational Test Control Panel is set to Statistics when the intercept first registers with Rational Test Control Panel. If the initial state is off, the Observation level for this intercept in Rational Test Control Panel is set to None when the intercept first registers with Rational Test Control Panel. domains This setting defines the domains that this proxy instance is registered against. A proxy does not need to register against a domain or environment. By default it will proxy for all domains and environments. To restrict its use, add <domain> entries based on the example given. Each domain can have 0 or more environments. observed-resources This setting enables you to specify which file extensions are used by the HTTP/TCP proxy when analyzing observed URLs to determine which resources in its traffic can be ignored when collecting observation data. You can use one or more regular expressions to configure the exclude extension settings. If URLs do not contain file extensions, they are included in the observed resources.Note: If URLs do not contain any file extensions that are specified, they are included in the observed resources.reporting frequency By default, observations are reported by the proxy every 10 seconds. If you increase the reporting interval, fewer observation messages are sent over the network, but the data is not available to Rational Integration Tester as frequently. The value is specified in seconds, and values 5 - 30 are allowed. HTTP configuration settings
Table 3. HTTP/TCP proxy, Example HTTP configuration settings <http-proxy port="3128" bind-address="" disableConnectForwarding="false"> <!-- proxy host="localhost" port="7128"/ --> </http-proxy>
Table 4. HTTP/TCP proxy, HTTP configuration settings Attribute Description port
3128 is the default port number where the HTTP/TCP proxy listens for HTTP traffic. Any client applications that communicate with the proxy must also be set to the same port. If this port number is already in use on the computer where the proxy is being installed, you must enter a different port number.
Otherwise, changing the default port number is optional.
bind-address
This setting is optional for multihomed computers with more than one IP address.
Default setting: Blank (meaning "all").
disableConnectForwarding By default, the proxy forwards the HTTPS connect request that is received on the HTTP port to the HTTPS part of the proxy. With this setting enabled, applications can use the same proxy port for both HTTP and HTTPS connections. This default setting can be turned off by changing the disableConnectForwarding attribute value to true. By default, this attribute is set to false.
Chained proxy configuration settings
In a chained proxy, the user is already connected to the live server by using a proxy, and the Rational Integration Tester HTTP proxy must connect to the user's proxy. To configure a chained proxy, uncomment the <proxy> element within the <http-proxy> element and specify values for the host and port attributes. You can optionally specify values for the username and password attributes to perform a preemptive authentication and a filter to include or exclude specific hosts.
Table 5. Chained proxy, Example HTTP configuration settings <http-proxy port="3128" bind-address="" disableConnectForwarding="false"> <proxy host="localhost" port="7128" username="user001" password="pa55w0rd" filter="*.ibm.com" useWhenStubbing="false"/> </http-proxy>
Table 6. Chained proxy, HTTP configuration settings Attribute Description host
The host name of the existing proxy that you want to connect to. port
The port name to connect to on the existing proxy. username
A valid user name for the existing proxy server. These credentials are used to provide preemptive BasicAuthentication to the chained proxy. If any other form of authentication is needed, omit these attributes or leave them blank, and the request will flow back to the client application from which the credentials can be sourced.
password A valid password for the user that is specified in the username attribute. filter A set of hosts for which requests are routed through the chained proxy. For information about creating a filter string, see Host filters for chained proxies. If you do not include the filter attribute, all requests are routed through the chained proxy. useWhenStubbing In Rational Integration Tester versions prior to 8.7.1.1, requests to a stub first go to the chained proxy. From version 8.7.1.1 onwards, you can use the useWhenStubbing parameter to control whether the chained proxy is used. By default, the parameter is set to false, which means two things: - A chained proxy is not used, even if it is defined.
- The onward proxy is still used when requests are not sent to a stub.
HTTPS configuration settings
Table 7. HTTP/TCP proxy, Example HTTPS configuration settings <https-proxy port="3129" bind-address="" serverProtocol="SSL_TLS, TLS" keyStoreFile="greenhat.jks" keyStoreType="jks" keyStoreAlias="mykey" keyStorePassword="passphrase" signingAlgorithm="SHA1withRSA" plainCommsPort="3131" clientProtocol="SSL_TLS, TLS" outboundKeyStoreFile="greenhat.jks" outboundKeyStorePassword="passphrase"> <!-- proxy host="localhost" port="7128"/ --> </https-proxy>
Table 8. HTTP/TCP proxy, HTTPS configuration settings Attribute Description port
3129 is the default port number where the HTTP/TCP proxy listens for HTTPS traffic. Any client applications that communicate with the proxy must also be set to the same port.
If this port number is already in use on the computer where the proxy is being installed, you must enter a different port number.
Otherwise, changing the default port number is optional.
bind-address
This setting is optional for multihomed computers with more than one IP address.
Default setting: Blank (meaning "all").
serverProtocol The protocol that the secure server socket uses.
Default value: SSL_TLS, TLS.
keyStoreFile
The value of the keyStoreFile attribute is set to greenhat.jks, which is included with the HTTP/TCP proxy.
Ordinarily, it is not necessary to specify and use a different Java™ keystore (JKS).
However, you might need to specify and use a different JKS if you want to use your own generated certificate that is already trusted by the client applications or if a specific certificate in the specified JKS was created incorrectly.
Important: To use your own certificate for signing that a client application or browser/client trusts, it needs to be both trusted and that every certificate in the chain above the generated one is entitled to generate descendant certificates, for example, all certificates carry the BasicConstraint CA=true attribute. Work with the appropriate server administrators to determine the types of certificates that you need to create.keyStoreType
It might be necessary to specify and use a different keystore file type if you want to use a keystore file other than greenhat.jks.
Default value: jks.
keyStoreAlias
Each certificate in a JKS is associated with a unique alias.
If the JKS greenhat.jks is used, the default value of the keyStoreAlias attribute is mykey.
However, if a different JKS is used, a different alias must be specified.
keyStorePassword
A JKS protects private keys with a password.
The default keystore password for Trusted Client Certificates is passphrase.
signingAlgorithm
The algorithm that is used when signing certificates.
Default value: SHA1withRSA.
plainCommsPort
The port that is used to handle plain text to SSL communications.
Default value: 3130.
clientProtocol The protocol that the onward secure connection uses. Default value: SSL_TLS, TLS.
The specified default options are checked for availability. SSL_TLS protocol is supported by the IBM® JRE and, if it is unavailable, the TLS protocol is used.
outboundKeyStoreFile
The file that contains public and private keys that are used by the proxy to identify itself during mutual authentication.
Default value: greenhat.jks.
outboundKeyStorePassword
The password that is required to access the keystore that is used during mutual authentication.
The default keystore password for Trusted Client Certificates is passphrase.
Secure chained proxy configuration settings
In a chained proxy, the user is already connected to the live server by using a proxy, and the Rational Integration Tester HTTPS proxy must connect to the user's proxy. To configure a chained proxy, uncomment the <proxy> element within the <https-proxy> element and specify values for the host and port attributes. You can optionally specify values for the username and password attributes to perform a preemptive authentication and a filter to include or exclude specific hosts.
Table 9. Chained proxy, Example HTTP configuration settings <https-proxy port="3128" bind-address="" disableConnectForwarding="false"> <proxy host="localhost" port="7128" username="user001" password="pa55w0rd" filter="*.ibm.com" useWhenStubbing="false"/> </https-proxy>
See Table 6 for a description of these attributes.
TCP proxy and reverse proxy configuration settings
The proxy allows you to configure port forwarding rules. The proxy listens on the address that is specified by the bind attribute and by default forwards traffic on to the destination address. The type attribute indicates how the contents are treated when making recording and routing decisions. For more information, see Configuring a HTTP(S) reverse proxy or TCP port forwarding.Table 10. HTTP/TCP proxy, Example TCP forwarding rules <forward bind="192.168.10.10:2000" destination="example.com:3000" /> <forward bind="[::0]:2001" destination="example.com:3001" type="fix" /> <forward bind="localhost:2002" destination="example.com:3002" type="tcps" />
Table 11. HTTP/TCP proxy, TCP configuration settings Attribute Description bind
Each base, or default, route is specified in a forward element and you can configure as many as you need.
bind refers to the HTTP/TCP proxy’s listening port forwarder and optional bind address.
Port numbers 2000 and 2001 are example port numbers where a HTTP/TCP proxy listens for TCP traffic. If 2000 or 2001 is already in use, you must enter a different port number.
A port number for a bind address can be any number in the range 0-65535.
Note: For Linux or UNIX environments, the proxy needs to be running as root user to bind to port numbers less than 1024.destination
destination refers to the base destination address, that is, the intended destination of TCP traffic from a source if there are no routing rules.
Port numbers 3000 and 3001 are example TCP port numbers where the target application is listening for TCP traffic from a client application.
A port number for a destination address can be any number in the range 0-65535.
type
The optional type attribute can be used to enable more protocol-specific features, such as content-based routing.
The following values are possible for type:- fix (Financial Information eXchange transport traffic)
- ims or imsconnect (IBM Information Management System (IMS™) Connect transport traffic)
- ipic (CICS® IP interconnectivity)
- tcp (TCP connection)
- http (HTTP connection)
- mqtt (MQ telemetry transport connection)
- tcps (TCP connection with SSL/TLS)
- https (HTTP connection with SSL/TLS)
- ipics (CICS IP interconnectivity with SSL/TLS)
- mqtts (MQ telemetry transport connection with SSL/TLS)
Note: The default value is tcp. Any other value is ignored, causing all TCP traffic to be forwarded as raw TCP data. - Save and close the file.
What to do next
You must restart the proxy. For more information, see Starting and stopping the HTTP/TCP proxy.
Feedback