Configuration Tool Online Help

[ Bottom of Page | Previous Page | Next Page | Table of Contents | Index ]


Gateway Protocol settings

Partial Table-of-Contents

  • Enable protocol handler
  • Bind Address
  • Port
  • Connection timeout (ms)
  • Maximum connections
  • Idle timeout (ms)
  • Ping time frequency (ms)
  • Drop working connections
  • SO_LINGER setting
  • Require Java Clients to use security classes
  • Key ring file
  • Key ring password
  • Use client authentication
  • Use only these ciphers
  • This panel contains Gateway settings specific to a particular protocol handler.

    To enable the settings for a particular protocol, click on the relevant node in the selection tree, and then select Enable protocol handler.


    Enable protocol handler

    Select this check box to enable the required protocol handler.

    When you do this CICS Transaction Gateway uses that network communications protocol handler to listen for incoming client requests.


    Bind Address

    Enter the IP address or name of the host to which the protocol handler is to be bound.

    If you enter a host name, it is resolved on startup.

    To bind the protocol to all addresses, leave the field blank.

    The default behavior is to bind all addresses.

    The IP address can be in IPv6 format; for example, 3ffe:307:8:0:260:97ff:fe40:efab.


    Port

    Enter a number in the range 1 through 65,535 to specify the number of the TCP/IP port on which the protocol handler listens for incoming client requests.

    For the statistics API protocol this specifies the number of the port for the Gateway daemon to use to handle incoming requests for the Statistics API.

    If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    The default port for TCP/IP is 2006, for SSL the default is 8050, and for the statistics API protocol the default is 2980.

    On Unix and Linux: You can override this setting with the ctgstart -port=number command.
    On Windows: You can override this setting with the ctgservice -port=number command.


    Connection timeout (ms)

    Specifies how long the protocol handler waits for a connection manager thread to become available. Enter a number in the range 0 through 65,536 to specify the value in milliseconds. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    When a new connection has been accepted, this value specifies how long the protocol handler waits for a connection manager thread to become available. If a connection manager thread does not become available within this time, the connection is refused. If this value is set to zero, a connection is refused if a connection manager thread is not immediately available.


    Maximum connections

    Specifies the maximum number of applications that can be connected at the same time to perform statistic queries. Set the value to the maximum number of connections. The default is 5.


    Idle timeout (ms)

    This setting specifies in milliseconds how long a connection is allowed to remain dormant.

    Enter a value in milliseconds, between 0 and 9,999,999. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    The idle timeout period is counted from the time when a request was last flowed down the connection. When the idle timeout has expired, the Java™ Client application is disconnected, although, if work is still in progress on behalf of the connection, it might be left connected, depending on the setting of the Drop working connections field. If the Idle timeout (ms) field is not set or is set to zero, idle connections are not disconnected.


    Ping time frequency (ms)

    This value specifies how often a ping message is sent by the Gateway to an attached client to check that client is still active.

    Enter a number in the range 0 through 65,536 to specify the value in milliseconds. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    If a reply has not been received by the time the next ping message is due to be sent, the connection is disconnected. Again, if work is still in progress on behalf of the connection it might (depending on the drop working connections value setting) be left connected. If this value is not set, or is set to zero, ping messages are not sent.


    Drop working connections

    Select this check box to specify that a connection can be disconnected, due to an idle timeout or a PING/PONG failure even if work is still in progress on behalf of this connection.

    SO_LINGER setting

    This is the delay value in seconds for closing a socket.

    Enter a number in the range 0 through 65,536 to specify the SO_LINGER setting for any socket used by this handler. If this value is not entered or is set to zero, SO_LINGER is disabled for any sockets used by this protocol handler. If you enter a value outside the permitted range, the Configuration Tool warns you. If the value entered is too low, it substitutes the minimum. If the value entered is too high, it substitutes the maximum. If a non-numeric value is present in the configuration file, it substitutes the minimum value.

    If SO_LINGER is enabled, and data transmission has not finished, a call to close the socket blocks the calling program until the data is transmitted or until the connection times out. If SO_LINGER is disabled, a call to close the socket returns without blocking the caller and TCP/IP still tries to send the data. Normally, this transfer is successful, but it cannot be guaranteed, because TCP/IP repeats the Send request for only a specified period of time.


    Require Java Clients to use security classes

    Select this check box if you want your Gateway to accept only connections that use security classes.

    When a Java Client application connects to the Gateway, it can specify a pair of security classes for use on the connection. However, by default, a Gateway also accepts connections from programs that do not specify this pair of security classes.


    Key ring file

    Enter the server key ring name. Give either the full path name or the path name of the file relative to the CICS Transaction Gateway bin directory. Use either a forward slash (/) character or double backslash (\\) characters as a separator in the path name on all operating systems.

    For example:

    c:/mykeys/jsse/keystore.jks
    c:\\mykeys\\jsse\\keystore.jks
    
    /mykeys/jsse/keystore.jks
    \\mykeys\\jsse\\keystore.jks      
    

    The server key ring consists of a valid x.509 certificate that identifies this server to connecting clients. This key ring is generated using the SSL tools supplied with this product.

    On Unix and Linux: You can override the SSL key ring path and file name with the ctgstart -keyring=keyring command.
    On Windows: You can override the SSL key ring path and file name with the ctgservice -keyring=keyring command.


    Key ring password

    CICS Transaction Gateway writes the password to the configuration file in a form that prevents an observer from easily reading it.

    Enter the password that you specified for the server key ring.

    You can override the SSL password with the ctgstart -keyring=keyring -keyringpw=keyringpw command. An error message is generated if the keyringpw parameter is used on its own without the corresponding keyring parameter in the ctgstart - command line. This error message does not affect the Gateway operation and the password is ignored.

    The following example shows a command line with parameters:

    On Unix and Linux: ctgstart -sslport=port_number -keyring=keyring -keyringpw=keyringpw

    Use client authentication

    Select this check box to enable client authentication for the CICS Transaction Gateway. The default is that client authentication is disabled.

    When client authentication is enabled, any connection attempted to the ssl: handler requires the client to present its own Client Certificate (also known as a digital ID).

    For information on how to obtain Client Certificates for the clients, see the CICS Transaction Gateway Administration book for your platform.


    Use only these ciphers

    Enter a valid cipher suite in the entry field.

    The value restricts the set of cipher suites that can be used with the SSL protocol. If you do not want to restrict the set of cipher suites used, omit this parameter. Click Add to add the cipher to the list of ciphers, below the entry field. Click Remove to remove all selected entries in the ciphers list. CICS Transaction Gateway uses cipher suites provided by the Java runtime environment for the SSL protocol. The cipher suites available to be used are dependant on the Java version. See the documentation supplied with your Java runtime environment for valid cipher suites, or proceed as follows:

    1. Remove any entries from the Use only these ciphers list.
    2. Save the configuration file.
    3. Run ctgstart.

    If the SSL protocol is correctly configured, CICS Transaction Gateway displays a list of valid ciphersuites that Java Client applications can use to connect to the CICS Transaction Gateway.

    If the Use only these ciphers list contains entries, a Java Client application can connect to the CICS Transaction Gateway only by using the cipher suites listed. If the Java Client application does not support any of the cipher suites listed, it cannot connect.

    If the list contains no entries, a Java Client application can connect using any available cipher suite.

    Use of the ciphersuites=128bitonly parameter is deprecated. If you use the Configuration Tool to open a configuration file that contains this entry, the entry is replaced by these cipher suites:

    Cipher suites entered as TLS_ are converted to SSL_ when the CICS Transaction Gateway starts. You can find the protocol used by checking the log or trace when a client connects.


    [ Top of Page | Previous Page | Next Page | Table of Contents | Index ]

    (C) Copyright IBM Corporation, 1999, 2010. All rights reserved. Legal