TCPIPSERVICE attributes

Describes the syntax and attributes of the TCPIPSERVICE resource.

Attributes used with PROTOCOL(ECI)

Attributes used with PROTOCOL(HTTP)

Attributes used with PROTOCOL(IPIC)

Attributes used with PROTOCOL(USER)

ATTACHSEC({LOCAL|VERIFY})

Specifies the level of attach-time user security required for this connection.

This option is valid only for PROTOCOL(ECI).

LOCAL: Specifies that CICS® does not require a user ID or password (or password phrase) from clients.
VERIFY: Specifies that incoming attach requests must specify a user ID, and a user password or password phrase. Specify VERIFY when connecting systems are unidentified and cannot be trusted.

AUTHENTICATE({NO|ASSERTED|AUTOMATIC|AUTOREGISTER|BASIC|CERTIFICATE})

Specifies the authentication and identification scheme to be used for inbound TCP/IP connections for the HTTP and USER protocols. For the IPIC protocol, this attribute is not applicable. For the ECI protocol, this attribute is invalid. For more information about authentication, see Identification and authentication.

ASSERTED: The ASSERTED attribute in TCPIPSERVICE definitions is obsolete but is retained for compatibility reasons.

When PROTOCOL(HTTP) or PROTOCOL(USER) is specified:

NO

The client is not required to send authentication or identification information. However, if the client sends a valid certificate that is already registered to the security manager and associated with a user ID, then that user ID identifies the client.

BASIC

HTTP Basic authentication is used to obtain a user ID, and password or password phrase from the client.

If the client has sent an Authorization header, its contents are decoded as a user ID, and password or password phrase. If these are not valid, an HTTP 401 response is returned, together with a WWW-Authenticate header, which causes the client program to prompt the user for a new user ID, and password or password phrase. This process continues until the client either supplies a valid user ID, and password or password phrase, or cancels the connection.

When the user has been successfully authenticated, the user ID supplied identifies the client.

AUTOREGISTER

SSL client certificate authentication is used to authenticate the client.

If the client sends a valid certificate that is already registered to the security manager and associated with a user ID, then that user ID identifies the client.
If the client sends a valid certificate that is not registered to the security manager, then HTTP Basic authentication is used to obtain a user ID, and password or password phrase from the client. If the password or password phrase is valid, CICS registers the certificate with the security manager and associates it with the user ID. The user ID identifies the client.
For a certificate to be registered, the client needs the appropriate access definition in RACF®. The access required is READ access to the IRR.DIGTCERT.ADD profile in the FACILITY class.

Note: If you specify AUTHENTICATE(AUTOREGISTER), you must also specify SSL(CLIENTAUTH | ATTLSAWARE).

AUTOMATIC

This function combines the AUTOREGISTER and BASIC functions.

If the client sends a certificate, then processing will continue as described in AUTOREGISTER.
If the client does not send a certificate, then processing will proceed as described in BASIC.

CERTIFICATE

SSL client certificate authentication is used to authenticate and identify the client. The 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.

When the user has been successfully authenticated, the user ID associated with the certificate identifies the client.

Note: If you specify AUTHENTICATE(CERTIFICATE), you must also specify SSL(CLIENTAUTH | ATTLSAWARE).

Note: For the HTTP or USER protocol, the analyzer program (named by the user replaceable module (URM) attribute) can change the user ID supplied by the authentication process. If the authentication process does not supply a user ID, the analyzer program or URIMAP definition can supply one. Otherwise, the CICS default user ID is used.

BACKLOG(0|backlog)

Specifies, in the range 0 - 32767, the maximum number of inbound TCP/IP connection open requests that can be queued in TCP/IP waiting for CICS processing. When the maximum is reached, TCP/IP rejects additional requests.

If the value of BACKLOG is zero, CICS does not limit the backlog; instead, the value of TCP/IP attribute SOMAXCONN is used. If the value of BACKLOG is greater than SOMAXCONN, the value of SOMAXCONN is used.

For IPIC connections, set this value to the maximum number of concurrent connection requests that can be established by using this TCPIPSERVICE.

If performance tuning for HTTP connections is enabled, when CICS is at maximum capacity, all inbound HTTP connection open requests will queue outside of CICS in the TCPIPSERVICE's listening connection's backlog queue in TCP/IP. Ensure the BACKLOG value is large enough, because when this queue is full, connection requests will be refused. NETSTAT ALL shows the backlog values in use for a listening connection. For more information, see Netstat in the z/OS Communication Server IP System Administrator's Commands.

When connection balancing is in use, the backlog queue's depth is included in the processing that determines the most suitable listener, so consider the BACKLOG attribute across all TCPIPSERVICEs on CICS regions that share a port.

CERTIFICATE(label)

Specifies the label of an X.509 certificate that is used as a server certificate during the SSL handshake when the connection is acquired. If this attribute is omitted, the default certificate defined in the key ring for the CICS region user ID is used.

Certificate labels can be up to 32 bytes long.

The certificate must be stored in a key ring in the database of the external security manager. For more information, see Building a key ring manually.

This attribute cannot be specified unless SSL(YES) or SSL(CLIENTAUTH) is also specified.

CIPHERS(value)

The CIPHERS attribute can be specified in either of two ways:

A string of up to 56 hexadecimal digits that is interpreted as a list of up to 28 2-digit cipher suite codes.
The name of the SSL cipher suite specification file, which is a z/OS® UNIX file in the security/ciphers subdirectory of the directory that is specified by the USSCONFIG system initialization parameter. For example if USSCONFIG is set to /var/cicsts/dfhconfig and CIPHERS is set to strongciphers.xml, the fully qualified file name is /var/cicsts/dfhconfig/security/ciphers/strongciphers.xml. For more information, see SSL cipher suite specification file.

When you use the CEDA transaction to define the resource, CICS automatically initializes the attribute with a default list of acceptable codes. For CICS to initialize the attribute, the KEYRING system initialization parameter must be specified in the CICS region where you are running CEDA. If KEYRING is not set, CICS does not initialize the attribute. The default list of codes is 35363738392F303132330A1613100D15120F0C unless the system initialization parameter NISTSP800131A=CHECK is set, in which case it is 35363738392F303132330A1613100D.

You can reorder the cipher codes or remove them from the initial list. However, you cannot add cipher codes that are not in the default list for the specified encryption level. To reset the value to the default list of codes, delete all of the cipher suite codes. The field is automatically repopulated with the default list.

For more information, see Cipher suites.

DESCRIPTION(text)

You can provide a description of the resource that you are defining in this field. The description text can be up to 58 characters in length. No restrictions apply to the characters that you can use. However, if you use parentheses, ensure that for each left parenthesis there is a matching right parenthesis. If you use the CREATE command, for each single apostrophe in the text, code two apostrophes.

DNSGROUP(dnsgroup)

This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS.

GROUP(groupname)

Every resource definition must have a GROUP name. The resource definition becomes a member of the group and is installed in the CICS system when the group is installed.

Acceptable characters: `A-Z 0-9 $ @ #` Any lowercase characters that you enter are converted to uppercase.

The GROUP name can be up to 8 characters in length. Lowercase characters are treated as uppercase characters.

GRPCRITICAL({NO|YES})

This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS.

HOST({ANY|DEFAULT|hostname})

Specifies the 116-character IPv4 or IPv6 address or host name on which CICS listens for incoming connections. Use HOST instead of IPADDRESS when you define new resources. Do not specify both HOST and IPADDRESS, because HOST always takes precedence over IPADDRESS. IPADDRESS is supported for existing programs that specify IPv4 function.

Possible values are as follows:

ANY

The ANY option has the same function as the ANY and INADDR_ANY options of IPADDRESS. The ANY option specifies that CICS listens on any of the addresses known to TCP/IP for the host system. You can have multiple IP addresses defined for a host. By specifying ANY, you also allow for the TCPIPSERVICE definition to be shared among CICS servers. If you specify ANY, CICS attempts to bind to the port on every stack where it is defined. If, in addition, you want more than one CICS region to bind to the port, you must specify the SHAREPORT option in every stack where the port is defined. If you do not do so, only one CICS region can bind to the port number in those stacks that do not have the SHAREPORT option. Subsequent attempts by other regions to bind to every stack fail, and CICS issues a message indicating that the port is in use.

If you specify the ANY option in a dual-mode (IPv4 and IPv6) environment, CICS attempts to reuse the most recent IPv4 or IPv6 address. If this is the first connection, and CICS cannot retrieve an address, 0.0.0.0 is returned, and no affinity is assigned.

DEFAULT

The DEFAULT option assigns affinity to the TCP/IP stack that is defined as the default in a multistack CINET environment.

If the DEFAULT option is used in a dual-mode (IPv4 and IPv6) environment, affinity is assigned to the IPv4 environment because the DEFAULT option is applied to the IPv4 environment.

If DEFAULT is used in a non-CINET environment or no default TCP/IP stack exists, an exception trace is written, 0.0.0.0 is returned, and no affinity is assigned.

If you are operating in a dual-mode (IPv4 and IPv6) environment, specifying HOST(DEFAULT) forces all traffic to pass across the IPv4 network connection.

hostname

hostname can be a character host name, an IPv4 address, or an IPv6 address.

You can specify an address as a character name that can be looked up on the domain name server. The host name can be entered in uppercase, lowercase, or mixed case, but if a host name is specified instead of an IP address, the host name is converted to lowercase in the TCPIPSERVICE definition.

Do not use a character host name if you have a list of addresses at the domain name server, because hostname resolves against the first IP address only in the list (that is, the server does not listen on any of the IP addresses in the list for this host name). If you require a particular IP address in a list at the domain name server, define the IP address explicitly in hostname.

If you specify an IPv6 address (or a host name that resolves to an IPv6 address), ensure that you are operating in a dual-mode (IPv4 and IPv6) environment and that the client or server that you are communicating with is also operating in a dual-mode (IPv4 and IPv6) environment. For more information about IPv6, see Understanding IPv6 and CICS.

You can specify IPv4 and IPv6 addresses in a number of acceptable formats. See IP addresses for more information about address formats.

IPADDRESS({ANY|INADDR_ANY|DEFAULT|ipaddress})

Specifies the dotted decimal IPv4 address on which this TCPIPSERVICE listens for incoming connections. It must be of the form nnn.nnn.nnn.nnn where nnn is 0 through 255. You can use the HOST attribute to specify the same information as IPADDRESS, but HOST also supports an IPv6 format address and character host name. If you are using IPv6 connections, you must use the HOST attribute for your definitions instead of IPADDRESS. HOST always takes precedence over IPADDRESS. The IPADDRESS attribute interacts with HOST in a number of ways:

If you specify HOST, IPADDRESS is always overwritten with a value that depends on the contents of HOST:
- If you specify an IPv4 address, ANY, or DEFAULT in HOST, IPADDRESS is overwritten with the contents of HOST.
- If you specify an IPv6 address or a character host name in HOST, IPADDRESS is overwritten with blanks.
If you specify both HOST and IPADDRESS, the HOST value is always used:
- If HOST contains an IPv4 address, ANY, or DEFAULT, IPADDRESS is populated with the contents of HOST.
- If HOST contains an IPv6 address, IPADDRESS is overwritten with blanks.
If you specify IPADDRESS (but not HOST), HOST is populated with the contents of IPADDRESS.

If you specify an IP address of 0.0.0.0 and the HOST option is blank, a warning is issued and the value ANY is assumed.

IPADDRESS is supported for existing IPv4 function only. Use the HOST option for new resources.

Possible values are:

ANY or INADDR_ANY: The TCPIPSERVICE listens on any of the addresses known to TCP/IP for the host system. It is possible to have multiple IP addresses defined for a host. Specifying ANY or INADDR_ANY also allows for the TCPIPSERVICE definition to be shared among CICS servers.
If you specify ANY or INADDR_ANY, CICS attempts to bind to the port on every stack where it is defined. If, in addition, you want more than one CICS region to bind to the port you must specify the SHAREPORT option in every stack where the port is defined. If you do not do so, only one CICS region is able to bind to the port number in those stacks that do not have the SHAREPORT option. Subsequent attempts by other regions to bind to every stack fails: CICS issues a message indicating that the port is in use. For information about the SHAREPORT option, see z/OS Communications Server: IP Configuration Reference.
DEFAULT: Assigns affinity to the TCP/IP stack that is defined as the default in a multi stack CINET environment. If DEFAULT is used in a non-CINET environment or there is no default TCP/IP stack, then an exception trace is written and no affinity is assigned.
ipaddress: The TCPIPSERVICE accepts connections on this particular address. If the address specified is not known to TCP/IP on the host system, the TCPIPSERVICE does not open. If you enter a specific address here, this definition might not be valid for CICS servers running on other regions, and you might not be able to share the definition with those servers.

MAXDATALEN({32|number})

Specifies, in kilobytes, the maximum length of data that can be received by CICS as an HTTP server, on the HTTP protocol or the USER protocol. The default value is 32 KB. The minimum is 3 KB, and the maximum is 524,288 KB. Use MAXDATALEN to guard against denial of service attacks involving the transmission of large amounts of data.

MAXPERSIST({NO|number})

Specifies the maximum number of persistent connections from web clients that the CICS region allows for this port at any one time. This setting applies only for the HTTP protocol.

The default value NO means that there is no limit on the number of persistent connections.
In a CICS region that is at risk of being overloaded with persistent connections, you can specify a suitable value (up to a theoretical maximum of 65535) based on the number of persistent connections that the CICS region can handle simultaneously. When this limit is reached and further web clients connect on the port, CICS requires the new clients to close the connection after they receive each response. When the new clients reconnect, if they connect to another CICS region that shares the port and has not reached its limit, they can maintain a persistent connection there instead. An HTTP/1.1 server should normally allow persistent connections, so only set this option in a CICS region that has experienced performance problems due to persistent connections from long-lived web clients.
If you specify a value of zero for this option, the CICS region does not allow persistent connections and requires every web client to close the connection after they receive each response. A zero setting for MAXPERSIST is not compliant with the HTTP/1.1 specification, so only use that setting 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.

PORTNUMBER(port)

Specifies, in the range 1 through 65535, the decimal number of the port on which CICS is to listen for incoming client requests.

The well-known ports are those from 1 through 1023. It is advisable to use well-known port numbers only for those services to which they are normally assigned. The well-known ports for services supported by CICS are:

80: HTTP (non-SSL)
443: HTTP with SSL
1435: ECI (Registered port number)

You should take care to resolve conflicts with any other servers on the same MVS™ image that might use the well-known ports.

Port sharing must be enabled for any port that you want to share across CICS systems within an MVS image. For more information, see z/OS Communications Server: IP Configuration Reference.

PRIVACY

This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.

PROTOCOL({HTTP|IIOP|ECI|IPIC|USER})

Specifies the application level protocol used on the TCP/IP port.

HTTP: HTTP protocol is used. HTTP protocol is handled by CICS Web support. CICS performs basic acceptance checks for messages sent and received using this protocol. This protocol is required for the well-known ports 80 (used for HTTP without SSL) and 443 (used for HTTP with SSL). HTTP requests might qualify for being processed by directly attached user transactions, and bypassing the web attach task, defined in the TRANSACTION attribute of TCPIPSERVICE. For more information, see Processing HTTP requests by using directly attached user transactions.
IIOP: The IIOP attribute in TCPIPSERVICE definitions is obsolete but is retained for compatibility reasons.
ECI: The CICS ECI protocol is used.
IPIC: IPIC protocol is used. Specify IPIC for TCPIPSERVICE resources that are to be used for IP interconnectivity (IPIC) connections.
USER: The user-defined protocol is used. Messages are processed as non-HTTP messages. They are flagged as non-HTTP and passed unchanged to the analyzer program for the TCPIPSERVICE resource. CICS Web support facilities are used for handling the request, but no acceptance checks are carried out for messages sent and received by using this protocol. Processing for all non-HTTP requests must be carried out under the USER protocol, so that they are protected from the basic acceptance checks that CICS carries out for requests by using the HTTP protocol. If an HTTP message is handled by the USER protocol, you are responsible for checking its validity.

REALM(string)

Specifies the realm that is used for HTTP basic authentication. You can only specify this attribute for the HTTP protocol.

The realm is provided by CICS in the WWW-Authenticate header, and is seen by the user 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 or password phrase) applies.

If you do not specify a realm, the default used by CICS is CICS application aaaaaaaa, where aaaaaaaa is the APPLID of the CICS region.

The realm can be up to 56 characters, and can include embedded blanks. It is specified in mixed case, and the case is preserved. Do not specify opening and closing double quotation marks, as CICS provides these when assembling the WWW-Authenticate header.

Acceptable characters: `A-Z a-z 0-9 $ @ # . - _ % & ? ! : \| ' = ¬ + * , ; < > ( )` Space characters are also permitted. If parentheses are used, you must use them as pairs of opening and closing parentheses.

SOCKETCLOSE({NO|hhmmss})

Specifies whether, and for how long, CICS waits before it closes the socket. The SOCKETCLOSE attribute does not apply to the first receive request that is issued after a connection is made. On the first receive request for the ECI and USER protocols, CICS waits for data for 30 seconds before it closes the socket. On the first receive request for the HTTP protocol, CICS waits for the DTIMEOUT value associated with the transaction specified on the TCPIPSERVICE. If this DTIMEOUT value is zero CICS waits for 30 seconds.

The interval is measured from the time of the initial receive request for incoming data on that socket.

NO: The socket remains open until it is closed by the client, or by a user application program in CICS.
hhmmss: The interval (in HHMMSS format) from the time of the initial receive request for incoming data, after which CICS is to timeout the socket. Choose a value that is appropriate to the responsiveness of the client, and the reliability of your network. Specifying 000000 closes the socket immediately if no data is available for any receive requests other than the first one.

If you are using this TCPIPSERVICE resource for CICS web support with the HTTP protocol, a zero setting for SOCKETCLOSE means that CICS closes the connection immediately after receiving data from the web client, unless further data is waiting. This setting means that persistent connections cannot be maintained, and it is not compliant with the HTTP/1.1 specification. Use a zero setting for SOCKETCLOSE with the HTTP protocol only 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.

If you specify PROTOCOL(ECI) or PROTOCOL(IPIC) you must specify SOCKETCLOSE(NO).

If you specify PROTOCOL(USER), persistent sessions are not supported, and you should specify SOCKETCLOSE(000000).

After the TCPIPSERVICE resource is installed, you cannot change this value using CEMT; you must set the TCPIPSERVICE resource out of service, then re-install the TCPIPSERVICE resource with the modified definition.

SPECIFTCPS

This parameter specifies the 8-character name of the specific TCPIPSERVICE when defining a generic TCPIPSERVICE as part of a high-availability cluster. This parameter is only valid when the protocol is IPIC and the IP end point defined by the PORT and HOSTNAME or IPADDRESS attributes is the generic end point of an HA cluster of CICS regions.

Acceptable characters: `A-Z 0-9 $ @ #` Unless you are using the CREATE command, any lowercase characters are converted to uppercase.

SSL({NO|YES|CLIENTAUTH|ATTLSAWARE})

Specifies whether the TCP/IP service is to use the secure sockets layer (SSL) for encryption and authentication. You can specify this attribute for the HTTP, USER, and IPIC protocols, but not for the ECI protocol. Note: When they use SSL, MAXSSLTCBs should be set to a value that is at least twice the number of IPIC connections that use SSL by the CICS region.

NO: SSL is not to be used. No security checks are applied when the connection is being acquired. No encryption is applied to outbound messages. SSL(NO) and PROTOCOL(HTTP) 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.
YES: An SSL session is to be used; CICS sends a server certificate to the client. SSL decryption processing is applied to all messages arriving at this port. The level of encryption that is applied to inbound messages is found from the value of the CIPHERS attribute.
CLIENTAUTH: An SSL session is to be used; CICS sends a server certificate to the client. CICS expects to receive a client certificate from the partner system during the SSL handshake, when the connection is being acquired.

ATTLSAWARE: CICS queries the client connection to determine whether AT-TLS is active. CICS retrieves a client certificate from TCP/IP if one was provided by the partner. ATTLSAWARE should be used with PROTOCOL(HTTP) TCPIPSERVICES. SSL(ATTLSAWARE) and PROTOCOL(HTTP) 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.

STATUS({OPEN|CLOSED})

Indicates the initial status of the service after installation. Set it to OPEN if CICS is to begin listening for this service after installation. Set to CLOSE if CICS is not to listen on behalf of this service after installation.

This attribute is ignored for TCPIPSERVICE resources that are dynamically generated by a CICS bundle. The initial status of a TCPIPSERVICE resource is derived from the initial status of the bundle that defines the resource.

TCPIPSERVICE(name)

Specifies the 8-character name of this service.

Acceptable characters: `A-Z 0-9 $ @ #` Unless you are using the CREATE command, any lowercase characters that you enter are converted to uppercase.

TRANSACTION(transaction)

Specifies the 4-character ID of the CICS transaction attached to process new requests received for this service.

For an ECI over TCP/IP TCPIPSERVICE resource, specify CIEP (or another transaction that executes program DFHIEP).
For an HTTP TCPIPSERVICE resource, specify CWXN (or another transaction that executes program DFHWBXN). 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.
For an IPIC TCPIPSERVICE resource, specify CISS (or another transaction that executes program DFHISCOP).
For a USER TCPIPSERVICE resource, specify CWXU (or another transaction that executes program DFHWBXN).

TSQPREFIX(prefix)

This attribute is obsolete, but is supported to provide compatibility with earlier releases of CICS. For more information, see Obsolete attributes.

URM({NO|program_name})

Specifies the name of a user-replaceable program to be started by this service.

NO

Autoinstall is not permitted with this TCPIPSERVICE resource. This is only applicable for PROTOCOL(IPIC).

program_name

For those protocols for which URM is a required attribute, the default program name depends upon the value of the PROTOCOL attribute:

For the HTTP protocol, specify the name of an analyzer program to be associated with this TCPIPSERVICE resource. The CICS-supplied analyzer program DFHWBAAX is the default. DFHWBAAX provides basic error handling when all requests on the port should be handled by URIMAP definitions (for example, web service requests). If you must provide support for requests that are not handled by URIMAP definitions, the analyzer program specified for your TCPIPSERVICE resource should be the CICS-supplied sample analyzer program DFHWBADX or your own customized analyzer program. See Analyzer programs for more information about analyzer programs.
For the IPIC protocol, specify the name of the autoinstall user program for IPIC connections, if required. For PROTOCOL(IPIC), if you do not specify this attribute CICS uses the CICS-supplied default autoinstall user program, DFHISAIP.
For the USER protocol, specify the name of an analyzer program to be associated with this TCPIPSERVICE definition. The analyzer program must be present, and it handles all requests on this protocol. The CICS-supplied sample analyzer program, DFHWBADX, is suitable. See the Analyzer programs for more information about analyzer programs.