Creating TCPIPSERVICE resource definitions for CICS web support

Use TCPIPSERVICE resource definitions 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.

About this task

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 which CICS service is invoked when it receives an inbound TCP/IP connection request on that port. Use the PROTOCOL attribute to identify the service. Specify HTTP for standard CICS web support, and USER for non-HTTP requests that are handled using CICS web support.

For CICS web support, 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 nonstandard port numbers.

Each TCPIPSERVICE definition can specify only one analyzer program and one transaction definition for the web attach task. If you need to use more than one of these items, you must 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: Use the TCPIPSERVICE resource definition to 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 choose the exact security measures that are applied; for example, the authentication method, the sending of certificates by client and server, and the encryption of messages. See Security for CICS web support for more information about the security features that you can use to keep your CICS web support facility safe.

Procedure

Identify a TCP/IP port to use for CICS web support.
You are recommended to reserve the port number for use by CICS web support. See Reserving ports for CICS web support for information on port usage.
Create TCPIPSERVICE resource.
When you set up URIMAP definitions for inbound HTTP requests on this port, specify the name of the TCPIPSERVICE definition.
Use the STATUS attribute to specify whether CICS starts listening for this service immediately after the definition is installed.
If you specify CLOSED, you must 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.
Specify the PORTNUMBER attribute as the number of the TCP/IP port that is covered by this definition.
Use the HOST attribute to specify the dotted decimal or colon hexadecimal IP address on which the TCPIPSERVICE listens for incoming connections. You can also use the IPADDRESS attribute to specify the dotted decimal IP address for existing programs.
Alternatively, for configurations with more than one IP stack, you can specify INADDR_ANY to make CICS try to bind to the port on every stack where it is defined. Or, 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.

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.
Use the PROTOCOL attribute to specify that CICS web support handles requests on this port.
1. Specify HTTP for normal HTTP requests. HTTP requests might qualify for being processed by directly attached user transactions, and bypassing the web attach task. For more information, see Processing HTTP requests by using directly attached user transactions.
  CICS forces HTTP if you specify ports 80 or 443. This option covers both HTTP with SSL and HTTP without SSL. The SSL option specifies whether SSL is involved.
2. Specify USER for non-HTTP requests that are handled using CICS web support.
  When you specify USER, CICS web support is 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.
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 can specify an alias of CWXN or CWXU, both of which must run the program DFHWBXN.
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. You must specify an analyzer program. You can select only one analyzer program 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 Enabling CICS web support for CICS as an HTTP server helps you to decide whether to involve the analyzer program for any particular HTTP request.
Use the SOCKETCLOSE attribute to specify how long CICS waits before closing the socket after issuing a receive for incoming data on that socket.
NO means that the socket is 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, 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 delay prevents a socket connection from being closed as soon as it is started, even if no data is immediately available, and so prevents a connection reset error at the web client.
Note: For CICS web support, a zero setting for SOCKETCLOSE means that a persistent connection cannot be maintained, even if the web client requests it. This setting is not compliant with the HTTP/1.1 specification. Only specify SOCKETCLOSE(0) with the HTTP protocol if you have a special requirement for it in a CICS region that is not currently handling external requests, for example in a test environment.
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.
If the value of BACKLOG is less than the value of the TCP/IP attribute SOMAXCONN, the TCPIPSERVICE is opened with the backlog value specified by the BACKLOG attribute. If the value of BACKLOG is greater than SOMAXCONN, the TCPIPSERVICE is opened with the backlog value specified by SOMAXCONN. The default is 0, which means that the TCPIPSERVICE is opened with the backlog value specified by SOMAXCONN.
The default is 1. A value of zero disables incoming connection requests. If the value of BACKLOG is greater than the TCP/IP configuration value for SOMAXCONN, TCP/IP uses the value specified by the SOMAXCONN attribute.
Use the MAXPERSIST attribute if you need to specify a limit on the number of persistent connections from web clients that the CICS region allows for this port at any one time.
The default is that there is no limit, which is the normal behavior for an HTTP/1.1 server. Only specify a limit in a region where CICS as an HTTP server has experienced performance problems due to long-lived persistent connections. When the limit is reached, CICS implements connection throttling. How CICS web support handles persistent connections explains what happens if you specify a limit.
Note: A zero setting for MAXPERSIST means that no web clients are allowed persistent connections. This setting is not compliant with the HTTP/1.1 specification. Only specify MAXPERSIST(0) if you have a special requirement for it in a CICS region that is not currently handling external requests, for example in a test environment.
Use the MAXDATALEN attribute to specify the maximum length of data that can be received on this connection.
The default value is 32 KB and the maximum is 524 288 KB. This option helps to guard against denial of service attacks involving the transmission of large amounts of data.
Use the SSL attribute to specify whether 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. ATTLSAWARE means CICS queries the connection to see whether AT-TLS is active. CICS retrieves the client certificate if the partner provided one. ATTLSAWARE mandates PROTOCOL(HTTP). CICS provides YES as a default if you specify port number 443, and forces NO if you specify port number 80.

Security for CICS web support explains what to do if you are using SSL.

HTTP requests received by TCPIPSERVICE with SSL(NO) and SSL(ATTLSAWARE) might qualify for being processed by directly attached user transactions, and bypassing the web attach task. For more information, see Processing HTTP requests by using directly attached user transactions.
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 database. Security for CICS web support has more information about using certificates.
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.
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.
  HTTP basic authentication explains basic authentication in more detail.
3. Specify CERTIFICATE to use SSL client certificate authentication.
  The web client must send a valid certificate that 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.
  
  You must specify SSL(CLIENTAUTH) or SSL(ATTLSAWARE) if you use 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.
  
  You must specify SSL(CLIENTAUTH) or SSL(ATTLSAWARE) if you use this option.
5. Specify AUTOMATIC to 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).
Use the REALM attribute to specify the realm that is used for HTTP basic authentication.
The user sees the realm during the process of basic authentication. It identifies the set of resources to which the authentication information requested (that is, the user ID and password) apply.
1. If you require different authentication information for resources delivered using different TCPIPSERVICE definitions, specify different realms to make this requirement clear to the end user.
2. If users use the same authentication information across your resources, you can specify the same realm on multiple TCPIPSERVICE definitions.
3. If you do not specify the REALM attribute, the default realm is used.
  The default realm is:
```
realm="CICS application aaaaaaaa"
```
  where aaaaaaaa is the applid of the CICS region.