INTERNALCLIENTPARMS Statement

The INTERNALCLIENTPARMS statement is used to configure the Telnet server, an internal client of the TCPIP virtual machine. A maximum of 500 characters can be used to specify the INTERNALCLIENTPARMS.

Read syntax diagramSkip visual syntax diagram INTERNALCLIENTPARMS ASYNCHRONOUSINPUTCCSTERMNAME TCPIPCCSTERMNAMEcccccCLIENTCERTcheck PREFERREDCLIENTCERTcheckPREFERREDNONEREQUIREDCONNECTEXITfilenameDISABLESGAEOJTIMEOUT 120EOJTIMEOUTsecondsIGNOREEAUDATAINACTIVE 0INACTIVEsecondsLDEVRANGE 0 0FFFLDEVRANGElow highNOTN3270EPORT 23PORT numSCANINTERVAL 60SCANINTERVALsecondsSECURECONNECTION NEVERSECURECONNECTIONREQUIREDPREFERREDALLOWEDNEVERTIMEMARK 600TIMEMARKsecondsTLSLABELlabelTN3270EEXITfilenameTN3270ENOSCEXITTRANSFORM ENDINTERNALCLIENTPARMS

Operands

ASYNCHRONOUSINPUT
ASYNCHINPUT
ASYNCINPUT
For Telnet LINEMODE connections, causes the Telnet server to signal an attention interrupt to the associated virtual machine, when input is received from the client and the virtual machine has not issued a read. This usually causes the virtual machine to issue a read, allowing the user input to be presented. If this option is not specified, the Telnet server holds client input until the associated virtual machine issues a read.
CCSTERMNAME ccccc
String 1 to 5 characters in length specifying the terminal name prefix for line-mode Telnet sessions.
CLIENTCERTCHECK NONE
A client certificate will not be requested.
CLIENTCERTCHECK PREFERRED
A client certificate will be requested. If a client certificate is not received, the connection will proceed without it. If a client certificate is received, it will be authenticated. If the certificate is not valid, the failure will be logged in the SSL server console log and the connection will continue as a secure connection protected by the server certificate.
CLIENTCERTCHECK REQUIRED
A client certificate will be requested and authenticated. If a client certificate is not received, the connection will be terminated with a fatal TLS error. If the certificate fails authentication, the handshake will fail.
CONNECTEXIT filename
The name of the Telnet session connection exit to be loaded. The exit will be called every time a Telnet session connection is established unless the TN3270ENOSCEXIT parameter has been supplied via the OBEYFILE command or as a parameter on the INTERNALCLIENTPARMS statement in the TCP/IP configuration file.

The CONNECTEXIT can be used to control system access based on the client’s IP address and the target port number. The exit can also be used to specify an initial CP command (such as DIAL VTAM) to be simulated for a client with a transparent mode session.

The search sequence is:

  1. The GLOBAL LOADLIB list,
  2. filename TEXT on any accessed disk,
  3. The GLOBAL TXTLIB list.

The CONNECTEXIT parameter is ignored if it is supplied via the OBEYFILE command. The exit interface is described in the z/VM: TCP/IP Programmer's Reference.

Sample copies of the Telnet session connection exit files (SCEXIT EXEC, SCEXIT ASSEMBLE and SCEXIT TEXT) are supplied as softcopy files (SCEXIT SAMPEXEC, SCEXIT SAMPASM, and SCEXIT TEXTSAMP, respectively) on the TCPMAINT 591 minidisk. Consult the z/VM: TCP/IP Programmer's Reference for details about SCEXIT parameter list and parameter descriptions.

DISABLESGA
Suppresses the transmission of GO AHEADS by Telnet, which is negotiated by both client and server. Using DISABLESGA reduces the overhead for a full duplex terminal and a full duplex connection.
EOJTIMEOUT seconds
Sets the EOJTIMEOUT interval. This parameter is used in conjunction with TN3270E printer support, and causes an EOJ header to be sent to a printer if no such header is sent within the specified number of seconds.

Specify seconds as a positive integer in the range of 1 through 99,999,999. If seconds is not within the range of accepted values or this operand is omitted, the default of 120 seconds (two minutes) is used.

IGNOREEAUDATA
Causes the Telnet server to ignore any data associated with Erase All Unprotected (EAU) commands in the data stream received from the host. Ordinarily, any such data is forwarded to the client. Some Telnet clients enforce the restriction that there can be no data associated with an EAU command and require this option in order to function properly.
INACTIVE seconds

Defines an interval (in seconds) after which the Telnet server closes a connection due to inactivity. In the context of this operand, a connection is considered to be inactive if no data is transmitted over that connection for the specified amount of time.

Specify seconds as zero (0) to signify no inactivity interval is to be in effect (that is, connections are not to be closed due to inactivity), or as a positive integer in the range of 1 through 99,999,999. If seconds is not within the range of accepted values or this operand is omitted, the default of zero (0) is used.

Note: Telnet protocol commands transmitted over a connection do not affect inactivity timing.
LDEVRANGE low high
Hexadecimal logical device number range between 0 and FFFF to be used for incoming Telnet connections. Do not set the end of the range larger than the maximum logical device number defined by the CP SET MAXLDEV command. Since logical device numbers are unique within the VM system, there is no guarantee that other service machines will not use the same device range that is assigned to TCP/IP.

If LDEVRANGE is not specified, logical device numbers in the range from 0 to 0FFF will be used.

NOTN3270E
Prevents the Telnet server from negotiating sessions based on the TN3270E protocol. Some Telnet clients might not handle TN3270E negotiation correctly, in which case this parameter can be used to allow them to function correctly. However, Telnet-based printer sessions are not supported if this parameter is specified.
PORT num
Accepts incoming Telnet requests on a specified port number rather than the default port 23. This parameter may be specified multiple times to accept incoming Telnet requests on any of several different ports. The port numbers specified should have corresponding PORT statements that reserve them for the special user identifier INTCLIEN, which represents the Telnet server.

The PORT parameter is ignored if it is supplied via the OBEYFILE command.

SCANINTERVAL seconds
Defines the interval at which the Telnet server checks connections to determine whether a TIMEMARK should be sent over a connection, or if a connection should be closed due to an elapsed interval of inactivity.

Specify seconds as a positive integer in the range of 1 through 60. If seconds is not within the range of accepted values or this operand is omitted, the default of 60 seconds (one minute) is used.

To facilitate appropriate timing-based actions, the SCANINTERVAL value is adjusted by the Telnet server to match the smallest interval established among the following:
  • EOJTIMEOUT
  • INACTIVE
  • TIMEMARK
  • SCANINTERVAL
  • 60 seconds (a constant)
SECURECONNECTION REQUIRED
All Telnet connections must be secured either statically or dynamically.
SECURECONNECTION PREFERRED
If a Telnet connection is not secured statically, the Telnet server will initiate the request for TLS to be used; if the client is unable to use TLS, the connection proceeds as a clear connection. Statically secured connections are not affected by this option.
SECURECONNECTION ALLOWED
If a Telnet connection is not secured statically, the Telnet server will use TLS only when the request to use TLS is initiated by the client. Statically secured connections are not affected by this option.
SECURECONNECTION NEVER
All Telnet connections must be clear connections.
TIMEMARK seconds
Defines an interval (in seconds) after which the Telnet server is to send a TIMEMARK option on a given connection. TIMEMARK options issued in this context serve to verify the client associated with a probed connection is operational.

Specify seconds as zero (0) to signify no TIMEMARKs are to be sent by the Telnet server, or as a positive integer in the range of 1 through 99,999,999. If seconds is not within the range of accepted values or this operand is omitted, the default of 600 seconds (10 minutes) is used.

When TIMEMARKs are in use, the Telnet server sends a TIMEMARK option over a connection once SCANINTERVAL processing has determined the time elapsed (since the last activity for the connection) is greater than the defined TIMEMARK interval. The receipt of a client TIMEMARK response confirms the connection should be maintained, and the response is otherwise ignored. If a TIMEMARK response is not received on a connection and a subsequent TIMEMARK interval then passes with no additional activity, the connection is closed by the Telnet server, under the assumption the client host can no longer respond (due to networking or other problems).

Note:
  1. The TIMEMARK value established can affect that used for SCANINTERVAL processing.
  2. Connections that are responsive to TIMEMARK probes may still be closed due to inactivity, as directed by the INACTIVE timing operand.
TLSLABEL label
Specifies the TLS label to be used by the Telnet server when securing connections using TLS.
Note: The TLS label can be no more than 8 characters, and must be comprised of only uppercase, alphanumeric characters.
TN3270EEXIT filename
The name of the Telnet printer management exit. The exit is called every time a Telnet printer session is established or terminated.

The TN3270EEXIT can be used to control system access based on the client’s IP address and port number, the local port number, the logical unit name associated with the session by the client, and the user identifier and virtual device address associated with the session through the TN3270E statement (see TN3270E Statement).

The search sequence is:

  1. The GLOBAL LOADLIB list,
  2. filename TEXT on any accessed disk,
  3. The GLOBAL TXTLIB list.

The TN3270EEXIT parameter is ignored if it is supplied via the OBEYFILE command. The exit interface is described in the z/VM: TCP/IP Programmer's Reference.

Sample copies of the Telnet printer management exit files (PMEXIT EXEC, PMEXIT ASSEMBLE and PMEXIT TEXT) are supplied as softcopy files (PMEXIT SAMPEXEC, PMEXIT SAMPASM, and PMEXIT TEXTSAMP, respectively) on the TCPMAINT 591 minidisk. Consult the z/VM: TCP/IP Programmer's Reference for details about PMEXIT parameter list and parameter descriptions.

TN3270ENOSCEXIT
Prevents the Telnet server from calling the session connection exit for telnet printer sessions only. Otherwise, the session connection exit will be called, if it is loaded, for all telnet sessions.
TRANSFORM
Causes the Telnet server to load a 3270 transform program. File TNSIMHPI TEXT must be accessible by the server, and additional virtual storage might be needed. This file is available only with third-party products; it is not supplied with TCP/IP for VM. The TRANSFORM parameter is ignored if it is supplied via the OBEYFILE command.

Examples

The following example shows that TNEXIT1 TEXT is to be loaded and used as the Telnet session connection exit. 
InternalClientParms
   ConnectExit TNEXIT1
EndInternalClientParms

Usage Notes

  • If a parameter name is misspelled or if the value specified is not valid, the parameter is ignored and the default is used.
  • When using the OBEYFILE command to modify the INTERNALCLIENTPARMS statement, keep these rules in mind:
    • The values of all parameters except CONNECTEXIT, PORT, TN3270EEXIT, and TRANSFORM may be changed.
    • A change to any read-only disk will cause the CONNECTEXIT and TN3270EEXIT interface to be reloaded during Obeyfile processing for INTERNALCLIENTPARMS.
    • An INTERNALCLIENTPARMS parameter that may be changed but is not specified assumes its default value or setting.
  • Communication with SNA/CCS terminals must be enabled in order for the Telnet server to support line-mode Telnet sessions. This can be accomplished by adding the CP ENABLE SNA command to a server profile exit or the global profile exit, TCPRUNXT. For more information, see General TCP/IP Server Configuration.
  • To disable line-mode Telnet support, ensure that the *CCS operand is not specified for any IUCV statements that are included in the TCP/IP server CP directory entry. Also, ensure that the CP ENABLE SNA command is not employed as previously described.
  • Prior to customizing the telnet exits described in this section (CONNECTEXIT and TN3270EXIT), ensure that you have reviewed the exit limitations and customization recommendations presented in Customizing Server-specific Exits.
  • The CLIENTCERTCHECK, SECURECONNECTION, and TLSLABEL options can be modified by an INTERNALCLIENTPARMS statement using the NETSTAT OBEY or OBEYFILE command.
  • When the SECURECONNECTION operand is omitted or is set to NEVER, the CLIENTCERTCHECK operand is not valid. The CLIENTCERTCHECK value will be set to NONE (the default).

More Information