Integration server HTTP listener parameters (SOAP and HTTP nodes)

Select the resources and properties that are associated with the HTTPInput, HTTPReply, SOAPInput, SOAPReply, and SOAPAsyncResponse nodes that you want to change.

To change these properties, you must specify the integration node name and -e followed by the name of a single integration server, and -o to specify the integration server object. If you specify -o integrationServerName, you can omit -e to change a property that applies to all integration servers on the specified integration node.

Because you define all of these properties at the integration server level, they apply to all HTTPInput, HTTPReply, SOAPInput, SOAPReply, and SOAPAsyncResponse nodes that you deploy to the specified integration server.

By default, the HTTP nodes that you deploy to the integration node all use the single integration node listener. If you prefer, you can change the configuration of the integration node so that all integration servers use the embedded listeners in the integration servers. You can also use the integration node listener for some integration servers, and the embedded listener in other integration servers. For more information about these options, see HTTP listeners.

By default, the SOAP nodes that you deploy to an integration server all use the embedded listener. You can change the configuration of some or all of your integration servers so that they use the integration node listener. For more information about these options, see HTTP listeners.

If you want HTTP or SOAP nodes to use the integration node listener, see Integration node HTTP listener parameters for more information about setting this configuration.

You must restart the integration server for all changes to be implemented.

Choose the ObjectName from the following options:

  • ExecutionGroup for controlling common properties
  • HTTPConnector for controlling HTTP communication.
  • HTTPSConnector for controlling HTTPS communication.

The following combinations are valid:

-o ExecutionGroup

The following properties and values are valid:
-n httpNodesUseEmbeddedListener
Set the value to false, to make all HTTPInput and HTTPReply nodes use the integration node HTTP listener, if this listener is enabled. Set the value to true to make all HTTPInput and HTTPReply nodes that are deployed to the specified integration server use the embedded integration server listener.

If you disabled the integration node HTTP listener, all HTTPInput and HTTPReply nodes use the embedded listener regardless of the value of this property.

  • Value type - Boolean
  • Initial value - false
-n soapNodesUseEmbeddedListener
Set the value to true to make all SOAPInput, SOAPReply, and SOAPAsyncResponse nodes use the embedded HTTP listener. Set the value to false to make all SOAPInput SOAPReply, and SOAPAsyncResponse nodes that are deployed to the specified integration server use the integration node listener, if this listener is enabled.

If you disabled the integration node HTTP listener, all SOAPInput, SOAPReply, and SOAPAsyncResponse nodes use the embedded listener, regardless of the value of this property.

  • Value type - Boolean
  • Initial value - true

-o HTTPConnector

The following properties and values are valid for HTTPConnector and HTTPSConnector:
-n address
If your server has more than one IP address, set the value to the IP address that is used for listening on port 7080. If this property is not set, port 7080 is used on all IP addresses associated with the server. A maximum of one address can be specified.
  • Value type - string
  • Initial value - null
-n acceptCount
Set the value to the maximum number of incoming connection requests that can be queued. Requests that are received when this limit is reached are rejected.
  • Value type - integer
  • Initial value - 100
-n compressableMimeTypes
Set the value to a list of MIME types that are applicable for HTTP compression. Other MIME types are not compressed.
  • Value type - comma-separated list
  • Initial value - text/html,text/xml,text/plain
-n compression
Set the value to off to disable compression, on to compress text data, force to compress all data, or the minimum size (in bytes) of data that must be received, before the output is compressed. If compression is enabled and the content-length is not known, all the output is compressed.
  • Value type - string
  • Initial value - off
    Note: For the webadmin component, compression is turned on by default for new integration nodes.
-n connectionLinger
Set the value to the number of seconds for which the sockets (used by the HTTPConnector) must remain active after a shutdown is initiated.
  • Value type - integer
  • Initial value - JVM default
-n connectionTimeout
Set the value to the number of milliseconds the HTTPConnector must wait for a request to be received after it accepts a connection. Set the value to -1 to specify no timeout.
  • Value type - integer
  • Initial value - 60000

The value of this property also controls the maximum duration that the listener permits between subsequent requests on the same connection before closing the connection.

-n maxHttpHeaderSize
Set the value to the maximum size (in bytes) that the HTTPListener accepts for an HTTP header.
  • Value type - integer
  • Initial value - 8192 (8 kilobytes)
-n maxKeepAliveRequests
Set the value to the maximum number of requests that can use a persistent connection. Set the value to 1 to disable keep-alive requests and force the creation of a new connection for each request. The default value is 0, which allows unlimited requests.
  • Value type - integer
  • Initial value - 0

    Versions of IBM® Integration Bus before Version 10.0 set an initial value of 100.

-n maxThreads
Set the value to the maximum number of threads that can be created by the HTTPConnector.
  • Value type - integer
  • Initial value - 200
-n minSpareThreads
Set the value to the minimum number of threads that must be active.
  • Value type - integer
  • Initial value - 10
-n noCompressionUserAgents
Set the value to a regular expression that, when matched with the user-agent header, disables compression.
  • Value type - string
  • Initial value - null
-n relaxedPathChars
Set the value to a string of special characters that are not to be percent encoded in URI paths. You can specify one or more, in any combination, of the following special characters:
  • Single quotation mark '''
  • Quotation mark '"'
  • Less than '<'
  • Greater than '>'
  • Square brackets '[' and ']'
  • Curly brackets '{' and '}'
  • Caret '^'
  • Backslash '\'
  • Vertical bar '|'
If you do not specify such characters are not to be percent encoded by using this parameter but include them in the URI path, the listener will reject the request with the HTTP code 400 BAD REQUEST.

Any other characters present in the value of relaxedPathChars are ignored.

  • Value type - string
  • Initial value - null
-n relaxedQueryChars
Set the value to a string of special characters that are not to be percent encoded in URI query strings. You can specify one or more, in any combination, of the following special characters:
  • Single quotation mark '''
  • Quotation mark '"'
  • Less than '<'
  • Greater than '>'
  • Square brackets '[' and ']'
  • Curly brackets '{' and '}'
  • Caret '^'
  • Backslash '\'
  • Vertical bar '|'
If you do not specify such characters are not to be percent encoded by using this parameter but include them in the query string, the listener will reject the request with the HTTP code 400 BAD REQUEST.

Any other characters present in the value of relaxedQueryChars are ignored.

  • Value type - string
  • Initial value - null
-n restrictedUserAgents
Set the value to a regular expression that, when matched with the user-agent header, disables keep-alive.
  • Value type - string
  • Initial value - null
-n serverName
Set the value that is set in the "Server" header for all HTTP responses sent by this server.
  • Value type - string
  • Initial value - Apache-Coyote/1.1
-n socketBuffer
Set the value to the size (in bytes) of the buffer that must be used for socket output buffering. Set the value to -1 to disable the use of a buffer.
  • Value type - integer
  • Initial value - 9000 (9 kilobytes)
-n tcpNoDelay
Set the value to true, to send small packets immediately.
  • Value type - Boolean
  • Initial value - true

    Versions of IBM Integration Bus before Version 10.0 set an initial value of false.

-n enableLookups
Set the value to true to use DNS lookups to return the host name of the remote client. Set the value to false to return the IP address instead.
  • Value type - Boolean
  • Initial value - false
-n corsEnabled
Set the value to true to make the connector respond to valid HTTP Cross-Origin Resource Sharing (CORS) requests from a web browser.

Set the value to false to disable all CORS processing.

  • Value type - boolean
  • Initial value - false
-n corsAllowOrigins
Use this value to configure the list of allowed origins for inbound cross-origin requests. An origin is the scheme, host, and port of the URI from which the cross-origin request was initiated. For example, if the cross-origin request was initiated from a web page that is hosted at http://example.com:7800/api/customers, the origin of the cross-origin request is http://example.com:7800

The cross-origin request that is made by the web browser automatically includes the origin as the value of the origin header.

Set the value to asterisk (*) to permit all cross-origin requests, otherwise, set the value to a comma-separated list of permitted origins for cross-origin access. For example: http://www.example.com,https://www.example.com:7843,http://othersite.net:7800

  • Value type - string
  • Initial value - *
-n corsAllowCredentials
Set the value to true to permit web browsers to pass credential information (HTTP Cookies and HTTP Authentication) over inbound cross-origin requests.

If set to true, an Access-Control-Allow-Credentials header is added to the response with the value true.

Set the value to false to stop web browsers from passing credential information over inbound cross-origin requests.

  • Value type - boolean
  • Initial value - false
-n corsExposeHeaders
Use this value to permit web pages that are running within a web browser to see the value of the specified headers that are returned in the response to a cross-origin request. The following headers are always permitted, regardless of the setting for this value: Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, and Pragma.

To permit a web page that is running in a web browser to see other headers in the response, set the value to a comma-separated list of header names. For example, X-Header1,X-Header2,X-Header3

If this value is set to a non-empty list and the inbound cross-origin request is permitted, an Access-Control-Expose-Headers header is added to the response with the value of this property.

If this value is set to an empty list, no Access-Control-Expose-Headers header is added to the response.

  • Value type - string
  • Initial value - Content-Type
-n corsMaxAge
Use this value to permit web browsers to cache the response to a preflight cross-origin request. If this value is set to 0 or a positive integer and the inbound cross-origin request is permitted, an Access-Control-Max-Age header is added to the response that has the value of this property.

The value specifies the maximum time in seconds that the web browser can cache the response to a preflight cross-origin request. A value of 0 stops the web browser from caching the response to a preflight cross-origin request.

If this value is set to -1, an Access-Control-Max-Age header is not added to the response. If the header is not present, depending on the web browser, the web browser might cache the response to a preflight cross-origin request.

  • Value type - integer
  • Initial value - -1
-n corsAllowMethods
Use this value to control the HTTP methods that the web browser is permitted to use when it is accessing HTTP services that are hosted by this connector. This value is used only when a preflight cross-origin request is received.

A preflight cross-origin request includes the HTTP method of the actual request as the value of the Access-Control-Request-Method header. To permit a preflight cross-origin request, the value of that header must be a case-sensitive match for one of the values that are listed in this property.

Set this property to a comma-separated list of permitted HTTP methods.

  • Value type - string
  • Initial value - GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS
-n corsAllowHeaders
Use this value to control which HTTP headers a web browser is permitted to pass to HTTP services that are hosted by this connector. This value is used only when a preflight cross-origin request is received.

A preflight cross-origin request can include a list of HTTP headers that are used in the actual request as the value of the Access-Control-Request-Headers header.

To permit a preflight cross-origin request, all values in that header must be a case-insensitive match for one of the values that are listed in this property. Set this property to a comma-separated list of permitted HTTP headers.

  • Value type - string
  • Initial value - Content-Type
-n maxPostSize
Set the value to the maximum POST size (in bytes) that can be processed by the integration server embedded listener.
  • Value type - integer
  • Initial value - -1 (no limit)
-n explicitlySetPortNumber
Set the value to the TCP/IP port number on which the Connector creates a server socket and awaits incoming connections.

Setting this value disconnects the automatic port-finding capability of the connector; this port is the only one allowed, and the connector fails to start if another program has already used this port.

  • Value type - integer
  • Initial value - 7800-7842
  • Other valid values - any integer in the range 0-65536.

You must use the explicitlySetPortNumber attribute, because the port attribute no longer works.

When you set the value to zero, the system enables the automatic port-finding capability again, starting with the last used port, which was saved by the integration server. You can change the default port that is used when port-scanning starts by explicitly setting a value in the range 7800-7842, then specifying the port number as zero.

The initial value for HTTPS is 7843 within the range 7843-7884.

-n autoRespondHTTPHEADRequests

Use this value to specify whether the connector handles HEAD requests for HTTP traffic in the same way that it does for SOAP traffic. Set the value to true to make the connector return an HTTP 200 OK response if the request is for a URI associated with a message flow.

Set the value to false to invoke the message flow if the request is for a URI associated with a message flow. The flow receives the request like a new message, and must be able to handle a HEAD request for proper handling.
Note: If the request is not for a URI associated with a message flow, the connector returns an HTTP 404 Not Found response.
  • Value type - boolean
  • Initial value - false
-n integratedWindowsAuthentication
Set the value to NTLM to use the NTLM protocol (Windows only), Negotiate to use the Negotiate process (SPNEGO) to select between NTLM (on Windows) and Kerberos protocols, or Negotiate:Kerberos to negotiate only the use of the Kerberos protocol. Multiple values can be specified, separated by a semicolon or a space, and are not case-sensitive. The order that the values are specified in, is the order in which they are returned to the client in the HTTP response. To disable Integrated Windows Authentication, set this property to a blank string.
  • Value type - string
  • Initial value - null
-n corsEnabled
Set the value to true to make the connector respond to valid HTTP Cross-Origin Resource Sharing (CORS) requests from a web browser.

Set the value to false to disable all CORS processing.

  • Value type - boolean
  • Initial value - false
-n corsAllowOrigins
Use this value to configure the list of allowed origins for inbound cross-origin requests. An origin is the scheme, host, and port of the URI from which the cross-origin request was initiated. For example, if the cross-origin request was initiated from a web page that is hosted at http://example.com:7800/api/customers, the origin of the cross-origin request is http://example.com:7800

The cross-origin request that is made by the web browser automatically includes the origin as the value of the origin header.

Set the value to asterisk (*) to permit all cross-origin requests, otherwise, set the value to a comma-separated list of permitted origins for cross-origin access. For example: http://www.example.com,https://www.example.com:7843,http://othersite.net:7800

  • Value type - string
  • Initial value - *
-n corsAllowCredentials
Set the value to true to permit web browsers to pass credential information (HTTP Cookies and HTTP Authentication) over inbound cross-origin requests.

If set to true, an Access-Control-Allow-Credentials header is added to the response with the value true.

Set the value to false to stop web browsers from passing credential information over inbound cross-origin requests.

  • Value type - boolean
  • Initial value - false
-n corsExposeHeaders
Use this value to permit web pages that are running within a web browser to see the value of the specified headers that are returned in the response to a cross-origin request. The following headers are always permitted, regardless of the setting for this value: Cache-Control, Content-Language, Content-Type, Expires, Last-Modified, and Pragma.

To permit a web page that is running in a web browser to see other headers in the response, set the value to a comma-separated list of header names. For example, X-Header1,X-Header2,X-Header3

If this value is set to a non-empty list and the inbound cross-origin request is permitted, an Access-Control-Expose-Headers header is added to the response with the value of this property.

If this value is set to an empty list, no Access-Control-Expose-Headers header is added to the response.

  • Value type - string
  • Initial value - Content-Type
-n corsMaxAge
Use this value to permit web browsers to cache the response to a preflight cross-origin request. If this value is set to 0 or a positive integer and the inbound cross-origin request is permitted, an Access-Control-Max-Age header is added to the response that has the value of this property.

The value specifies the maximum time in seconds that the web browser can cache the response to a preflight cross-origin request. A value of 0 stops the web browser from caching the response to a preflight cross-origin request.

If this value is set to -1, an Access-Control-Max-Age header is not added to the response. If the header is not present, depending on the web browser, the web browser might cache the response to a preflight cross-origin request.

  • Value type - integer
  • Initial value - -1
-n corsAllowMethods
Use this value to control the HTTP methods that the web browser is permitted to use when it is accessing HTTP services that are hosted by this connector. This value is used only when a preflight cross-origin request is received.

A preflight cross-origin request includes the HTTP method of the actual request as the value of the Access-Control-Request-Method header. To permit a preflight cross-origin request, the value of that header must be a case-sensitive match for one of the values that are listed in this property.

Set this property to a comma-separated list of permitted HTTP methods.

  • Value type - string
  • Initial value - GET,HEAD,POST,PUT,PATCH,DELETE,OPTIONS
-n corsAllowHeaders
Use this value to control which HTTP headers a web browser is permitted to pass to HTTP services that are hosted by this connector. This value is used only when a preflight cross-origin request is received.

A preflight cross-origin request can include a list of HTTP headers that are used in the actual request as the value of the Access-Control-Request-Headers header.

To permit a preflight cross-origin request, all values in that header must be a case-insensitive match for one of the values that are listed in this property. Set this property to a comma-separated list of permitted HTTP headers.

  • Value type - string
  • Initial value - Content-Type

-o HTTPSConnector

The properties that are listed for the HTTPConnector are also valid for the HTTPSConnector. The following additional properties and values are valid for the HTTPSConnector:

The following additional properties and values are valid:
Tip: The valid values for keystoreType, sslProtocol, sslSessionTimeout, and ciphers are JSSE-implementation-specific. These values are in the JSSE provider documentation. For a list of the platforms that use IBM Java™, see Appendix A of the IBM JSSE2 Guide at IBM JSSE2 Guide.
-n algorithm
Set the value to the certificate-encoding algorithm to use.
  • Value type - string
  • Initial value -
    • HP-UX platformSolaris platformSunX509 on Solaris and HP-UX
    • AIX platformLinux platformWindows platformz/OS platformIbmX509 on other systems (AIX®, Linux®, Windows, z/OS®)
-n clientAuth
Set the value to true if a valid SSL certificate must be received from the client before a connection can be accepted.
  • Value type - Boolean
  • Initial value - false
-n keystoreFile
Set the value to the path and file name of the keystore file where the server certificate is stored.
  • Value type - string
  • Initial value - platform default
-n keystorePass
Set the value to the password that is used to access the server certificate in the keystore file. The value can either be a plaintext password or, if the value is prefixed with "brokerKeystore::", the password is the named value that is configured by the mqsisetdbparms command.
  • Value type - string
  • Initial value - changeit
-n keystoreType
Set the value to the type of keystore file used.
  • Value type - string
  • Initial value - JKS
-n truststoreFile
Set the value to the path and file name of the truststore file.
  • Value type - string
  • Initial value - platform default
-n truststorePass
Set the value to the password used to access the truststore file. The value can either be a plaintext password or, if the value is prefixed with "brokerTruststore::", the password is the named value that is configured by the mqsisetdbparms command.
  • Value type - string
  • Initial value - changeit
-n truststoreType
Set the value to the type of truststore file used.
  • Value type - string
  • Initial value - JKS
-n sslProtocol
Set the value to the version of the SSL protocol to use.
  • Value type - string
  • Initial value - TLS

Valid values are: SSL, SSLv3, TLS, TLSv1, TLSv1.1, TLSv1.2, SSL_TLS, and SSL_TLSv2

From Integration Bus V9.0.0.3 onwards, SSLv3 is disabled due to the Poodle vulnerability. Therefore TLS is set as the default protocol. In versions of Integration Bus earlier than V9.0.0.3 the default protocol is still SSLv3.
-n ciphers
Set the value to a list of the encryption ciphers that can be used. If no value is set, any available cipher is used. The client sends a list of ciphers in priority order. The server selects the first acceptable cipher in the list. If none of the ciphers in the list are suitable, the server returns a handshake failure alert and closes the connection.
  • Value type - comma-separated list
  • Initial value - null
-n keyAlias
Set the value to the alias that is given to the server certificate in the keystore. By default, the first key in the keystore is used.
  • Value type - string
  • Initial value - null
-n keypass
Set the value to the password that is used to access the server certificate in the keystore file. The value can either be a plaintext password or, if the value is prefixed with "brokerKeystore::keypass", the password is the named value that is configured by the mqsisetdbparms command.
  • Value type - string
  • Initial value - changeit
-n sessionCacheSize
Set the value to the maximum number of sessions that you allow in the SSL Session Cache. These cached sessions are available for SSL session renegotiation.
  • Value type - integer
  • Initial value - 100
-n maxSavePostSize
Set the value to the maximum size in bytes that can be buffered during FORM or CLIENT-CERT authentication.
  • Value type - integer
  • Initial value - 2097152 (2MB)
-n preserveHTTPMethod

Set the value to true to ensure that requests with a HTTP method of HEAD are passed to the message flow as HEAD requests. The flow must be able to process this type of request. Set the value to false to change the HTTP method for any HEAD requests to GET when passing the message to the flow. This property has no effect if autoRespondHTTPHEADRequests is set to true.

  • Value type - Boolean
  • Initial value - false
-n autoRespondHTTPHEADRequests

Set the value to true to ensure that the connector returns an HTTP 200 OK response if the request is for a URI that is associated with a message flow. Set the value to false to invoke the message flow if the request is for a URI that is associated with a message flow. If the request is not for a URI that is associated with a message flow, the connector returns an HTTP 404 Not Found response.

  • Value type - Boolean
  • Initial value - false
sslSessionTimeout
Set the value to the time (in seconds) allowed for an SSL session to be completed. The value is set on the SSLSessionContext for SSLSessions created by the HTTPConnector.
  • Value type - integer
  • Initial value - 86400 (24 hours)
  • Other valid values - any positive integer, 0 means no timeout

See the mqsichangeproperties command for examples of how to change parameters.