IBM

TCP/IP
Logging on to a
remote computer (Telnet)

XXXX-0000-00

IBM
TCP/IP
Logging on to a
remote computer (Telnet)

XXXX-0000-00

 Copyright International Business Machines Corporation 1998, 1999. All rights reserved.
US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.

Contents
Chapter 1. Getting started with Telnet

Chapter 2. Starting a Telnet client

session . . . . . . . . . . . . . .

Telnet server functions from your AS/400 client

session . . . . . . . . . . . . . .

Chapter 3. Planning for the Telnet

server . . . . . . . . . . . . . . .

Automatically configuring virtual devices with

Telnet. . . . . . . . . . . . . . .
Telnet naming conventions for automatically
configured devices . . . . . . . . . .
Creating your own virtual devices . . . . .

.
.

5
6

| Chapter 4. Telnet server and Secure

| Sockets Layer (SSL). . . . . . . . .
| Restricting Telnet ports . . . . . . . . . .

Chapter 5. Starting the Telnet server

Activating the QSYSWRK subsystem .

Ending your Telnet server session . .

.
.

.
.

.
.

.
.

9
9

Setting the number of virtual devices to control

sign-on . . . . . . . . . . . . . .
Creating Telnet user profiles . . . . . . .
Assigning devices to subsystems. . . . . .
Restricting privileged users to specific devices
Setting the session keep alive timeout value
Using the inactive message queue . . . .

.
.
.

11
11
12
12
12
12

| Chapter 7. Sample Telnet exit program

| files . . . . . . . . . . . . . . . . 15

Chapter 8. Telnet pass-through to

multiple systems . . . . . . . . . . 17
System request options for cascaded Telnet . . .
SIGNOFF command to return to server system

| Chapter 9. Troubleshooting Telnet.

| Troubleshooting your Telnet SSL server . .
Checking system status for Telnet SSL . .
|
Checking for an active SSL listener . . .
|
Checking Telnet job log . . . . . . .
|
SSL return codes . . . . . . . . .
|
Common Telnet SSL problems . . . .
|

17
18

. . 19
.
.
.
.
.
.

.
.
.
.
.
.

19
19
20
20
21
23

Chapter 6. Controlling user access to

AS/400 via Telnet . . . . . . . . . . 11

Copyright IBM Corp. 1998, 1999

iii

iv

TCP/IP Logging on to a remote computer (Telnet)

Chapter 1. Getting started with Telnet

Telnet allows you to log on to a remote computer and use it as though you are
connected directly to it within the local network. The machine, or system, that you
are physically in front of is the client. The Telnet server is the remote computer to
which the client is attached. AS/400 TCP/IP supports both the Telnet client and
server.
One of the most important features of Telnet is its ability to negotiate options
between the client and the server. This type of open negotiation makes it possible
for either, the client or the server, to initiate a request or to honor a request.
In addition to supporting virtual display sessions, the AS/400 Telnet server also
supports a virtual printer client.
Several different emulation types, or modes, are available to you for negotiating
requests and converting them to output. For the AS/400, the preferred type is 5250
emulation. The Telnet client and server topics contained in these articles focus
solely on tasks relative to the 5250 full-screen mode.
AS/400 can also support 3270 type terminals, VTxxx terminals, and printer
pass-through mode. For information on AS/400 Telnet support of non-5250
terminal types, see the Telnet client and server chapters in the OS/400 TCP/IP
Configuration and Reference.
To help you establish a Telnet client session, see:
v Chapter 2. Starting a Telnet client session on page 3
From the client session, you will see an AS/400 command line. You can enter
commands that will enable you to run programs, change configurations, or access
other server applications. To view a list of the commands that you can work with
from a client session, review the topic:
v Telnet server functions from your AS/400 client session on page 4
Starting a Telnet server job requires that you, first, determine the number of virtual
devices to associate with the workstations that are connected to your system. You
can find more information about configuring virtual devices in the topic:
v Chapter 3. Planning for the Telnet server on page 5
The AS/400 Telnet application can be configured with a digital certificate for the
purpose of data encryption. The steps in this procedure will enable your Telnet
server to operate with both SSL and non-SSL clients:
v Chapter 4. Telnet server and Secure Sockets Layer (SSL) on page 7
For procedures on how to get your Telnet server up and running, see:
v Chapter 5. Starting the Telnet server on page 9
Controlling user sign-on is an important aspect of basic Telnet security. You can
find more information about securing devices, and examples for creating your own
Telnet exit programs, in these topics:
v Chapter 6. Controlling user access to AS/400 via Telnet on page 11
Copyright IBM Corp. 1998, 1999

v Chapter 7. Sample Telnet exit program files on page 15

Moving between systems to establish Telnet sessions and jobs is possible with
cascaded Telnet sessions. To learn more about performing this action and its
associated options, read this topic:
v Chapter 8. Telnet pass-through to multiple systems on page 17
When things go wrong and you have problems with the Telnet server, see:

|
|

v Chapter 9. Troubleshooting Telnet on page 19

TCP/IP Logging on to a remote computer (Telnet)

Chapter 2. Starting a Telnet client session

You will need to complete these steps before you establish your Telnet client
session:
1. The Telnet server must be available and configured on the remote system (the
server system that you want to connect to using Telnet).
2. (Optional) Set the AS/400 server to automatically configure virtual controllers
and devices.
The Work with Subsystem (WRKSBS) command shows the status of the
subsystem and the jobs that are active. The jobs that must be active are the
QTVTELNET and QTVDEVICE jobs in the QSYSWRK subsystem.
3. Check to see that the QAUTOVRT system value is equal to the maximum
number of users that are signed on, using automatically configured virtual
devices, at any one time. QAUTOVRT supports numeric values of 0 through
32500, and a special value of *NOMAX.
4. You should know the name or internet address of the remote system with
which you want to start the Telnet session.
5. Type option 10 (Work with TCP/IP host table entries) from the Configure
TCP/IP menu to display the internet addresses and host names.
To start a Telnet client session, perform these steps:
1. Type the STRTCPTELN command, or type TELNET at the command line.
Type the name of the remote system, or type *INTNETADR if you prefer to use
the internet address.
2. Press Enter.
If you typed *INTNETADR for the Remote system field, the system prompts
you for the Internet address field.
3. Type the internet address of the remote system and then press Enter. The
display shows optional parameter values and the internet address information.
4. To use the default parameter values, press Enter. The next display is the
sign-on display for the remote system.
v To specify connection parameters for 3270 and VTxxx connections, press F10
Additional Parameters.
Note:
1. If you are starting Telnet from a device that is remotely attached to the
AS/400 system, you must use the keyboard language type (KBDTYPE)
parameter on the STRTCPTELN command for the keyboard you are
using. This parameter is used only for 3270 and 5250 full-screen modes.
2. If a SOCKS server is not configured or not found, or if errors occur using
the SOCKS server, then a direct connection is established.
To control server functions while you are in a client session, see the topic:
v Telnet server functions from your AS/400 client session on page 4

Copyright IBM Corp. 1998, 1999

Telnet server functions from your AS/400 client session

AS/400 Telnet client has control functions that allow you to control workstation
processing on the server system when you are in a client session. The Telnet
control functions allow you to invoke client to server commands that can affect the
already established session.
Both the AS/400 name and the TCP/IP name is listed for each of the command
functions.
To select which server functions that you want to control:
1. Access the Telnet Control Functions menu.
2. To get to this menu, press the Attention key on your 5250 keyboard.
The following list provides you with a brief description of each of the Telnet Client
Control Functions:
v Interrupting a process on the server system:
Interrupt process or IP: Cancels, interrupts, or suspends a process that has
started on the server. For example, you can use IP when a process appears to be
in a permanent loop, or if you have started a process by accident.
v Querying connection status when the server system becomes inactive:
Query connection status or AYT: Provides a message from the server that lets
you know that the server system is still running. You can use this control
function when the server system is unexpectedly inactive for a long period of
time.
v Discarding remote output before it reaches your workstation:
Discard remote output data or AO: Allows a process that is generating output
to run to completion without sending the output to your workstation. This
function removes server-system output already produced but not yet displayed
on your workstation.
v Clearing the data path between your system and the server system:
Clear the data path or SYNCH: Discards all characters (except Telnet
commands) between your system and the server system. You can use this
function when the networks flow control mechanisms cause other functions,
such as IP or AO, to be buffered.
v Ending the Telnet session:
End Telnet session or QUIT: Ends the Telnet session and closes the TCP/IP
connection to the server system (remote system). You can request this function
any time during the Telnet session, but you should sign off the remote system
before selecting this function. If you do not sign off, you remain signed on to the
server system because the Telnet protocol does not provide an end session
sequence.
v Using the Attention key to remote host option:
Attn key to remote host: Press the Attention key to display the Telnet control
functions menu.

TCP/IP Logging on to a remote computer (Telnet)

Chapter 3. Planning for the Telnet server

Telnet uses virtual device descriptions to maintain client workstation information
for open Telnet sessions. A virtual device is a device description that is used to form
a connection between a user and a physical workstation attached to a remote
system. Virtual devices provide information about your physical device (display or
printer) to the programs on the server. If a virtual device is not specified in the
attaching client/server protocol, and it is not designated by a registered exit
program, then it attempts to match a virtual device description with a device type
and model similar to the device on your local system.
Before starting a Telnet session from a client, the Telnet server must associate a
device description with that session. AS/400 Telnet automatically configures virtual
devices for you, if you choose.
Review Telnet naming conventions for automatically configured devices for tips
on naming conventions.
You also have the option of creating your own virtual device under the
QVIRCDnnnn virtual controller.

Automatically configuring virtual devices with Telnet

The option is available to allow the Telnet server to automatically configure your
virtual devices and controllers, using the QAUTOVRT system value. This value
specifies the maximum number of devices that are automatically configured by the
system. Each device is configured or created one device at a time, on an as needed
basis, up to a specified limit.
You can change the number of devices that are automatically started by using the
Change System Value (CHGSYSVAL) command. For example, entering the
following string changes the number of virtual devices that can be allocated on a
system to 50:
CHGSYSVAL SYSVAL(QAUTOVRT) VALUE(50)

Note: QAUTOVRT is able to support numeric values of 0 through 32500, and a

special value of *NOMAX.
When automatically configuring virtual devices with Telnet, the Telnet server does
not delete virtual devices and does not delete the devices when the session is
closed. The devices are not deleted even if the number of devices attached to the
virtual controllers exceeds the QAUTOVRT limit. If the devices already exist on the
virtual controller, they can be used by the Telnet server.

Telnet naming conventions for automatically configured devices

The Telnet server uses the following conventions for naming automatically created
virtual controllers and devices:
v Virtual controllers are named QPACTLnn
v Virtual devices are named QPADEVxxxx
Copyright IBM Corp. 1998, 1999

All virtual devices that are created under QPACTLnn controllers and
QVIRCDnnnn controllers count toward the QAUTOVRT limit.
The Telnet server reuses available existing virtual devices that were auto-created by
selecting virtual devices of the same device type and model. When there are no
more device type and model matches, but there are still available virtual devices,
then the device type and model will be changed to match the client device and
model negotiated. This is true only for auto-created (QPADEVnnn) virtual devices.
If you choose to manually create your own devices, you should establish naming
conventions that will allow you to easily manage your configuration. You can
select whatever device names and controller names that you want, provided the
names conform to the OS/400 object naming rules.

Creating your own virtual devices

You can create virtual controllers and devices. If you create your own virtual
devices, by allowing the system to automatically select the device name, you must
be aware of the following:
v The virtual controller must be named QPACTLnn, where nn is a decimal number
01 or greater.
v The virtual device should be named QPADEVxxxx, where xxxx is an alphanumeric
character from 0001 to ZZZZ. The virtual device should be type *VRT and found
under a virtual controller.
Note: If you want to use more than 32500 devices, the maximum for
QAUTOVRT, you can set the QAUTOVRT system value to *NOMAX to
allow additional devices to be created.
If you choose to create your own devices, you should be familiar with the naming
conventions used by the Telnet server.

TCP/IP Logging on to a remote computer (Telnet)

Chapter 4. Telnet server and Secure Sockets Layer (SSL)

|
|
|
|
|
|

The TCP/IP Telnet server supports the use of Secure Sockets Layer (SSL) for
SSL-enabled Telnet clients. SSL uses a private key/public key pair to encrypt data
and transfer documents over the Internet. The private key is used to decode, or
decrypt, the digital certificate that is attached to the document. A digital certificate
allows you to use SSL for secure browser access to web sites and other Internet
services.

|
|
|

When a digital certificate is configured for the Telnet server, the server can handle
SSL and non-SSL clients. All data from the Telnet SSL client is decrypted by the
Telnet SSL server.

|
|
|
|
|

The AS/400 Telnet server supports non-SSL Telnet sessions in 5250, 3270, VT100,
and Printer pass-through emulation. When there is no need for you to use the
Telnet SSL server, you can turn off the SSL port by adding port restrictions. Then,
the Telnet server runs in non-SSL mode only, even if the Telnet server was
previously configured with a certificate.

|
|
|
|

The most important factor to consider when using the Telnet SSL server is the
sensitivity of the information that is used in a client session. If the information is
sensitive, or private, then you may find it beneficial to set up your AS/400 Telnet
server using SSL.

|
|
|
|
|
|

To get started with Telnet SSL, follow these steps:

1. Install the following software to support Telnet SSL and manage digital
certificates:
v Digital Certificate Manager, 5769-SS1 - Boss Option 34. For help with this
installation, reviewGetting started with IBM Digital Certificate Manager.
v Cryptographic Access Provider, 5769-ACx
v IBM HTTP Server for AS/400, 5769-DG1
2. Establish secure Telnet connections by configuring a system certificate for the
Telnet server application QIBM_QTV_TELNET_SERVER.
3. Start the Telnet server.

|
|
|
|
|
|
|
|
|
|
|

Review these topics for additional information:

v Securing applications with SSL provides information to help you configure your
AS/400 applications to use SSL.
v Restricting Telnet ports on page 8 explains how to allow or disallow SSL client
sessions at the Telnet server.
v Troubleshooting your Telnet SSL server on page 19 suggests ways to solve SSL
problems related to the Telnet server.

Copyright IBM Corp. 1998, 1999

|
|

Restricting Telnet ports

|
|
|
|
|

The Telnet server can operate with both SSL and non-SSL clients once the digital
certificate is configured. However, you can control the type of client sessions to
accept at the server by restricting Telnet ports. You can restrict the non-encrypted
Telnet port to run Telnet SSL only or you can restrict the SSL port to run
traditional Telnet only.

|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

To add a port restriction

1. Use the CRTUSRPRF command at the AS/400 command line to create a user
profile.
Example:
CRTUSRPRF USRPRF(TLNR)
TEXT('Restrict SSL or non-SSL telnet server access')
MAXSTF(3)

2. Type ADDTCPPORT at the command line and use the PORT, PROTOCOL, and
USRPRF parameters.
v In the PORT parameter, enter the number of the port you want to restrict.
To run Telnet SSL only, use the non-encrypted Telnet port, which is
usually port 23.
To run non-SSL Telnet only, use the Telnet SSL port, which is usually port
992.
To identify the port number used on your machine, check the services
table for the telnet and telnet-ssl labels.
Example:

|
|
|
|

ADDTCPPORT PORT(23) PROTOCOL(*TCP) USRPRF(TLNR)

or
ADDTCPPORT PORT(992) PROTOCOL(*TCP) USRPRF(TLNR)

To remove a port restriction

1. Type RMVTCPPORT at the command line and use the PORT, PROTOCOL, and
USRPRF parameters to restrict the SSL port.
v In the PORT parameter, enter the port number of the SSL or non-SSL port
that you previously restricted with the ADDTCPPORT command.

|
|
|
|
|

Example:

|
|
|
|

RMVTCPPORT PORT(992) PROTOCOL(*TCP) USRPRF(TLNR)

or
RMVTCPPORT PORT(23) PROTOCOL(*TCP) USRPRF(TLNR)

TCP/IP Logging on to a remote computer (Telnet)

Chapter 5. Starting the Telnet server

The active Telnet server has one or more instances of each of these jobs running in
the QSYSWRK subsystem: QTVTELNET and QTVDEVICE.
1. (Optional) Type CFGTCPTELN at the AS/400 command line to set up your
5250 full-screen mode session.
v This command displays the Configure TCP/IP Telnet menu. From there, you
can select and change Telnet attributes for Telnet 5250 full-screen mode.
v 5250 full-screen support can only be negotiated with a Telnet client
application on an AS/400, or another system that supports the Telnet 5250
client.
2. Type STRTCPSVR *TELNET at the AS/400 command line to start the Telnet
server.
|

To start the Telnet server with Operations Navigator, follow these steps:

|
|

1. In Operations Navigator, expand your AS/400 server.

2. Expand Network, then expand Servers.

|
|
|
|

3.
4.
5.
6.

For information on signing off, see Ending your Telnet server session.

Click TCP/IP.
Find Telnet in the Server Name column.
Confirm that Started appears in the Status column.
If the server is stopped, right-click Telnet, then select Start.

Activating the QSYSWRK subsystem

The server job for a TCP/IP application must be started in the QSYSWRK
subsystem. The spooling subsystem, QSPL, needs to be active to run pass-through
sessions. To activate and display the status of the QSYSWRK subsystem:
1. Use the WRKSBS (Work with Subsystem) command.
2. Make certain that the Telnet server is also started.
3. Start the interactive subsystem, QINTER to run interactive jobs for Telnet
sessions.

Ending your Telnet server session

When you are connected to an AS/400 server, signing off does not necessarily end
your Telnet server session. To end the session, you must enter a key or sequence of
keys to put the Telnet client into a local command mode. You can then type the
command to end the session. For example, this table provides you with key
sequences for ending a Telnet server session:
Table 1. Ending a Telnet server session
Ending Session From

How to End Session

AS/400 system

Press the Attention key and then select option 99

(End TELNET session - QUIT)

Many others

Press Ctrl-] and type QUIT

Copyright IBM Corp. 1998, 1999

If you do not know what key or key sequence to press to cause the client to enter
command mode, consult either your system administrator or your Telnet client
documentation.
You can also use the end connection (ENDCNN) parameter of the SIGNOFF
command to sign off the server system and end the Telnet connection. For
example, SIGNOFF ENDCNN(*YES) returns you to the client system (if you only have
one Telnet session established) or returns you to the previous system (if you have
more than one Telnet session established).

10

TCP/IP Logging on to a remote computer (Telnet)

Chapter 6. Controlling user access to AS/400 via Telnet

When you invoke Telnet across a TCP connection, you need to consider security
measures that prevent or allow user access to the AS/400 via Telnet. For example,
it is important that you set limits and controls on the number of sign-on attempts,
and the number of devices that a user can sign on to.
For procedural information about controlling user access to Telnet, review these
topics:
v Setting the number of virtual devices to control sign-on
v Creating Telnet user profiles
v Assigning devices to subsystems on page 12
v Restricting privileged users to specific devices on page 12

Setting the number of virtual devices to control sign-on

The number of Telnet sign-on attempts allowed increases if you have virtual
devices automatically configured. The number of virtual devices that can be
created is defined by the QAUTOVRT system value. The number of system sign-on
attempts allowed is defined by the QMAXSIGN system value.
To determine and set the maximum number of users signed on to the AS/400
system at any time, do the following:
1. Set the QAUTOVRT value to 32500, the maximum value that is allowed, or use
the *NOMAX value.
2. Let your users use Telnet until you decide that the number of virtual devices
created is sufficient for normal system operation.
3. Change the QAUTOVRT value from 32500 to the number of virtual devices you
require for normal system operation.
User-supplied exit programs offer the following support with regard to the security
of virtual devices:
v Audit the number of sign-on attempts
v Deny connections
v Allow by-passing of the sign-on screen

Creating Telnet user profiles

At the server system, you can create Telnet user profiles with the CRTUSRPRF
command:
Example:
CRTUSRPRF USRPRF(CLERK1)
PASSWORD(unique-password)
JOBD(CLERKLIB/CLERK1)
TEXT('User profile for Clerks Group 1')

Copyright IBM Corp. 1998, 1999

11

Assigning devices to subsystems

Before a user can sign-on to the AS/400 server, the workstation must be defined to
a subsystem. The workstation, for example, would be the virtual display device
that is selected or automatically created by the Telnet server.
The workstation name or the workstation type should be specified in the
subsystem description on the AS/400. Use the Display Subsystem Description
(DSPSBSD) command to see the workstation entries defined to the subsystem.
The following command can be used to add all workstation types to a subsystem
that is named QINTER:
ADDWSE SBSD(QINTER) WRKSTNTYPE(*ALL)

The Add Workstation Entry (ADDWSE) command can be done when the
subsystem is active. However, the changes may or may not take effect immediately.
You may need to end and restart the subsystem.

Restricting privileged users to specific devices

The OS/400 licensed program supports the QLMTSECOFR system value, which
restricts or limits the devices that a user can sign on to. All object authority
(*ALLOBJ), allows the user to access any of the resources on the system. Service
special authority (*SERVICE) allows the user to perform specific service functions
on the system. For example, the user with this type of authority would be able to
debug a program, and perform display and alter service functions.
If the QLMTSECOFR value is greater than zero, the user must be authorized to use
the virtual device descriptions. However, when this value is 0, the system does not
limit the devices that users with *ALLOBJ or *SERVICE can sign on to.
The recommended value is to limit users to one device session. This reduces the
likelihood of sharing passwords and leaving devices unattended.
Review these topics for other ways to restrict users:
v Setting the session keep alive timeout value
v Using the inactive message queue

Setting the session keep alive timeout value

The Telnet session keep alive timeout (QINACTITV) system value specifies the
number of minutes that you want between connection validation. TCP tests each
Telnet connection at the specified time interval. If TCP does not get a response, it
ends the connection.
Note: You must have *ALLOBJ and *SECADM special authority to change the
QINACTITV system value.

Using the inactive message queue

The inactive message queue (QINACTMSGQ) system value specifies the action the
system takes when an interactive job has been inactive for an interval of time. The

12

TCP/IP Logging on to a remote computer (Telnet)

time interval is specified by the system value QINACTITV. The interactive job can
be ended, disconnected, or a message can be sent to the message queue that you
specify.
QINACTMSGQ is a 20-character list of up to two 10-character values where the
first is the message queue name and the second is the library name.
v *DSCJOB: The interactive job is disconnected, as is any secondary or group jobs
associated with it. If *DSCJOB is specified, and the job cannot be disconnected,
*ENDJOB will be used.
v *ENDJOB: The interactive job is ended, along with any secondary job and any
group jobs associated with it. If there are many inactive jobs in a subsystem that
are to be ended at once, the interactive response time of that subsystem may be
slowed.
v inactive-message-queue library: A message indicating the job is inactive is sent
to the specified message queue. If the specified message queue does not exist or
is damaged, the messages are sent to the QSYSOPR message queue.
Note: All messages in the message queue specified by QINACTMSGQ are
cleared during an IPL. If you assign a users message queue to
QINACTMSGQ, the user loses all messages in the users message queue
during each IPL.
Possible library values are:
v *LIBL: Use the library list when locating the inactive message queue.
v library name: The name of the library where the inactive message queue is
located. If no library is specified as the current library for the job, QGPL is used.
A change to this system value takes effect immediately.
Note: You must have *ALLOBJ and *SECADM special authority to change the
QINACTMSGQ system value.

Chapter 6. Controlling user access to AS/400 via Telnet

13

14

TCP/IP Logging on to a remote computer (Telnet)

Chapter 7. Sample Telnet exit program files

|
|
|
|

You can use these samples as a starting point to build your own exit programs, or
lift portions of the code from them to add to programs that you write yourself. The
example programs that are provided here are not recommended for use on a
production system.

|
|
|
|

The ZIP and SAVF contain the same files. The files in telnet42.zip are in a format
that is compatible with PCs. Choose telnet42.zip to download the program and
information files to your PC, unzip them, then transfer them to your AS/400. You
will need to rename most of the files once you get them to your AS/400.

|
|
|
|

Telnet42.savf is an AS/400 save file. Download it to your PC, then transfer it to

your AS/400. It is recommended that you create a temporary library on your
AS/400 and transfer the save file to that. Unpack the save file in the temporary
library and follow the instructions in the READ.ME file.

|
|

To download the files, right-click on a link, then select Save Link As.

v telnet42.zip (187 KB)

v telnet42.savf (835 KB)

Here are descriptions for each Telnet exit program sample:

|
|
|
|

Create Telnet exit program CL utility code (TELCRT)

This is a working example code for the utility program that creates,
installs, and registers Telnet exit programs. It is written in AS/400
Command Language (CL) programming language

|
|
|
|

Delete Telnet exit program CL utility code (TELDLT)

This is a working example of code for the utility program that uninstalls
and deletes Telnet exit programs from your AS/400. It is written in AS/400
CL programming language.

|
|
|
|
|
|
|

Basic Telnet initialization exit program (DEVINIT1)

The basic Telnet initialization exit program (DEVINIT1) lets you screen
Telnet clients. You decide who is allowed to connect to your Telnet server
and who is not. The DEVINIT1 exit program is not designed to take
advantage of the many other functions available to Telnet exit programs.
The DEVINIT2 exit program is designed to take advantage of those
functions.

|
|
|
|
|
|
|
|
|
|

Advanced Telnet initialization exit program (DEVINIT2)

The advanced Telnet initialization (logon) exit program uses the access lists
MAP and DISALLOW. By using the MAP list instead of the simpler
ALLOW list, the advanced initialization program exploits more of the exit
point interface than the basic version. It allows you to set or override
Telnet session settings which is a function you normally see in the Client
Access environments. Here are some examples of the kinds of session
settings:
v Select a particular Virtual Terminal device for this session
v Bypass the sign-on panel
v Set up NLS support, etc.

Copyright IBM Corp. 1998, 1999

15

Telnet termination program (DEVTERM)

DEVTERM QCSRC is a simple logging program which logs a disconnect
message. This is a companion program to both DEVINIT1 QCSRC and
DEVINIT2 QCSRC. The termination messages it logs can be matched up
with the initialization messages to determine Telnet session duration.

|
|
|
|
|

16

TCP/IP Logging on to a remote computer (Telnet)

Chapter 8. Telnet pass-through to multiple systems

You can start a Telnet session while you are currently in a Telnet session, or start a
display station pass-through (DSPT) session while you are in a Telnet session. You
can also start a Telnet session at the same time that you are in a display station
pass-through session. This method for moving back and forth between systems, or
passing through multiple systems, is referred to as cascaded Telnet.
The system where you first use pass-through (DSPT) or Telnet is called the home
system. The home system may be either a Telnet client system or a DSPT source
system. The last Telnet server system, or the last DSPT target system, is called the
end system. The system that you pass-through to get from the home system to the
end system is an intermediate system.
|
|

To start a cascaded Telnet session, type the STRTCPTELN (TELNET) command

from an existing Telnet or DSPT session.

To use cascaded Telnet, see System request options for cascaded Telnet.

System A

System B
Pass-Through
or TELNET

System C
Pass-Through
or TELNET

Home
System

System D
Pass-Through
or TELNET

Intermediate Systems

End
System
RV2P971-1

Figure 1. Cascaded Telnet and Pass-through Home system and End system

System request options for cascaded Telnet

|
|

Once you have started a cascaded Telnet session, press the System Request (Sys
Req) key, then press Enter to display the System Request menu.

|
|
|
|
|
|

The following options are those associated with the cascaded Telnet system:
v Starting a system request at a client system: AS/400 System Request option 10
displays the System Request menu on the previous client system.
v Transferring to the client system: AS/400 System Request option 11 transfers
you to an alternate job on the previous client system.
v Starting a system request at the home system: AS/400 System request option 13
takes you from an intermediate or end system to the System Request menu of
the home system.
v Transferring to the home system: AS/400 System Request option 14 takes you
from an intermediate or end system to the alternate job on the home system.
If you are using a Telnet client session to connect to the original AS/400, the
client PC is treated as the home system for all System Request options. For
options 10 and 11, the client PC is the previous system. For options 13 and 14,
the client PC is the home system.
Copyright IBM Corp. 1998, 1999

17

Use System Request option 11 to move backward from each system until you
reach the first AS/400 that is not the client box. From here you can use System
Request option 1 to move forward, system to system. Although this does not
provide you with a direct path from one system to the first AS/400, it will
enable you to get there using the System Request options.

|
|
|
|
|

To bypass the System Request menu, press the System Request key and type the
number 10 on the command line. This shortcut is applicable between AS/400
systems only.
To sign off your Telnet session, or to end a Telnet connection, see SIGNOFF
command to return to server system.

SIGNOFF command to return to server system

The SIGNOFF command ends the session and returns you to the sign-on display of
the server system. If you are signed on to the server system, the SIGNOFF
command ends the current server job and you are returned to the sign-on display
of the server system.
End Connection Parameter
You can use the end connection (ENDCNN) parameter of the SIGNOFF command
to sign off the server system and end the Telnet connection.

18

TCP/IP Logging on to a remote computer (Telnet)

Chapter 9. Troubleshooting Telnet

|
|
|
|
|

Check this list when looking for information to help with Telnet problems:
v For suggestions on ways to fix problems with Telnet SSL, see the topic
Troubleshooting your Telnet SSL server.
v For operating information on VTxxx and 3270 emulation modes, see the Telnet
Client and Telnet Server chapters in the OS/400 TCP/IP Configuration and

|
|

Reference
.
v For diagnostic information, see the Telnet client and server chapters in the

|
|
|

OS/400 TCP/IP Configuration and Reference

Troubleshooting your Telnet SSL server

|
|

The troubleshooting topics contain information and tips to help solve Telnet SSL
problems.

|
|
|
|
|
|

You can use this general procedure to identify problems:

|
|
|
|

Many problems with SSL can be narrowed down to incorrect digital certificates.
Digital Certificate Manager lets you change your Certificate Authority or system
certificates. To confirm that you have a valid system certificate, read how to start
Digital Certificate Manager, then view the system certificate.

|
|

You can also browse the topic Common Telnet SSL problems on page 23 for
quick descriptions and resolutions.

|
|
|
|
|
|
|
|
|
|
|
|

1. Check your system status to make sure you have the proper software installed
and that the servers are started.
2. Check for an active SSL listener using the NETSTAT *CNN command.
3. Check the job log to find the SSL return code.
4. Look up the SSL return codes for suggestions to solve the problem.

Checking system status for Telnet SSL

To confirm that your Telnet server is ready for SSL sessions, follow these steps:
1. Verify that you have the proper software installed to support Telnet SSL and to
manage certificates:
v TCP/IP Connectivity Utilities for AS/400, 5769-TC1
v Digital Certificate Manager, 5769-SS1 - Boss Option 34
v Cryptographic Access Provider, 5769-ACx
v IBM HTTP Server for AS/400, 5769-DG1
2. Make sure you have a secure Telnet server by associating a certificate with the
Telnet server application QIBM_QTV_TELNET_SERVER.
3. Ping your host system to verify your TCP/IP connection and network status.
4. Check that you have started the Telnet server.

Copyright IBM Corp. 1998, 1999

19

Checking for an active SSL listener

|
|
|
|
|
|
|
|
|
|

The Telnet server must be active and ready to receive connection attempts. To
check for an active SSL listener, follow these steps:
1. At the AS/400 command line, type NETSTAT *CNN to show the Work with
TCP/IP Connection Status display.
2. In the Local Port column, find the telnet- label for telnet-ssl. You will see only
telnet- because the field is not long enough on the display.

|
|

SSL initialization has failed if you dont find telnet-ssl in the Local Port column.
For help fixing the problem, you have to check the job log for the SSL return code.

v Use the F22 key to display the entire Local Port field.
v Use the F14 key to see the port numbers. The telnet-ssl entry will be port
992.

Checking Telnet job log

|
|
|
|

When SSL initialization and handshake fails, the Telnet server sends TCP255x
messages to the QTVTELNET job. The SSL return code is a negative number, such
as -2 or -93, for an unsuccessful SSL initialization or an SSL handshake.

|
|
|
|

To
1.
2.
3.

|
|
|

4. Select Job Log.

5. Look for the TCP255x message in the Message ID column. The text in the
Message column contains the SSL return code.

Here are some things to remember about the Telnet server jobs:
v Only one QTVTELNET job starts when the SSL listener fails to initialize.

|
|
|
|
|
|
|
|

check the Telnet server job log, do these steps:

In Operations Navigator, expand your AS/400 server.
Expand Job Management, then click Server Jobs.
Right-click QTVTELNET in the Job name column.

v QTVDEVICE and QTVTELNET jobs start when Telnet server starts after a
system IPL or reboot.
v The same number of QTVTELNET and QTVDEVICE jobs are started when the
Telnet server starts an SSL listener.
v QTVTELNET jobs are ended with the ENDTCPSVR *TELNET or ENDTCP
command.
v QTVDEVICE jobs are ended when the QSYSWRK subsystem is ended.

SSL initialization and handshake

|
|

Sometimes understanding what goes on during SSL processing can help you figure
out where a problem might have occurred.

What happens during SSL initialization

|
|
|
|
|
|

The Telnet server attempts to initialize SSL every time the server is started. During
initialization, the Telnet server checks the certificate information in the
QIBM_QTV_TELNET_SERVER application. You can tell the SSL initilization is
successful when more than one active QTVTELNET job appears in the job log. Of
course, if the CHGTELNA NBRSVR parameter is set to 1, youll only see one active
QTVTELNET job.

20

TCP/IP Logging on to a remote computer (Telnet)

|
|
|
|
|

The Telnet server does not initialize SSL when you have a restricted telnet-ssl port.
The Telnet server sends the TCP2550 message Access to port 992 is restricted to
the QTVTELNET job log and the QSYSOPER message queue. The topic
Restricting Telnet ports on page 8 describes how to add or remove port
restrictions.

|
|

When a certificate is incorrect or expired, initialization fails and the Telnet server
sends TCP2553 messages to the QTVTELNET job log.

|
|
|
|

Even if there is no certificate in the QIBM_QTV_TELNET_SERVER application, the

Telnet server successfully initializes SSL. However, the SSL handshake fails when
the client tries to connect to the Telnet server. The Telnet server sends TCP2554
messages to the QTVTELNET job log.

What happens during SSL re-initialization

|
|
|
|
|
|

When the certificate in the QIBM_QTV_TELNET_SERVER application is changed,

the Telnet server re-initializes SSL the next time a client attempts to establish an
SSL session. The process is the same as SSL initialization. New Telnet SSL client
sessions use the new certificate. Telnet SSL client sessions that are already
established use the original certificate. Once the Telnet server is ended and started
again, all Telnet SSL client sessions use the new certificate.

|
|
|
|

If the SSL re-initialization fails, new and established SSL sessions will use the
original certificate that was initialized when the server started. The Telnet server
sends TCP2553 messages to the QTVTELNET job log. The next time you start the
Telnet server, SSL initialization fails with no active SSL listener.

What happens during SSL handshake

|
|
|
|
|
|
|
|

An SSL handshake occurs when the Telnet SSL client connects to TCP port 992 and
attempts an SSL negotiation with the server. While the client is connecting to the
server, it displays status numbers or messages on the status bar of the open
window. If the SSL handshake fails, the Telnet session is not established. For
example, a sign-on screen doesnt appear in the Telnet SSL client window. Consult
the user guide or online help for your Telnet SSL client for information on specific
status numbers or messages. The Telnet server sends TCP2554 messages to the
QTVTELNET job log.

SSL return codes

|
|

The SSL return code table shows the most common problems that can occur during
SSL initialization or SSL handshake.

|
|
|
|
|
|
|

Before using the return code table, review these notes:

v You need to find the SSL return code in the QTVTELNET job log.
v In some cases, you will have to use Digital Certificate Manager to correct
problems with Certificate Authority (CA) certificates or system certificates.
v When copying CA certificate information for your Telnet SSL client, remember to
copy the lines that include the words BEGIN CERTIFICATE and END
CERTIFICATE.

Chapter 9. Troubleshooting Telnet

21

|
|
|
|

v Occasionally, you may find return codes in the job log that do not appear in the
return code table. You have probably encountered a problem that doesnt
happen often. Check SSL return codes (Part 2) for suggestions to solve these
problems.

||
|

Return
Code

Description

Action

|
|
|
|

-2

No system certificate is available for

SSL processing

Create a new system certificate for the

QIBM_QTV_TELNET_SERVER
application. For instructions, see
Working with system certificates.

|
|
|
|
|

-4

The CA certificate or system certificate If you are using Client Access Express as
is bad
your Telnet SSL client, see Adding CA
certificates to the Client Access Express
key database. Or, see Installing a CA
certificate on a PC for instructions.

|
|
|
|
|

-16

The peer system is not recognized

If you are using Client Access Express as

your Telnet SSL client, see Adding CA
certificates to the Client Access Express
key database. Or, see Installing a CA
certificate on a PC for instructions.

|
|
|

-18

The system certificate is self-signed

and server is using it as a CA
certificate

Create a CA certificate and associate it to

the system certificate. For instructions,
see Selecting Certificate Authority tasks.

|
|
|

-23

The system certificate is not signed by Change the CA certificate to Trusted. For
a trusted certificate authority
instructions, see Working with secure
applications.

|
|
|
|

-24

The valid time period of the CA

certificate has expired

Renew the CA certificate used to build

the system certificate. For instructions,
see Completing the Renew a Certificate
Authority.

|
|
|
|

-93

SSL is not available for use

Install software requirements to support

Telnet SSL and to manage certificates.
For instructions, see Checking system
status for Telnet SSL.

SSL return codes (Part 2)

|
|
|
|
|
|
|

For the SSL return codes in this table, use Digital Certificate Manager to verify that
the digital certificates meet these requirements:
v The CA certificate is valid and not expired.
v The Telnet server application QIBM_QTV_TELNET_SERVER has a value of Yes
in the Certificate Assigned column.

|
|

v The system certificate is being used within the timeframe stated on the
certificate.

||
|

Return
Code

Description

-1

No ciphers are available or specified

-6

OS/400 does not support the certificate type

v The system certificate is signed by a certificate authority.

v The system certificate is trusted.

22

TCP/IP Logging on to a remote computer (Telnet)

|
|

-10

An error occurred in SSL processing. In the job log, check the CPExxxx
message where xxxx is the errno value.

-11

SSL received a badly formatted message

-12

A bad message authentication code was received

-13

Operation is not supported by SSL

-14

The certificate signature is not valid

-15

The certificate is bad

-17

Permission was denied to access object

-20

Unable to allocate storage required for SSL processing

-21

SSL detected a bad state in the SSL session

-22

The socket used by the SSL connection has been closed

-25

The date in the certificate is in a bad format

-26

The key length is bad for export

-90

Not a keyring file

-91

The password in the key database has expired

-92

Certificate is not valid or was rejected by the exit program

-94

SSL_Init() was not previously invoked for the job

-95

There is no keyring for SSL initialization

-96

SSL is not enabled

-97

The specified cipher suite is not valid

-98

The SSL session ended

-99

An unknown or unexpected error occurred during SSL processing

-1010

Double encryption is not allowed when using AC2 and IP-SEC

Common Telnet SSL problems

|
|

The most common Telnet SSL problems are listed here. Select a topic to read about
symptoms, causes, and solutions for each problem.

|
|
|

If you do not know the SSL return code you received, check the Telnet job log for
TCP255x messages.
v SSL is not available (return code -93)
v System certificate is not correct (return code -18 or -23)
v System certificate does not exist for the Telnet server (return code -2)

|
|
|
|
|
|
|

v System certificate did not match the name known to client (return code -16)
v System certificate has expired (return code -24)
v System certificate is not valid (return code -2 or -4)
v Server is not listening on the specified port
v Server did not respond in time

SSL is not available

|
|
|

Telnet SSL clients cannot connect to host because there is no active SSL listener. A
TCP2553 message appears in the QTVTELNET job log with return code -93. Check
the software requirements and system status for Telnet SSL.

Chapter 9. Troubleshooting Telnet

23

System certificate is not correct

|
|
|
|
|
|
|
|
|
|
|

The system certificate assigned to the QIBM_QTV_TELNET_SERVER application

must be trusted, signed by a certificate authority, and used within the valid time
period. The Telnet server does not initialize SSL if the system certificate is
incorrect. A TCP2553 message appears in the QTVTELNET job log with return
code -18 or -23.
v If the SSL return code is -18, the system certificate is self-signed and server is
using it as a CA certificate. You need to create a CA certificate and associate it to
the system certificate. See Selecting Certificate Authority tasks for instructions.
v If the SSL return code is -23, the system certificate is not signed by a trusted
certificate authority. You need to change the CA certificate to trusted. See
Working with secure applications for instructions.

System certificate does not exist for the Telnet server

|
|
|
|

The Telnet server successfully initializes SSL, but the SSL handshake fails. There is
no sign-on panel in the SSL Telnet client window. A TCP2553 message appears in
the QTVTELNET job log with return code -2. The QIBM_QTV_TELNET_SERVER
application does not have an assigned system certificate.

|
|
|
|

View the system certificate and check that the value Yes shows in the Certificate
assigned column. If the value is No, you need to create a system certificate for the
QIBM_QTV_TELNET_SERVER application. See Working with system certificates
for instructions.

System certificate did not match the name known to client

|
|
|
|
|
|
|

This problem is the most common problem when a Telnet SSL client first attempts
to establish an SSL session. There is no sign-on panel in the Telnet SSL client
window. A TCP2554 message appears in the QTVTELNET job log with return code
-16. You need to add Certificate Authority (CA) certificate information in your
Telnet SSL client. If you are using Client Access Express as your Telnet SSL client,
see Adding CA certificates to the Client Access Express key database. Otherwise,
see Installing a CA certificate on a PC for more information.

System certificate has expired

|
|
|
|
|

You are using an out-of-date certificate. There is no sign-on panel in the Telnet SSL
client window. A TCP2553 message appears in the QTVTELNET job log with
return code -24. You need to renew the CA certificate that was used to build the
system certificate. See Completing the Renew a Certificate Authority form for
instructions.

System certificate is not valid

|
|
|
|
|
|
|

The system certificate is not private or trusted. The Private Key and Trusted fields
on the serve certificate are not correct. There is no sign-on panel in the Telnet SSL
client window. A TCP2554 message appears in the QTVTELNET job log with
return code -4. You need to add Certificate Authority (CA) certificate information
in your Telnet SSL client. If you are using Client Access Express as your Telnet SSL
client, see Adding CA certificates to the Client Access Express key database.
Otherwise, see Installing a CA certificate on a PC for more information.

Server is not listening on the specified port

There is no sign-on panel in the Telnet SSL client window.

24

TCP/IP Logging on to a remote computer (Telnet)

|
|
|
|
|
|

1. Check for an active SSL listener by using the NETSTAT *CNN command. You
may not have an SSL listener for these reasons:
v There is a port restriction on the Telnet SSL port. You will see the TCP2550
message in the QTVTELNET job log.
v SSL did not initialize successfully. You will see the TCP2553 message in the
QTVTELNET job log.

|
|
|

2. From the Telnet SSL client, check that the port and the host name are correct
for the Telnet SSL server. Telnet SSL is assigned to port 992 by default.
3. End and start the Telnet SSL server to get an active SSL listener.

Server did not respond in time

Check that the network is operating correctly. For information in this area, see the

|
|

OS/400 TCP/IP Configuration and Reference

book.

Chapter 9. Troubleshooting Telnet

25

26

TCP/IP Logging on to a remote computer (Telnet)

IBMR

Printed in U.S.A.

XXXX-0000-00