ServicesConnection statement

The Policy Agent uses the ServicesConnection statement to specify the listening port, listening TCP/IP image, and security level for connections to the Policy Agent. Applications that use this connection are known as services requestors. One such services requestor is the IBM® Configuration Assistant for z/OS® Communications Server, which is an import requestor that uses this connection to retrieve import policies or TCP/IP profile information.

Consider the following characteristics when using the ServicesConnection statement:

• If you want to use default values for all parameters, you can specify the ServicesConnection statement without a set of braces.
• If you specify Security Basic, you can either use a default unsecure connection or supply user defined AT-TLS policies for this import services connection to create a secure SSL connection.
• If you specify Security Secure, the Policy Agent generates an AT-TLS policy and installs it at the lowest priority (lower than any configured policies) into the specified TCP/IP image after any configured local or remote AT-TLS policies have been installed.
• If you update any parameters that are used in the generated policy (Port, Trace or Keyring parameters), the Policy Agent reinstalls the generated policy.
• The Policy Agent listens for TCP connections on the specified TCP/IP image name only.
• If you remove the ServicesConnection statement, all services requestor connections to this Policy Agent are disconnected.
• Updates to the ServicesConnection statement are used for only new services requestor connections to the Policy Agent.
• If you do not configure the ServicesConnection statement, or the image name is not an active TCP/IP image, the Policy Agent does not listen on any port for services requestor connections.
• To restart the listen for services requestor connections and to reinstall the generated AT-TLS policy, issue the MODIFY SRVLSTN command. See z/OS Communications Server: IP System Administrator's Commands for more information about this command.

Parameters

Port

Specifies the port that the Policy Agent listens on for TCP connections from services requestors on the specified TCP/IP image name. If you are using the IBM Configuration Assistant for z/OS Communications Server, this port must be the same as the host connection port that is specified on the Configuration Assistant Import Policy Data request panel for any import requestor that connects to this Policy Agent or on the request panels for discovery import (for example, on the Discover Stack Local Addresses panel).

If you change the Port parameter value, the Policy Agent listens for new TCP connections using the updated value on the specified TCP/IP image name.

Valid port values are in the range 1 - 65 535. The default port value is 16 311.

Restriction: The port value cannot match the port value configured on the ClientConnection statement.

ImageName

A string 1 - 8 characters in length that specifies the TCP/IP image name. The Policy Agent listens for services connections only on this TCP/IP image.

If you change the ImageName value, the Policy Agent listens for new TCP connections on the newly specified TCP/IP image name. If you specify the Security parameter with the Secure value and update the ImageName parameter, the Policy Agent removes the generated policy from the original TCP/IP image and installs it on the newly specified image.

If you specify Security Basic and define AT-TLS policies for this import services connection to create a secure SSL connection, these policies must be installed for this ImageName.

Results:

• In a single stack (INET) environment, the Policy Agent uses the active TCP/IP image to listen for services connection requests.
• In a common INET (CINET) environment, if you do not specify the TCP/IP image name, the Policy Agent uses the default TCP/IP image (resolver supplied TCPIPuserid statement or TCPIPjobname statement). If the Policy Agent cannot determine the default TCP/IP image, the Policy Agent uses the name INET.
• If you specify an image name that does not have a corresponding TcpImage or PEPInstance statement, the Policy Agent creates an internal TcpImage statement with default values to represent the specified TCP/IP image. You can specify only 7 (instead of 8) TcpImage or PEPInstance statements.
• If you specify an image name that is not active, the Policy Agent does not listen for services requestor connections until the TCP/IP image becomes active.

Security

Indicates the level of security that is used for the services requestor connection. If you change the Security parameter from Secure to Basic, the Policy Agent uninstalls the generated AT-TLS policy from the specified TCP/IP image.

Basic

Specifies one of the following connections:

• The connection does not use SSL and is unsecure.
• You define AT-TLS policies for this import services connection to create a secure SSL connection.

Result: If you specify the Security Basic setting without defining AT-TLS policies, the user ID and password that the services requestor provides flow without encryption.

Tip: For secure SSL, it is recommended to configure Security Basic and to supply user defined AT-TLS policies to protect the import service connection with the required SSL/TLS protection.

Secure

Specifies that the connection uses SSL. The Policy Agent installs a generated AT-TLS policy similar to the following example into the specified TCP/IP image to protect the connection.

Restriction: This option supports only TLSv1.0 and is not recommended for secure SSL.

TTLSRule                     TTLS_RULE_______________GENERATED
{
   LocalPortRange             <ServicesConnection port value>
   Direction                  Inbound
   TTLSGroupActionRef         TTLS_GROUP_ACTION_______GENERATED
   TTLSEnvironmentActionRef   TTLS_ENVIRONMENT_ACTION_GENERATED
}
TTLSGroupAction   TTLS_GROUP_ACTION_______GENERATED
{
  TTLSEnabled     On
  Trace           <ServicesConnection trace value>
}
TTLSEnvironmentAction  TTLS_ENVIRONMENT_ACTION_GENERATED
{
  HandshakeRole        Server
  TTLSKeyRingParms
  {
    Keyring            <ServicesConnection keyring value>
  }
}

Rule: If you specify Security Secure, the Keyring parameter is required.

Trace

Specifies the level of AT-TLS tracing to be used for the generated AT-TLS policy. Valid values for n are in the range 0 - 255. The sum of the numbers associated with each level of selected tracing is the value you should specify for n. If n is an odd number, errors are written to joblog, and all other configured traces are sent to syslogd.

0

No tracing is enabled.

1 (Error)

Errors are traced to the TCP/IP joblog.

2 (Error)

Errors are traced to syslogd. This is the default. The messages are issued with syslogd priority code err.

4 (Info)

Enables tracing of instances when a connection is mapped to an AT-TLS rule and when a secure connection is successfully initiated. The messages are issued with syslogd priority code info.

8 (Event)

Enables tracing of major events. The messages are issued with syslogd priority code debug.

16 (Flow)

Enables tracing of system SSL calls. The messages are issued with syslogd priority code debug.

32 (Data)

Enables tracing of encrypted negotiation and headers. This value traces the negotiation of secure sessions. The messages are issued with syslogd priority code debug.

64

Reserved.

128

Reserved.

255

Enables all tracing.

If you specify Security Basic, this parameter is ignored.

Keyring

A string 1 - 1 023 in length that specifies the ring name of the SAF key ring. This key ring typically contains the certificates of the trusted (by the client) Certificate Authorities.

Restriction: If Security is configured with Secure, then this parameter is required.

If you specify Security Basic, this parameter is ignored.