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.

If you use an integration node listener, you must specify a default queue manager for the integration node. For more information, see Interaction between IBM App Connect Enterprise and IBM MQ.

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.
    #HealthCheckServerStartingCode: 503 # Respond to "HEAD /" with the specified HTTP status code during startup. Set to a valid HTTP status code; default is 503.
    #HealthCheckRespondToGET: false # Respond to HTTP "GET /" as well as "HEAD /". Set to true or false; default is false.
    #ServerName: ''               # Set the value to be returned in the 'Server' HTTP response 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,Authorization'
    #DuplicateHeaderAction: 'combineHeaders' # Set to 'combineHeaders' (the default) for standard RFC 2616 behaviour; for compatibility with
                                             # IIB v10 and earlier, set to 'useLastHeader' so that the HTTPInput header value is the taken
                                             # from the last header when duplicate headers are detected. Other valid settings are:
                                             #'useFirstHeader' When duplicate headers are detected use the value from the first instance of the header
                                             #'errorOnDuplicate' Throw an error if duplicate headers are detected
                                             #'combineReservedHeaders' as 'combineHeaders' but also allow the action to be performed on reserved headers
                                             #'useFirstReservedHeader' as 'useFirstHeader' but also allow the action to be performed on reserved headers
                                             #'useLastReservedHeader' as 'useLastHeader' but also allow the action to be performed on reserved headers
                                             #Note that this value must match any value specified for HTTPSConnector below.
    #MaxHeaderSize: 8192          # Set the maximum size for individual inbound HTTP headers. If this limit is exceeded then requests will be rejected with a 413 Entity Too Large error

  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             # Controls whether to request for client certificate during tls handshake.
    #RejectUnauthorizedClient: true  # Controls whether to allow connection without client certificate when ReqClientAuth is set.
    #KeyAlias: ''
    #KeyPassword: 'P4s5w0rd'         # Set the password or alias to the password of the key
    #KeystoreFile: '/path/to/keystore.jks'
    #KeystorePassword: 'P4s5w0rd'    # Set the password or alias to the password of the keystore
    #KeystoreType: 'JKS'             # Set the key store type, can be 'JKS' or 'PKCS12'. Default is JKS.
    #TruststoreFile: /path/tp/truststore.jks
    #TruststorePassword: 'P4s5w0rd'  # Set the password or alias to the password of the keystore
    #TruststoreType: 'JKS'           # Set the truststore type, can be 'JKS', 'PEM' or 'PKCS12'. Default is JKS.
    #CipherSpec: ''                  # Comma-separated list of allowable ciphers. IANA cipher names are accepted.
                                     # Example: 'TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384'.
    #AutoRespondToHTTPHEADRequests: false # Automatically respond to HTTP HEAD requests without invoking the message flow. Set to true or false; default is false.
    #HealthCheckServerStartingCode: 503 # Respond to "HEAD /" with the specified HTTP status code during startup. Set to a valid HTTP status code; default is 503.
    #HealthCheckRespondToGET: false # Respond to HTTP "GET /" as well as "HEAD /". Set to true or false; default is false.
    #ServerName: ''                  # Set the value to be returned in the 'Server' HTTP response 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,Authorization'
    #TLSProtocols: 'all'          # Enabled versions of the TLS protocols. Default is 'all'.
                                  # Can be  'all', 'none', 'TLSv1.2', 'TLSv1.3', or 'TLSv1.2,TLSv1.3'.
    #EnableTLSTrace: false           # Enables tracing of TLS handshake messages to the console
    #AllowRenegotiation: true        # Controls whether renegotiation of connections is allowed when using TLSv1.2 and earlier.
    #DuplicateHeaderAction: 'combineHeaders' # Set to 'combineHeaders' (the default) for standard RFC 2616 behaviour; for compatibility with
                                             # IIB v10 and earlier, set to 'useLastHeader' so that the HTTPInput header value is the taken
                                             # from the last header when duplicate headers are detected. Other valid settings are:
                                             #'useFirstHeader' When duplicate headers are detected use the value from the first instance of the header
                                             #'errorOnDuplicate' Throw an error if duplicate headers are detected
                                             #'combineReservedHeaders' as 'combineHeaders' but also allow the action to be performed on reserved headers
                                             #'useFirstReservedHeader' as 'useFirstHeader' but also allow the action to be performed on reserved headers
                                             #'useLastReservedHeader' as 'useLastHeader' but also allow the action to be performed on reserved headers
                                             #Note that this value must match any value specified for HTTPSConnector below.
    #MaxHeaderSize: 8192          # Set the maximum size for individual inbound HTTP headers. If this limit is exceeded then requests will be silently rejected

For more information about these parameters, see Integration server HTTP listener parameters (SOAP and HTTP nodes).

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.

Configuring HTTP listeners to use IPv6

IBM App Connect Enterprise supports connections to TCP/IP addresses in Internet Protocol version 6 (IPv6) format, in addition to Internet Protocol version 4 (IPv4). IPv4 is still used by default. The main difference between the two is that IPv6 has a larger address space, so you are less likely to run out of addresses. To make IBM App Connect Enterprise listen on all available IPv6 and IPv4 addresses, configure your HTTPSConnector in the server.conf.yaml file as follows:

HTTPSConnector:
    ListenerPort: 7800
    ListenerAddress: '::'
For more information about configuring IBM App Connect Enterprise to use IPv6, see Configuring IBM App Connect Enterprise to use IPv6.