MQIPT route properties

The mqipt.conf configuration file can contain properties for individual routes.

The [route] section of the mqipt.conf configuration file can contain the following properties:

Active

The route accepts incoming connections only if the value of Active is set to true. This means that we can temporarily shut off access to the destination, by setting this value to false, without having to delete the [route] section from the configuration file. If we change this property to false, the route is stopped when a refresh command is issued. All connections to the route are stopped.

ClientAccess

The route allows incoming client channel connections only if the value of ClientAccess is set to true. Note that potentially we can configure MQIPT to accept client requests only, queue manager requests only, or both types of request. Use this property in conjunction with the QMgrAccess property. If we change this property to false, the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

Destination

The host name (or dotted decimal IP address) of the queue manager, or subsequent MQIPT instance, to which this route is to connect. Each [route] section must contain an explicit Destination value, but several [route] sections can refer to the same destination. If a change to this property affects a route, the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped. When using the SocksProxyHost property the Destination property must use the dotted decimal IPv4 address format.

DestinationPort

The port on the destination host to which this route is to connect. Each [route] section must contain an explicit DestinationPort value, but several routes can refer to the same combination of Destination and DestinationPortvalues. If a change to this property affects a route, the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

HTTP

Set HTTP to true for routes responsible for making outbound HTTP tunneling requests. The Destination property for the route must be the host name of another MQIPT when HTTP it set to true. Set HTTP to false for routes connected to IBM MQ queue managers. If we change this property, the route is stopped. At least one of the HTTPProxy or HTTPServer properties must also be specified when HTTP is set to true. This property cannot be used in conjunction with the SocksClient property.

HTTPProxy

The host name (or dotted decimal IP address) of the HTTP proxy used by all connections for this route. A CONNECT request is issued to the HTTP proxy, instead of the POST request that is normally used when no HTTP proxy is configured. If we change this property (and HTTP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

HTTPProxyPort

The port address to use on the HTTP proxy. The default value is 8080. If we change this property (and HTTP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

HTTPServer

The host name (or dotted decimal IP address) of the HTTP server used by all connections for this route. This is usually the host name of another MQIPT.

If HTTPProxy is not specified, MQIPT connects to the host specified in HTTPServer, and issues HTTP POST requests to the host specified in the route Destination property. If HTTPProxy is specified, MQIPT connects to the host specified in HTTPProxy instead.

If HTTPProxy is specified, the default value is the route Destination.

If we change this property (and HTTP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

HTTPS

Set HTTPS to true to make HTTPS requests. The HTTP and SSLClient properties must also be enabled, and the client key ring configured using the SSLClientKeyRing or SSLClientKeyRingUseCryptoHardware property, as for SSL/TLS operation. If we change the HTTPS property (and HTTP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

HTTPServerPort

The port address to use on the HTTP server. The default value is 8080, unless HTTPProxy is specified, in which case the default value is the route DestinationPort.

If we change this property (and HTTP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

IdleTimeout

The time, in minutes, after which an idle connection is closed. Note that queue manager to queue manager channels also have the DISCINT property. If you set the IdleTimeout parameter, take note of DISCINT. If IdleTimeout is set to 0, there is no idle timeout. Changes to this property take effect only when the route is restarted.

IgnoreExpiredCRLs

Set IgnoreExpiredCRLs to true to ignore an expired CRL. The default value is false. Note that if you set IgnoreExpiredCRLs to true, a revoked certificate could be used to make an SSL/TLS connection.

LDAP

Set LDAP to true to enable use of an LDAP server when using SSL/TLS connections. MQIPT will use the LDAP server to retrieve CRLs and ARLs. The SSLClient property or SSLServer property must also be set to true for this property to take effect.

LDAPCacheTimeout

The expiry time, in hours, of the temporary cache in which a CRL retrieved from an LDAP server, is stored. After this time, the entire CRL cache is emptied. For example, specifying a value of 1 hour means that the cache is emptied once per hour. The default value is 24. If you specify a timeout value of 0, entries in the cache will not expire until the route is restarted. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

LDAPIgnoreErrors

Set LDAPIgnoreErrors to true to ignore any connection or timeout errors when performing an LDAP search. If MQIPT cannot perform a successful search, it will not allow the client connection to complete, unless this property has been enabled. A successful search means that a CRL has been retrieved or there are no CRLs available for the specified CA. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped. Note: If you enable this property, a revoked certificate could be used to make an SSL/TLS connection.

LDAPServer1

The host name or IP address of the main LDAP server. This property must be set if LDAP has been set to true. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

LDAPServer1Port

The listening port number of the main LDAP server. The default value is 389. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

LDAPServer1Userid

The user ID needed to access the main LDAP server. This property must be set if authorization to access the main LDAP server is required. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

LDAPServer1Password

The password needed to access the main LDAP server. This property must be set if LDAPServer1Userid has been set to true. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

The value can be either a password that has been encrypted using the mqiptPW command, or a plain text password. Plain text passwords can only contain alphanumeric characters. You are strongly encouraged to encrypt passwords that are stored in the MQIPT configuration. For more information on encrypting passwords in the MQIPT configuration, see Encrypting stored passwords.

LDAPServer1Timeout

The time, in seconds, that MQIPT waits for a response from the main LDAP server. The default value is 0, which means the connection will not time out. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

LDAPServer2

The host name or IP address of the backup LDAP server. This property is optional. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

LDAPServer2Port

The listening port number of the backup LDAP server. The default value is 389. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

LDAPServer2Userid

The userid needed to access the backup LDAP server. This property must be set if authorization to access the backup LDAP server is required. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

LDAPServer2Password

The password needed to access the backup LDAP server. This property must be set if LDAPServer2 has been set to true. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

The value can be either a password that has been encrypted using the mqiptPW command, or a plain text password. Plain text passwords can only contain alphanumeric characters. You are strongly encouraged to encrypt passwords that are stored in the MQIPT configuration. For more information on encrypting passwords in the MQIPT configuration, see Encrypting stored passwords.

LDAPServer2Timeout

The time, in seconds, that MQIPT will wait for a response from the backup LDAP server. The default value is 0, which means the connection will not time out. If we change this property (and LDAP is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

ListenerAddress

Use this property if the MQIPT system has multiple IP addresses and we need to bind the route listener port to a specific address. This is useful for restricting inbound connections to those from a particular network interface. The value of this property should be an IP address belonging to one of the network interfaces on the system where MQIPT is running. The default is to accept connections from all network interfaces.

ListenerPort

The port number on which the route should listen for incoming requests. Each [route] section must contain an explicit ListenerPort value The ListenerPort values set in each section must be distinct. Any valid port number can be used, including ports 80 and 443, provided that the ports chosen are not already in use by any other TCP/IP listener running on the same host.

LocalAddress

The IP address to bind all connections to for this route on this computer. The chosen address must be an IP address that is associated with one of the network interfaces on the computer on which MQIPT is running. If we change this property, the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

MaxConnectionThreads

The maximum number of connection threads, and thus the maximum number of concurrent connections, that can be handled by this route. If this limit is reached, the MaxConnectionThreads value also indicates the number of connections that are queued when all the threads are in use. Beyond that number, subsequent connection requests are refused. The minimum allowed value is the greater of 1 and the value of MinConnectionThreads. If a change to this property affects a route, the new value is used when the refresh command is issued. All connections use the new value immediately. The route is not stopped.

MinConnectionThreads

The number of connection threads allocated to handle incoming connections on a route when the route is started. The number of threads allocated does not drop below this value during the time the route is active. The minimum allowed value is the lesser of 0 and the value of MaxConnectionThreads. Changes to this property take effect only when the route is restarted.

Name

A name to help identify the route. This property is optional. The value is shown in console messages and tracing information. Changes to this property take effect only when the route is restarted.

OutgoingPort

The starting port number used by outgoing connections. The range of port numbers match the MaxConnectionThread value for this route. The default value of 0 uses a system-defined port number. If we change this property, the route is stopped and restarted when a refresh command is issued. All connections to this route are stopped. When HTTP is used, each channel connection requires two outgoing ports. For more information, see Port number control.

QMgrAccess

Set QMgrAccess to true to allow incoming queue manager channel connections (for example sender channels). If we change this property to false, the route is stopped when a refresh command is issued. All connections to this route are stopped.

RouteRestart

Set RouteRestart to false to stop the route from restarting when other route properties have been changed and a refresh command has been issued. The default value for this property is true.

SecurityExit

Set SecurityExit to true to enable a user-defined security exit. The default value for this property is false.

SecurityExitName

The class name of the user-defined security exit. This property must be set if SecurityExit has been set to true. If we change this property (and SecurityExit is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to this route are stopped.

SecurityExitPath

The fully-qualified path name containing the user-defined security exit. If this property has not been set, then it will default to the exits subdirectory. This property can also define the name of a Java archive (JAR) file containing the user-defined security exit. If we change this property (and SecurityExit is set to true), the route is stopped and restarted when a refresh command is issued. All connections to this route are stopped.

SecurityExitTimeout

The timeout value (in seconds) used by MQIPT to determine how long to wait for a response when validating a connection request. The default value is 30. If we change this property (and SecurityExit is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SocksClient

Set SocksClient to true to make the route act as a SOCKS client and define all connections through the SOCKS proxy with the SocksProxyHost and SocksProxyPort properties. If we change this property, the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped. This property cannot be used with:

• HTTP
• SocksServer
• SSLClient
• SSLProxyMode

SocksProxyHost

The host name (or dotted decimal IPv4 address) of the SOCKS proxy that all connections for this route use. If we change this property (and SocksClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to this route are stopped. When using the SocksProxyHost property the Destination property must use the dotted decimal format.

SocksProxyPort

The port number to use on a SOCKS proxy. The default value is 1080. If we change this property (and SocksClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SocksServer

Set SocksServer to true to make the route act as a SOCKS proxy and accept SOCKS client connections. If we change this property, the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped. This property cannot be used with the following properties:

• SocksClient
• SSLProxyMode
• SSLServer

SSLClient

Set SSLClient to true to make the route act as an SSL/TLS client and make outgoing SSL/TLS connections. Setting SSLClient to true implies that the destination is either another instance of MQIPT acting as an SSL/TLS server, or an HTTP proxy/server.

If you set SSLClient to true, we must specify a SSL/TLS client key ring using the SSLClientKeyRing or SSLClientCAKeyRing property, or configure MQIPT to use cryptographic hardware by setting the SSLClientKeyRingUseCryptoHardware or SSLClientCAKeyRingUseCryptoHardware property.

If we change SSLClient, the route is stopped, and restarted when a refresh command is issued. All connections to this route are stopped.

This property cannot be used in conjunction with the following property:

• SSLProxyMode

SSLClientCAKeyRing

The fully-qualified file name of the key ring file containing CA certificates, used to authenticate certificates from the SSL/TLS server. On Windows platforms, we must use a double backslash (\\) as the file separator. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientCAKeyRingPW

The password to open the SSL/TLS client CA key ring file specified with the SSLClientCAKeyRing property, or to connect to the cryptographic hardware key store if the SSLClientCAKeyRingUseCryptoHardware property is set to true.

The value can be either a password that has been encrypted using the mqiptPW command, or the fully-qualified file name of the file containing an encrypted password. If you specify a file name on Windows platforms, we must use a double backslash (\\) as the file separator. You are encouraged to migrate any key ring passwords currently stored in a file to use the latest and most secure protection method, by re-encrypting the passwords using the mqiptPW utility. For more information on encrypting passwords in the MQIPT configuration, see Encrypting stored passwords.

If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientCAKeyRingUseCryptoHardware

Specifies whether cryptographic hardware that supports the PKCS #11 interface is used as the key store for CA certificates used to authenticate server certificates from the SSL/TLS server, when MQIPT is acting as a SSL/TLS client. If this property is set to true, SSLClientCAKeyRing cannot be set on the same route.

If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

Use of cryptographic hardware with MQIPT is an IBM MQ Advanced capability. To use this capability, the local queue manager that is connected using the MQIPT route is also required to have IBM MQ Advanced, IBM MQ Appliance or IBM MQ Advanced for z/OS VUE entitlement. The route will not start when this property is set to true unless the EnableAdvancedCapabilities global property is set to confirm that IBM MQ Advanced capabilities can be used.

SSLClientCipherSuites

The name of the SSL/TLS CipherSuite to use on the SSL/TLS client side. This can be one or more of the supported CipherSuites. If you leave this property blank, the SSL/TLS client uses the supported CipherSuites from the key ring. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to this route are stopped.

SSLClientConnectTimeout

The time (in seconds) that an SSL/TLS client waits for an SSL/TLS connection to be accepted. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_C

Use this property to accept certificates received from the SSL/TLS server that match this country name. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, all country names are accepted. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_CN

Use this property to accept certificates received from the SSL/TLS server that match this common name. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, all common names are accepted. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_DC

Use this property to accept certificates received from the SSL/TLS server that match this domain component. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. We can specify multiple DCs by separating them with commas. Each DC represents an element in a domain name, for example the domain name example.ibm.com is represented as example,ibm,com using commas to separate the multiple values. If we do not specify this property, all domain components are accepted. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_DNQ

Use this property to accept certificates received from the SSL/TLS server that match this domain qualifier. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, all domain qualifiers are accepted. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_L

Use this property to accept certificates received from the SSL/TLS server that match this location. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, you imply "all locations". If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_O

Use this property to accept certificates received from the SSL/TLS server that match this organization. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted from all organizations. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_OU

Use this property to accept certificates received from the SSL/TLS server that match this Organizational Unit (OU). The name can be prefixed or suffixed with an asterisk (*) to extend its scope. We can specify multiple OUs by separating them with commas. (Match a literal comma by prefixing it with a backslash (\) character.) Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any OU name. If we change this property (and SSLClient is set to true), the route is stopped and restarted when a refresh command is issued. All connections to this route are stopped.

SSLClientDN_PC

Use this property to accept certificates received from the SSL/TLS server that match this postal code. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, all postal codes are accepted. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_ST

Use this property to accept certificates received from the SSL/TLS server that match this state. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted from servers in all states. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_Street

Use this property to accept certificates received from the SSL/TLS server that match this street name. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, all street names are accepted. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_T

Use this property to accept certificates received from the SSL/TLS server that match this title. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, all titles are accepted. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientDN_UID

Use this property to accept certificates received from the SSL/TLS server that match this user ID. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, all user IDs are accepted. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientExit

Use this property to enable or disable the use of an exit when the route is acting as an SSL/TLS client. This allows you to define exit details in the configuration file without them actually being used.

SSLClientKeyRing

The fully-qualified file name of the key ring file containing the client certificate. On Windows platforms, we must use a double backslash (\\) as the file separator. If we change SSLClientKeyRing (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientKeyRingPW

The password to open the SSL/TLS client key ring file specified with the SSLClientKeyRing property, or to connect to the cryptographic hardware key store if the SSLClientKeyRingUseCryptoHardware property is set to true.

The value can be either a password that has been encrypted using the mqiptPW command, or the fully-qualified file name of the file containing an encrypted password. If you specify a file name on Windows platforms, we must use a double backslash (\\) as the file separator. You are encouraged to migrate any key ring passwords currently stored in a file to use the latest and most secure protection method, by re-encrypting the passwords using the mqiptPW utility. For more information on encrypting passwords in the MQIPT configuration, see Encrypting stored passwords.

If we change SSLClientKeyRingPW (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientKeyRingUseCryptoHardware

Specifies whether cryptographic hardware that supports the PKCS #11 interface is used as the key store containing the client certificate, when MQIPT is acting as a SSL/TLS client. If this property is set to true, SSLClientKeyRing cannot be set on the same route.

If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

Use of cryptographic hardware with MQIPT is an IBM MQ Advanced capability. To use this capability, the local queue manager that is connected using the MQIPT route is also required to have IBM MQ Advanced, IBM MQ Appliance or IBM MQ Advanced for z/OS VUE entitlement. The route will not start when this property is set to true unless the EnableAdvancedCapabilities global property is set to confirm that IBM MQ Advanced capabilities can be used.

SSLClientProtocols

Used to restrict the set of enabled secure socket protocols that are used to make outbound connections to the destination for a route when SSLClient is set to true. We can specify multiple values by separating them with commas. If you do not specify this property, the only protocol enabled by default is TLS 1.2. To enable protocols other than TLS 1.2, we must specify the protocols to enable in this property, and also add support for the protocol in the Java runtime environment by following the procedure in Enable deprecated protocols and CipherSuites. We can specify one or more of the following values.

Value	Protocol
SSLv3	SSL 3.0
TLSv1	TLS 1.0
TLSv1.1	TLS 1.1
TLSv1.2	TLS 1.2

Use the entry listed in the Value column in the route property. The corresponding entry in the Protocol column is for information only.

SSLClientSiteDN_C

Use this property to specify a country name to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any country name. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteDN_CN

Use this property to specify a common name to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any common name. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteDN_DC

Use this property to specify a domain component name to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. We can specify multiple DCs by separating them with commas. Each DC represents an element in a domain name, for example the domain name example.ibm.com is represented as example,ibm,com using commas to separate the multiple values. If we do not specify this property, certificates are accepted with any domain component name. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteDN_DNQ

Use this property to specify a domain qualifier to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any domain qualifier. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteDN_L

Use this property to specify a Location name to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any location name. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteDN_O

Use this property to specify an Organization name to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any organization name. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteDN_OU

Use this property to specify an Organizational Unit (OU) name to select a certificate to send to the SSL/TLS server. We can specify multiple OUs by separating them with commas. (Match a literal comma by prefixing it with a backslash (\) character.) Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any OU name. If we change this property (and SSLClient is set to true), the route is stopped and restarted when a refresh command is issued. All connections to this route are stopped.

SSLClientSiteDN_PC

Use this property to specify a postal code to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any postal code. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteDN_ST

Use this property to specify a State name to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any state name. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteDN_Street

Use this property to specify a street name to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any street name. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteDN_T

Use this property to specify a title to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any title. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteDN_UID

Use this property to specify a user ID to select a certificate to send to the SSL/TLS server. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any user ID. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLClientSiteLabel

Use this property to specify a label name to select a certificate to send to the SSL/TLS server. If we do not specify this property, certificates are accepted with any label name. If we change this property (and SSLClient is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLExitData

Use this property to provide a user-defined string to be passed to the exit.

SSLExitName

Use this property to define the class name for the exit that will be called when the route is acting as an SSL/TLS client or an SSL/TLS server. The name must include any package name; for example, com.ibm.mq.ipt.exit.TestExit.

SSLExitPath

Use this property to define the location of the exit to be used to load a copy of the exit. The name must be a fully qualified name to be used to locate the class file or the name of a .jar file that contains the class file; for example, C:\mqipt\exits or C:\mqipt\exits\exits.jar.

SSLExitTimeout

Use this property to define how long MQIPT waits for the exit to complete before terminating the connection request. A value of 0 means that MQIPT waits indefinitely.

SSLPlainConnections

Use this property to specify whether SSL/TLS is mandatory for connections to the MQIPT listener port of a route configured to accept inbound SSL/TLS connections. This property is applicable to routes that have either the SSLServer or SSLProxyMode property set to true. If enabled, this property allows unencrypted connections to connect to the route listener port, which means that MQIPT can forward all IBM MQ connections to the queue manager's listener port regardless of whether the connection is encrypted. If we do not set this parameter, or set it to false, only inbound SSL/TLS connections are allowed. If we change this property, the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLProxyMode

Set this property to true to make the route accept only SSL/TLS client connection requests and to tunnel the request directly to the destination. If we change this property, the route is stopped and restarted when a refresh command is issued. All connections to this route are stopped. This property cannot be used in conjunction with the following properties:

• SocksClient
• SocksServer
• SSLClient
• SSLServer

SSLServer

Set this property to true to make the route act as an SSL/TLS server and accept incoming SSL/TLS connections. Setting SSLServer to true implies that the caller is another MQIPT acting as an SSL/TLS client, or is an IBM MQ client or queue manager with SSL/TLS enabled.

If you set SSLServer to true, we must specify a SSL/TLS server key ring using the SSLServerKeyRing property, or configure MQIPT to use cryptographic hardware by setting the SSLServerKeyRingUseCryptoHardware property.

If we change this property, the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

This property cannot be used in conjunction with the following properties:

• SocksServer
• SSLProxyMode

SSLServerCAKeyRing

The fully-qualified file name of the key ring file containing CA certificates, used to authenticate certificates from the SSL/TLS client. On Windows platforms, we must use a double backslash (\\) as the file separator. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to this route are stopped.

SSLServerCAKeyRingPW

The password to open the SSL/TLS server CA key ring file specified with the SSLServerCAKeyRing property, or to connect to the cryptographic hardware key store if the SSLServerCAKeyRingUseCryptoHardware property is set to true.

The value can be either a password that has been encrypted using the mqiptPW command, or the fully-qualified file name of the file containing an encrypted password. If you specify a file name on Windows platforms, we must use a double backslash (\\) as the file separator. You are encouraged to migrate any key ring passwords currently stored in a file to use the latest and most secure protection method, by re-encrypting the passwords using the mqiptPW utility. For more information on encrypting passwords in the MQIPT configuration, see Encrypting stored passwords.

If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerCAKeyRingUseCryptoHardware

Specifies whether cryptographic hardware that supports the PKCS #11 interface is used as the key store for the CA certificates, used to authenticate certificates from the SSL/TLS client. If this property is set to true, SSLServerCAKeyRing cannot be set on the same route.

If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

Use of cryptographic hardware with MQIPT is an IBM MQ Advanced capability. To use this capability, the local queue manager that is connected using the MQIPT route is also required to have IBM MQ Advanced, IBM MQ Appliance or IBM MQ Advanced for z/OS VUE entitlement. The route will not start when this property is set to true unless the EnableAdvancedCapabilities global property is set to confirm that IBM MQ Advanced capabilities can be used.

SSLServerAskClientAuth

Use this property to request SSL/TLS client authentication by the SSL/TLS server. The SSL/TLS client must have its own certificate to send to the SSL/TLS server. The certificate is retrieved from the key ring file. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to this route are stopped.

SSLServerCipherSuites

The name of the SSL/TLS CipherSuite to use on the SSL/TLS server side. This can be one or more of the supported CipherSuites. If you leave this blank, the SSL/TLS server uses the supported CipherSuites from the key ring. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to this route are stopped.

SSLServerDN_C

Use this property to accept certificates received from the SSL/TLS client of this country name. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any company name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerDN_CN

Use this property to accept certificates received from the SSL/TLS client of this common name. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any common name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerDN_DC

Use this property to accept certificates received from the SSL/TLS client of this domain component name. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. We can specify multiple DCs by separating them with commas. Each DC represents an element in a domain name, for example the domain name example.ibm.com is represented as example,ibm,com using commas to separate the multiple values. If we do not specify this property, certificates are accepted with any domain component name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerDN_DNQ

Use this property to accept certificates received from the SSL/TLS client of this domain qualifier. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any domain qualifier. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerDN_L

Use this property to accept certificates received from the SSL/TLS client of this location. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any location. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerDN_O

Use this property to accept certificates received from the SSL/TLS client of this organization. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any organization. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerDN_OU

Use this property to accept certificates received from the SSL/TLS client of this Organizational Unit (OU). The name can be prefixed or suffixed with an asterisk (*) to extend its scope. We can specify multiple OUs by separating them with commas. (Match a literal comma by prefixing it with a backslash (\) character.) Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any OU name. If we change this property (and SSLServer is set to true), the route is stopped and restarted when a refresh command is issued. All connections to this route are stopped.

SSLServerDN_PC

Use this property to accept certificates received from the SSL/TLS client of this postal code. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any postal code. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerDN_ST

Use this property to accept certificates received from the SSL/TLS client of this state. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any state. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerDN_Street

Use this property to accept certificates received from the SSL/TLS client of this street name. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any street name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerDN_T

Use this property to accept certificates received from the SSL/TLS client of this title. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any title. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerDN_UID

Use this property to accept certificates received from the SSL/TLS client of this user ID. The name can be prefixed or suffixed with an asterisk (*) to extend its scope. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any user ID. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerExit

Use this property to enable or disable the use of an exit when the route is acting as an SSL/TLS server. This allows you to define exit details in the configuration file without them actually being used.

SSLServerKeyRing

The fully-qualified file name of the key ring file containing the server certificate. On Windows platforms, we must use a double backslash (\\) as the file separator. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerKeyRingPW

The password to open the SSL/TLS server key ring file specified with the SSLServerKeyRing property, or to connect to the cryptographic hardware key store if the SSLServerKeyRingUseCryptoHardware property is set to true.

The value can be either a password that has been encrypted using the mqiptPW command, or the fully-qualified file name of the file containing an encrypted password. If you specify a file name on Windows platforms, we must use a double backslash (\\) as the file separator. You are encouraged to migrate any key ring passwords currently stored in a file to use the latest and most secure protection method, by re-encrypting the passwords using the mqiptPW utility. For more information on encrypting passwords in the MQIPT configuration, see Encrypting stored passwords.

We must specify SSLServerKeyRingPW if you set SSLServer to true.

If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerKeyRingUseCryptoHardware

Specifies whether cryptographic hardware that supports the PKCS #11 interface is used as the key store for the server certificate, when MQIPT is acting as a SSL/TLS server. If this property is set to true, SSLServerKeyRing cannot be set on the same route.

If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

Use of cryptographic hardware with MQIPT is an IBM MQ Advanced capability. To use this capability, the local queue manager that is connected using the MQIPT route is also required to have IBM MQ Advanced, IBM MQ Appliance or IBM MQ Advanced for z/OS VUE entitlement. The route will not start when this property is set to true unless the EnableAdvancedCapabilities global property is set to confirm that IBM MQ Advanced capabilities can be used.

SSLServerProtocols

Used to restrict the set of enabled secure socket protocols that are used to accept inbound connections to the route listener port for a route when SSLServer is set to true). We can specify multiple values by separating them with commas. If you do not specify this property, the only protocol enabled by default is TLS 1.2. To enable protocols other than TLS 1.2, we must specify the protocols to enable in this property, and also add support for the protocol in the Java runtime environment by following the procedure in Enable deprecated protocols and CipherSuites. We can specify one or more of the following values.

Value	Protocol
SSLv3	SSL 3.0
TLSv1	TLS 1.0
TLSv1.1	TLS 1.1
TLSv1.2	TLS 1.2

Use the entry listed in the Value column in the route property. The corresponding entry in the Protocol column is for information only.

SSLServerSiteDN_C

Use this property to specify a country name to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any country name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteDN_CN

Use this property to specify a Common Name to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any common name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteDN_DC

Use this property to specify a domain component name to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. We can specify multiple DCs by separating them with commas. Each DC represents an element in a domain name, for example the domain name example.ibm.com is represented as example,ibm,com using commas to separate the multiple values. If we do not specify this property, certificates are accepted with any domain component name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteDN_DNQ

Use this property to specify a domain qualifier to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any domain qualifier. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteDN_L

Use this property to specify a Location name to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any location name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteDN_O

Use this property to specify an organization name to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any organization name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteDN_OU

Use this property to specify an Organizational Unit (OU) name to select a certificate to send to the SSL/TLS client. We can specify multiple OUs by separating them with commas. (Match a literal comma by prefixing it with a backslash (\) character.) Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any OU name. If we change this property (and SSLServer is set to true), the route is stopped and restarted when a refresh command is issued. All connections to this route are stopped.

SSLServerSiteDN_PC

Use this property to specify a postal code to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any postal code. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteDN_ST

Use this property to specify a State name to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any state name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteDN_Street

Use this property to specify a street name to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any street name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteDN_T

Use this property to specify a title to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any title. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteDN_UID

Use this property to specify a user ID to select a certificate to send to the SSL/TLS client. Certificate matching is not case sensitive. If we do not specify this property, certificates are accepted with any user ID. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

SSLServerSiteLabel

Use this property to specify a label name to select a certificate to send to the SSL/TLS client. If we do not specify this property, certificates are accepted with any label name. If we change this property (and SSLServer is set to true), the route is stopped, and restarted when a refresh command is issued. All connections to the route are stopped.

StoredCredentialsFormat

Use this property to indicate whether the values of password properties use the encrypted password format supported from MQIPT Version 9.1.5. MQIPT can almost always detect whether passwords are specified in the encrypted password format. This property only needs to be set in the unlikely scenario that MQIPT cannot automatically differentiate between an encrypted password and a plain text password or a file name.

The value can be one of the following values:

encrypted

Password properties contain an encrypted password in the format that is supported from MQIPT Version 9.1.5.

compat

Password properties contain either a plain text password, or for key ring passwords, the name of the file containing an encrypted password.

TCPKeepAlive

Set this property to true to enable the sending of TCP/IP keep-alive packets periodically to prevent the connections on this route becoming idle. This reduces the chances of the MQIPT connections being severed by a firewall or router. The sending of TCP/IP keep-alive packets is controlled by operating system tuning parameters; consult your operating system documentation for further details on how to tune keep-alive. If we do not set this parameter, or set it to false, keep-alive packets are not sent.

Trace

The level of tracing required for this route. Enabling trace for one route does not enable trace for any other routes. For to trace more than one route, we must add the Trace property to the [route] section of each route to be traced. This property should be an integer in the range 0 - 5, where 0 indicates that trace is disabled, and any other value indicates that trace is enabled. The default value is 0. If the [route] section does not include a Trace property, the Trace property from the [global] section is used. For information about tracing threads that are not associated with a route, see Trace in the [global] section. If a change to this property affects a route, the new value is used when the refresh command is issued. All connections use the new value immediately. The route is not stopped.

UriName

This property can be used to change the name of the Uniform Resource Identifier of the resource when using an HTTP proxy, although the default value will suffice for most configurations:

HTTP://destination:destination_port/mqipt

If we change this property (and HTTP is set to true), the route is stopped, and restarted when a refresh command is issued.

Parent topic: IBM MQ Internet Pass-Thru configuration reference