Start of change

Creating TCPIPSERVICE resource definitions for CICS Web support

TCPIPSERVICE resource definitions are used to define the association between ports and CICS® services, including CICS Web support. Define and install a TCPIPSERVICE resource definition for each port that you use for CICS Web support.

Each TCPIPSERVICE definition that is active in a CICS system must specify a unique port number. CICS uses the TCPIPSERVICE definition for a port to determine what CICS service should be invoked when it receives an inbound TCP/IP connection request on that port. The PROTOCOL attribute is used to identify the service. HTTP is specified for standard CICS Web support, and USER is specified for non-HTTP requests that are handled using CICS Web support. (The remaining protocols are IIOP and ECI.)

For CICS Web support, you normally need to create TCPIPSERVICE definitions for the default, or well-known, port numbers that are used for Internet services. For HTTP, the default port number is 80, and for HTTPS, the default port number is 443. You can also use non-standard port numbers.

Each TCPIPSERVICE definition can only specify one analyzer program, and one transaction definition for the Web attach task. If you need to use more than one of these items, you will need to use different TCPIPSERVICE definitions, and therefore different ports.

CICS provides sample TCPIPSERVICE definitions for CICS Web support in group DFH$SOT:
HTTPNSSL
CICS Web TCPIPSERVICE with no SSL support
HTTPSSL
CICS Web TCPIPSERVICE with SSL support
Important: The TCPIPSERVICE resource definition is the place where you specify the security measures that are applied for each port. You can choose whether or not to use SSL, and if you do use SSL, you need to choose the exact security measures that are applied (for example, the authentication method, the sending of certificates by client and server, and encryption of messages). Read Security for CICS Web support for more information about the security features that you can use to keep your CICS Web support facility safe.

The CICS Resource Definition Guide has information about the different methods of resource definition, and full reference information about all the TCPIPSERVICE resource definition attributes that you will use during this process.

  1. Identify a TCP/IP port that you want to use for CICS Web support. You are recommended to reserve the port number for use by CICS Web support. Reserving ports for CICS Web support has notes on port usage.
  2. Begin a TCPIPSERVICE definition with a name and group of your choice, using one of the methods listed in the CICS Resource Definition Guide. When you set up URIMAP definitions for inbound HTTP requests on this port, you will need to specify the name of the TCPIPSERVICE definition.
  3. Use the STATUS attribute to specify whether or not CICS should start listening for this service immediately after the definition is installed. If you specify CLOSED, you need to set the service open before it can be used. You can set the service open or closed using the CEMT transaction or the SET TCPIPSERVICE system programming command.
  4. Specify the PORTNUMBER attribute as the number of the TCP/IP port that is covered by this definition.
  5. Use the IPADDRESS attribute to specify the dotted decimal IP address on which the TCPIPSERVICE will listen for incoming connections. Alternatively, for configurations with more than one IP stack, you can specify INADDR_ANY to make CICS attempt to bind to the port on every stack where it is defined. Start of changeOr if you have a multi-stack CINET environment, and you want to assign affinity only to the default TCP/IP stack, you can specify DEFAULT to do this.End of change The reference information about this TCPIPSERVICE resource definition attribute details some additional considerations, which are important if you want more than one CICS region to share this TCPIPSERVICE definition, or if you want more than one CICS region to bind to the port number that it specifies.
  6. Use the DNSGROUP and GRPCRITICAL attributes to specify the DNS group name that the service uses within the sysplex domain, and the critical status for the service. This information enables CICS to register to Workload Manager for DNS connection optimization. "Domain Name System (DNS) connection optimization" in Java™ Applications in CICS has more information about this area.
  7. Use the PROTOCOL attribute to specify that CICS Web support handles requests on this port.
    1. Specify HTTP for normal HTTP requests. CICS forces this if you specify ports 80 or 443. This option covers both HTTP with SSL and HTTP without SSL. The SSL option specifies whether or not SSL is involved.
    2. Specify USER for non-HTTP requests that are handled using CICS Web support. When USER is specified, CICS Web support facilities are used for handling the request, but no acceptance checks are carried out for messages sent and received using this protocol. The requests are flagged as non-HTTP and passed straight to the analyzer program. URIMAP definitions are not used for these requests.
  8. Specify the TRANSACTION attribute as the 4-character ID of the Web attach task, which is normally CWXN for HTTP requests, or CWXU for non-HTTP (USER protocol) requests. This task handles initial processing of a request. CICS provides CWXN as a default if you specify ports 80 or 443. If required for accounting or monitoring purposes, you may specify an alias of CWXN or CWXU, both of which must execute the program DFHWBXN.
  9. Specify the URM attribute as the name of the analyzer program that is associated with this TCPIPSERVICE definition. For a non-HTTP (USER protocol) request, the analyzer program is always used. For an HTTP request, the analyzer program is used to interpret the request if a URIMAP definition specifies the use of an analyzer program, or if no URIMAP definition is present. An analyzer program must be specified. Only one analyzer program can be selected for each TCPIPSERVICE definition, but you can code it to handle any requests. Analyzer programs tells you about the basic support that your analyzer program must provide if you intend to use URIMAP definitions to handle all your HTTP requests. The architecture guidance in Planning your CICS Web support architecture for CICS as an HTTP server helps you decide whether you need to involve the analyzer program for any particular HTTP request.
  10. Use the SOCKETCLOSE attribute to specify how long CICS should wait before closing the socket, after issuing a receive for incoming data on that socket. NO means that the socket is left open until data is received, or until the Web client closes it. To prevent the socket from being blocked by a slow or broken Web client, you should specify a timeout value rather than specifying NO. On the first receive command issued by the Web attach task after a connection is made, this timeout value is ignored, and the task waits to receive data from the Web client for a period of time determined by CICS (30 seconds for HTTP). This prevents a socket connection being closed as soon as it is initiated, even if no data is immediately available, and so prevents a connection reset error at the Web client.
    Note: For CICS Web support, you should never specify a zero setting for SOCKETCLOSE. SOCKETCLOSE(0) means that a persistent connection cannot be maintained, even if the Web client requests it.
  11. Use the BACKLOG attribute to specify the number of connections that can be queued before TCP/IP starts to reject incoming requests from Web clients. The default is 1.
  12. Use the MAXDATALEN attribute to specify the maximum length of data that may be received on this connection. The default value is 32K, and the maximum is 524288K. This option helps to guard against denial of service attacks involving the transmission of large amounts of data.
  13. Use the TSQPREFIX attribute to specify the prefix of temporary storage queues that are created by CICS Web support. Temporary storage queues are used to store request lines, status lines, and HTTP headers for inbound and outbound messages. The prefix that you specify must correspond to an existing TSMODEL definition. The CICS-supplied default definition is DFHWEB. Configuring CICS Web support base components explains how to set up TSMODEL definitions for this purpose.
    Note: For CICS Web support, shared temporary storage queues are not supported, and recoverable temporary storage queues are not recommended.
  14. Use the SSL attribute to specify whether or not the secure sockets layer (SSL) is used for this port. YES means that SSL is used, and CICS sends a server certificate to the Web client. CLIENTAUTH means that SSL is used, and that the Web client is requested to send a client certificate to CICS, in addition to CICS sending a server certificate to the Web client. CICS provides YES as a default if you specify port number 443. Security for CICS Web support explains what to do if you are using SSL.
  15. If you have specified SSL(YES) or SSL(CLIENTAUTH), use the CERTIFICATE attribute to specify the label of an X.509 certificate that CICS uses as the server certificate during the SSL handshake. If this attribute is omitted, the default certificate defined in the key ring for the CICS region user ID is used. The certificate must be stored in a key ring in the external security manager's database. Security for CICS Web support has more information about using certificates.
  16. Use the AUTHENTICATE attribute to specify the level of authentication that is used for Web clients making requests on this port. Security for CICS Web support explains authentication and identification. Start of change(Note that if you use a URIMAP definition to deliver items as static responses, basic authentication does not operate.) End of change
    1. Specify NO if the Web client is not required to send authentication or identification information. If the client sends a valid certificate that is already registered to the security manager, CICS can use it.
    2. Specify BASIC to make CICS attempt HTTP basic authentication, where CICS requests a user ID and password from the Web client.
    3. Specify CERTIFICATE to use SSL client certificate authentication. The Web client must send a valid certificate which is already registered to the security manager, and associated with a user ID. If a valid certificate is not received, or the certificate is not associated with a user ID, the connection is rejected. SSL(CLIENTAUTH) must be specified if you are using this option.
    4. Specify AUTOREGISTER to use SSL client certificate authentication with auto-registration for the security manager. The Web client must send a valid certificate. If CICS finds that the certificate is not yet registered to the security manager, HTTP basic authentication is used to request a user ID and password, and CICS uses this information to register the certificate. SSL(CLIENTAUTH) must be specified if you are using this option.
    5. Specify AUTOMATIC to either use SSL client certificate authentication with auto-registration for the security manager (as for the AUTOREGISTER option), or if no certificate is sent, to use HTTP basic authentication (as for the BASIC option).
End of change