HTTP listeners

You can choose between integration node listeners and integration server (embedded) listeners to manage HTTP messages in your HTTP or SOAP flows. Learn about the two types of listener, how ports are assigned to them, and how you can switch from one to the other for individual integration servers.

Your choice of listener affects message flows that handle inbound web service requests and synchronous replies by using the following nodes:
  • SOAPInput with SOAPReply
  • HTTPInput with HTTPReply
Message flows that do not handle inbound requests but that instigate outbound requests or asynchronous responses by using the following nodes are not affected:
  • SOAPRequest
  • SOAPAsyncRequest
  • SOAPAsyncResponse
  • HTTPRequest
  • HTTPAsyncRequest
  • HTTPAsyncResponse

The choice of listener also affects integration services and REST APIs. Integration services use a SOAPInput node, so they use the listener that is specified for the SOAPInput node. REST APIs use an HTTPInput node, so they use the listener that is specified for the HTTPInput node.

The integration node listener requires access to system queues on the queue manager specified on the integration node, so you must install IBM® MQ Server if you want to use an integration node listener. However, if you use HTTP nodes or SOAP nodes with the integration server embedded listener, IBM MQ is not required.

Integration server (embedded) listeners

Each integration server can run an embedded listener. You can configure the listener for HTTP or HTTPS configurations by setting values in the integration server's server.conf.yaml file:
HTTPConnector:
    #ListenerPort: 0                        # Set non-zero to set a specific port, defaults to 7800.
    #ListenerAddress: '0.0.0.0'             # Set the IP address for the listener to listen on. Default is to listen on all addresses.
    #AutoRespondToHTTPHEADRequests: false   # Automatically respond to HTTP HEAD requests without invoking the message flow. Set to true or false, default is false.
    #ServerName: ''                         # Set the value to be returned in the 'Server' HTTP header.
    #CORSEnabled: false                     # Set the value to true to make the listener respond to valid HTTP CORS requests.
    #CORSAllowOrigins: '*'
    #CORSAllowCredentials: false
    #CORSExposeHeaders: 'Content-Type'
    #CORSMaxAge: -1
    #CORSAllowMethods: 'GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS'
    #CORSAllowHeaders: 'Accept,Accept-Language,Content-Language,Content-Type'
HTTPSConnector:
    HTTPSConnector:
    #ListenerPort: 0                        # Set non-zero to set a specific port, defaults to 7843.
    #ListenerAddress: '0.0.0.0'             # Set the IP address for the listener to listen on. Default is to listen on all addresses
    #ReqClientAuth: true
    #KeyAlias: ''
    #KeyPassword: 'myPassword'              # Set the password or alias to the password of the key
    #KeystoreFile: '/path/to/keystore.jks'
    #KeystorePassword: 'myPassword'         # Set the password or alias to the password of the keystore
    #KeystoreType: 'JKS'                    # Set the keystore type, can be 'JKS' or 'p12'. Default is JKS.
    #TruststoreFile: /path/tp/truststore.jks
    #TruststorePassword: 'myPassword'       # Set the password or alias to the password of the keystore
    #TruststoreType: 'JKS'                  # Set the truststore type, can be 'JKS' or 'p12'. Default is JKS. 
    #CipherSpec: ''                         # Comma-separated list of allowable ciphers. IANA cipher names are accepted.
                                            # Example: 'TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384'.
    #CORSEnabled: false                     # Set the value to true to make the listener respond to valid HTTP CORS requests
    #CORSAllowOrigins: '*'
    #CORSAllowCredentials: false
    #CORSExposeHeaders: 'Content-Type'
    #CORSMaxAge: -1
    #CORSAllowMethods: 'GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS'
    #CORSAllowHeaders: 'Accept,Accept-Language,Content-Language,Content-Type'
    #EnableTLSTrace: false                  # Enables tracing of TLS handshake messages to the console

The following examples assume that an integration server is associated with an integration node.

Run the following command to display the HTTPConnector properties for an integration server called default on integration node integrationNodeName:
mqsireportproperties integrationNodeName -e default -o HTTPConnector -r
Run the following command to display the HTTPSConnector properties for an integration server called default on integration node integrationNodeName:
mqsireportproperties integrationNodeName -e default -o HTTPSConnector -r
By default, SOAPInput, SOAPReply, SOAPAsyncResponse, HTTPInput, HTTPReply, and HTTPAsyncResponse nodes use the integration server listener. They also use the integration server listener if the integration node listener is not available, even if you do not explicitly reconfigure them to use the integration server listener. If integration server default on integration node integrationNodeName is using the embedded listener for SOAP nodes or HTTP nodes, the following commands return a value of true:
mqsireportproperties integrationNodeName -e default -o ExecutionGroup -n soapNodesUseEmbeddedListener
mqsireportproperties integrationNodeName -e default -o ExecutionGroup -n httpNodesUseEmbeddedListener

If you configure any of the SOAP nodes or HTTP nodes to use the integration node listener, the previous commands return a value of false.

Integration node listeners

You can configure the integration node listener for HTTP and HTTPS configurations by setting values in the integration node's node.conf.yaml file:

HTTPConnector:
   ListenerPort:  7080
HTTPSConnector:
   ListenerPort:  7083
Run the following two commands to display the currently active settings for the integration node listener:
mqsireportproperties integrationNodeName -b NodeHttpListener -o HTTPConnector -r 
mqsireportproperties integrationNodeName -b NodeHttpListener -o HTTPSConnector -r
Each connector has its own assigned port; default values are 7080 for HTTP and 7083 for HTTPS. You can change these port numbers by using the mqsichangeproperties command. For example, run the following command to change the port on which the integration node listener for integration node integrationNodeName listens for HTTP messages:
mqsichangeproperties integrationNodeName -b NodeHttpListener -o HTTPConnector 
   -n ListenerPort -v 8085
Run the following command to change the port on which the integration node listener for integration node integrationNodeName listens for HTTPS messages:
mqsichangeproperties integrationNodeName -b NodeHttpListener -o HTTPSConnector 
   -n ListenerPort -v 8086

You can configure one or more integration servers so that HTTP nodes that you deploy to those integration servers use the embedded listener, or so that SOAP nodes that you deploy to those integration servers use the integration node listener.

Using both integration node and embedded listeners

Because the option to use the embedded listener is at the integration server level, you can change your configuration such that some integration servers that are associated with an integration node use the integration node listener for HTTP nodes, SOAP nodes, or both, and other integration servers use the embedded listener for HTTP nodes, SOAP nodes, or both.

However, if you disable the integration node listener, the integration server listeners are used for all HTTP and SOAP nodes, even if you do not explicitly enable support for them.

The HTTPRequest node always communicates directly through the HTTP transport, and is therefore unaffected by your choice.

If you change the listener and port that are processing your HTTP or HTTPS messages, you must ensure that you also update your applications to use the updated configuration.