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 RTCP_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

  1. Use a text editor to open the registration.xml file.
  2. Edit the general, HTTP, HTTPS, and TCP 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 the base-url attribute. Set the security-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, and trustStorePassword 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, or warning.
    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 is off, 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 the exclude 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 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 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 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 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 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.

    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. The greenhat.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 are JKS or PKCS12.

    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 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.

    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 are JKS or PKCS12.

    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 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 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 and 2001 are example port numbers where an 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 Unix-like environments, the proxy needs to be running as a 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)
    • imss or imsconnects (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 is tcp. Any other value is ignored, causing all TCP traffic to be forwarded as raw TCP data.
  3. 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.

Note: You might also need to make configuration changes to each stand-alone application and hosted application that is communicating with the HTTP/TCP proxy by using HTTP(S) traffic. For more information, see the related links.