Modifying the configuration settings of the HTTP/TCP proxy
To change the server address, log level, and other settings, you can modify the
registration.xml
file of the HTTP/TCP proxy.
Before you begin
You must have set the default port settings for HTTP and TCP proxy during the HCL OneTest™ API installation process.
About this task
The registration.xml
file in Quality_Server_install_directory\httptcp
contains the configuration settings for the
HTTP/TCP proxy.
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 HTTPS function supports mutual authentication of any connections between the proxy and
any intended target servers. 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 plain text (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.
The HTTP/TCP proxy utilizes port 3128 to listen to both HTTP and HTTPS messages.
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="https://localhost:5443/RTCP" security-token="" /> --> <server base-url="https://localhost:5443/RTCP"> <!-- By default this proxy will trust all certificates presented by the server --> <ssl trustAll="true"/> <!-- Replace the ssl element above with the example below for greater control over the trust store and ssl protocol used --> <!-- <ssl trustStore="<HCL Quality Server installation directory>/usr/servers/defaultServer/resources/security/greenhatTrusted.jks" trustStorePassword="passphrase" trustStoreType="jks" protocol="SSL_TLSv2, TLS" /> --> </server> <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
The address of the HCL Quality Server instance. The host name and port number are specified as part of the installation process and by default use HTTPS. The default is port 5443
. If your HCL Quality Server installation is using a different host name or port number, edit thebase-url
attribute. Set thesecurity-token
value if you want to use domain-level security for the proxy.ssl
The SSL connection details that you want to use to connect to the server. The SSL element is optional. If the ssl
element is not included, then the proxy uses the Java keystore location and password that is found in the system properties javax.net.ssl.trustStore and javax.net.ssl.trustStorePassword. If these properties are not set, then the proxy trusts all server certificates.trustAll
- If set to true, this attribute tells the proxy to trust all certificates
that are presented by the server. In this case, the
trustStore
,trustStoreType
, andtrustStorePassword
attributes are ignored. trustStore
- The path to the keystore that contains the trusted certificates that are used to verify the certificate that is presented by the server. By default, this attribute's value is set to the path of the greenhatTrusted.jks keystore, which is included with the HTTP/TCP proxy and contains the HCL OneTest™ API Root CA certificate. If the server's certificate was changed, then this value must also be changed to point to a keystore that contains a certificate that can be used to verify the new server certificate. For more information about configuring the server certificate, see Using your own truststore for server SSL connections.
trustStoreType
- The type attribute specifies the type of the keystore. If not specified,
the default value is
jks
. trustStorePassword
- The password attribute specifies the password that is used to load the
keystore file. The password for the default truststore is
passphrase
. protocol
- The protocol attribute defines the SSL handshake protocol used to
connect to the server.
Default value:
SSL_TLSv2, TLS
.The specified default options are checked for availability. SSL_TLSv2 protocol is supported by the JRE and, if it is unavailable, the TLS protocol is used.
logger level
The activity logging level to present to the HCL Quality Server instance. The level attribute must be set to one of the following values: debug
,error
,info
, orwarning
.identifier
A name for this proxy. This setting makes it easier to identify a specific proxy when two or more proxies of the same type are registered with HCL Quality Server. 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 HCL Quality Server is set to Statistics when the intercept first registers with HCL Quality Server. If the initial state isoff
, the Observation level for this intercept is set to None when the intercept first registers.domains
This setting defines the domains that this proxy instance is registered against. A proxy is not required to register with a domain or environment. By default, the proxy instance can be the 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
Specifies 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 theexclude extension
settings.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 HCL OneTest™ API 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 is used to listen both HTTP and 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").
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 totrue
. By default, this attribute is set tofalse
.Chained proxy configuration settings
In a chained proxy, the user is already connected to the live server by using a proxy, and the HCL OneTest™ API 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 thehost
andport
attributes. You can optionally specify values for theusername
andpassword
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 Basic Authentication to the chained proxy. If any other form of authentication is needed, omit these attributes or leave them blank, and the request flows 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 HCL OneTest™ API versions before 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 tofalse
, 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.
SSL configuration settings
Table 7. HTTP/TCP proxy: Example SSL configuration settings <ssl-settings serverProtocol="SSL_TLSv2, TLS" keyStoreFile="greenhat.jks" keyStoreType="jks" keyStoreAlias="mykey" keyStorePassword="passphrase" signingAlgorithm="SHA256withRSA" plainCommsPort="3131" clientProtocol="SSL_TLSv2, TLS" outboundKeyStoreFile="greenhat.jks" outboundKeyStorePassword="passphrase"> <!-- proxy host="localhost" port="7128" useWhenStubbing="false"/ --> </ssl-settings>
Table 8. HTTP/TCP proxy: SSL configuration settings Attribute Description serverProtocol
The protocol that the secure server socket uses.
Default value:
SSL_TLSv2, TLS
.keyStoreFile
You must enable this attribute in the registration.xml file to use the SSL mode of communications with the HTTP proxy.
The key store file is used to supply key material for the endpoints that are being connected via the proxy. These are either the private key and public certificate of the actual endpoint, or a keypair that will be used to fabricate a new certificate for other endpoints.
The default value of the keyStoreFile attribute is set as
greenhat.jks
. Thegreenhat.jks
file is provided along with the HTTP/TCP proxy.Important: If you use a custom certificate for signing, then a client application or browser might perform various checks that need the certificate chain to be valid, trusted and that each certificate in the chain above the generated certificate is entitled to generate descendant certificates. The ability to generate descendent certificates is achieved by including the BasicConstraint CA=true attribute in all parent certificates. You must work with your server administrators to determine the types of certificates that you want 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
.The values possible for
keyStoreType
areJKS
orPKCS12
.Default value:
JKS
.keyStoreAlias
Each certificate in a JKS is associated with a unique alias.
When the certificates are generated they will be signed by the certificate referred to by the unique alias. If the JKS
greenhat.jks
is used, the default value of thekeyStoreAlias
attribute ismykey
. 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
.Note: The proxy directly utilizes any key pairs that exist in the store where the certificate lists the target endpoint in either the CN or SubjectAlternateName field.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 JRE and, if it is unavailable, the TLS protocol is used.
outboundKeyStoreType
It might be necessary to specify and use a different outbound keystore file type if you want to use an outbound keystore file other than
greenhat.jks
.The values possible for
outboundKeyStoreType
areJKS
orPKCS12
.Default value:
JKS
.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 HCL OneTest™ API HTTPS proxy must connect to the user's proxy. To configure a chained proxy, uncomment the
<proxy>
element within the<ssl-settings>
element and specify values for thehost
andport
attributes. You can optionally specify values for theusername
andpassword
attributes to perform a preemptive authentication and a filter to include or exclude specific hosts.Table 9. Chained proxy: Example SSL configuration settings <ssl-settings disableConnectForwarding="false"> <proxy host="localhost" port="7128" username="user001" password="pa55w0rd" filter="*.ibm.com" useWhenStubbing="false"/> </ssl-settings>
See Chained proxy: HTTP configuration settings 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 default route is specified in a forward element and you can configure as many as you need.
bind
refers to the HTTP/TCP proxy listening port forwarder and optional bind address.Port numbers
2000
and2001
are example port numbers where an HTTP/TCP proxy listens for TCP traffic. If2000
or2001
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 Unix-like environments, the proxy needs to be running as aroot
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
and3001
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 fortype
:fix
(Financial Information eXchange transport traffic)ims
orimsconnect
(IBM® Information Management System (IMS™) Connect transport traffic)imss
orimsconnects
(IBM® Information Management System (IMS™) Connect transport SSL 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 istcp
. 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.