TRCTCPAPP (Trace TCP/IP Application)

TRCTCPAPP syntax diagram

 

Purpose

The Trace TCP/IP Application (TRCTCPAPP) command is used by service personnel when trace information needs to be collected for one of the following TCP/IP applications:

• FTP - Internal trace information can be collected for the FTP server. The information that can be collected for the FTP server may be filtered using remote network address or user profile.
  
• SMTP - Internal trace information can be collected for inbound or outbound connections. For inbound connections (*SMTPSVR) the trace information can also be filtered by remote network address or recipient mail address. For outbound connections (*SMTPCLT) the trace information can be filtered by recipient host name, recipient mail address or domain name service.
  
• TELNET and VTAPI - Telnet provides these qualifiers to help filter the collected information:

  • Remote network address
  • Local network address
  • Device description
  • Device types
  • Trace points

  
  

• Host Servers - Service personnel can collect trace information for several of the Client Access host servers: *CENTRAL, *DTAQ, *RMTCMD, *SIGNON, *NETPRT and *SVRMAP.

  Trace information can also be collected for the database host server (*DATABASE). > The information that can be collected for these servers may be filtered using remote network address, local network address and trace points.
  

• DDM - Service personnel can collect trace information for Distributed Data Management (DDM) running over TCP/IP. The information may be filtered using remote network address, local network address and trace points.
  
• VPN - Service personnel can collect trace information for the Virtual Private Network (VPN) server. The information that can be collected may be filtered using the argument list and VPN server type.
  
• L2TP - Service personnel can collect trace information for Layer Two Tunneling Protocol (L2TP). The information that can be collected for these servers may be filtered using the remote network address.
  
• Certificate Services - Service personnel can collect trace information for the certificate services server. The information that can be collected for this server may be filtered using the certificate services type.
  
• PPP - Service personnel can collect trace information for a Point-to-point connection profile. The information that can be collected for this profile may be selected using the PPP connection profile name

  and the argument list>. The user can specify what additional data (TCPTRCDTA) will be collected when ADLTRC(*TCPIP) is selected.
  

• QOS - Service personnel can collect trace information for the Quality of Service server. The information that can be collected for this server may be filtered using a trace type and an argument list.
  
• SNTP - Service personnel can collect trace information for the Simple Network Time Protocol client.
  
• HTTP - Service personnel can collect trace information for the HTTP server powered by Apache. The information that can be collected may be filtered by selecting an HTTP server instance and trace level.
  
• Directory Services - Service personnel can collect trace information for the directory services server. The information that can be collected may be filtered using an argument list.
  
• Packet Rules - Service personnel can collect trace information for packet rules. The information that can be collected may be filtered using an argument list.

 

Restrictions

1. For a given application, only one trace instance can be active at a time.
   
   
2. This command is shipped with public *EXCLUDE authority.
   
   
3. To use this command, have either *SERVICE special authority or be authorized to the Service Trace function of Operating System/400 through iSeries Navigator's Application Administration support. The Change Function Usage Information (QSYCHFUI) API, with a function ID of QIBM_SERVICE_TRACE, can also be used to change the list of users that are allowed to perform trace operations.
   
   
4. The user must have *USE authority to the line, network interface, or network server to be traced.

 

Required Parameter

APP

Specifies the TCP/IP application.

Parameter	Specifies tracing for...
CENTRAL	central host server.
CERTSRV	services.
DATABASE	database host server.
DDM	Distributed Data Management (DDM) server.
DIRSRV	services.
DTAQ	data queue host server.
FTP	File Transfer Protocol (FTP) server(s).
HTTP	HTTP server powered by Apache.
L2TP	Two Tunneling Protocol (L2TP).
NETPRT	network print host server.
NTP	Simple Network Time Protocol (SNTP) client.
PKTRULES	packet rules.
PPP	Point-to-point protocol (PPP).
QOS	Quality of Service (QOS) server.
RMTCMD	remote command host server.
SIGNON	signon host server.
SMTPCLT	SMTP client job(s) handling outbound mail processing connections.
SMTPSVR	Simple Mail Transfer Protocol (SMTP) server job(s) handling inbound mail processing connections.
SVRMAP	port mapper host server.
TELNET	TELNET server.
VPN	Virtual Private Network (VPN) server.
VTAPI	virtual terminal application programming interfaces.

Optional Parameters

SET

Specifies whether the collection of trace information starts, stops, or status is presented.

*ON: The collection of trace information is started.

*OFF: The collection of trace information is stopped, and the trace information is written to spooled printer files of the user. For PPP traces, the trace files are also included in the OUTQ for the designated PPP profile.

*END: Tracing is ended and all trace information is deleted. No trace information output is created.

*CHK: The status of tracing for the specified application is checked. Messages are returned indicating whether or not tracing is active for the specified TCP/IP application, the command parameters specified from the last time that TRCTCPAPP was started for this application, and other information related to the collection of trace information.

MAXSTG

Specifies the maximum amount of storage in kilobytes (K) used for collected trace information. Values can range from 1-16,000.

*APP: Each application type defines a default buffer size.

*FTP - 4096K bytes per job

*SMTPCLT or *SMTPSVR - 4096K bytes per job

*TELNET or *VTAPI - 16,000K bytes per job

Host Servers - 16,000K bytes per job

*DDM - 16,000K bytes per job

*VPN - 16,000K bytes per job

*PKTRULES - 16,000K bytes per job

*L2TP - 4096K bytes per job

*CERTSRV - 16,000K bytes per job

*PPP - 4096K bytes per job.

*QOS - 4096K bytes per job

*NTP - 4096K bytes per job

*HTTP - 16,000K bytes per job

*DIRSRV - 300K bytes per job

maximum-K-bytes: Specify the maximum amount of storage, in K-bytes, used to store trace records (one K equals 1024 bytes).

TRCFULL

Specifies whether the trace records wrap (replace oldest records with new records) or whether the trace stops when all of the storage specified by the MAXSTG parameter has been used.

*WRAP: When the trace buffer is full, the trace wraps to the beginning. The oldest trace records are written over by new ones as they are collected.

*STOPTRC: Tracing stops when the trace buffer is full of trace records.

ADLTRC

Specifies additional trace(s) to be started. When the TRCTCPAPP command is invoked interactively, the user will be prompted for any options to change on each of the selected traces. This parameter is valid for all applications.>

*NONE: No additional trace will be included.

*CMNTRC: A communications trace will be included in the trace information for the specified application.

Note:

Due to resource limitations of the I/O hardware, multi-connection PPP profiles may not produce trace data for every connection started by the PPP profile.

*TCPIP: A single TCP/IP component trace will be included in the trace information for the specified application.

*SRCSINK: A source/sink component trace will be included in the trace information for the specified application.

TRCPGM

Specifies the name of a program to call for user defined trace commands and procedures.

For SET(*ON), the trace program will be called:

• Before the application trace starts.
• After the communications and Licensed Internal Code (LIC) traces, if requested, start.

For SET(*OFF), the trace program will be called:

• Before the LIC traces, if requested, end.
• After the communications trace, if requested, ends.
• After the application trace ends.

For SET(*END), the trace program will be called:

• After the LIC and communications traces, if requested, end.
• After the application trace ends.

This parameter is valid for all applications.

When the TRCTCPAPP command detects an error from the trace program, it will send a TCP4537 diagnostic message.

There are two input parameters and one output parameter associated with the trace program. The three parameters are required:

• 1 Trace option setting Input Char(10)
• 2 Application Input Char(10)
• 3 Error detected Output Char(10)

The possible values for the "Trace option setting" parameter are:

• *ON, The collection of trace information is started.
• *OFF, The collection of trace information is stopped and the trace information is written to spooled printer files of the user.
• *END, Tracing is ended and all trace information is deleted. No trace information output is created.

The possible values for the "Application" parameter are the same as the values for the APP parameter on the TRCTCPAPP command.

The possible value for the "Error detected" parameter is:

• *ERROR, Error detected by customer trace program.

*NONE: No user supplied trace program will be called.

The possible library values are:

*LIBL: The library list is used to locate the program.

*CURLIB: The current library is used to locate the program. If no library is specified as the current library, the QGPL library is used.

trace-program-library: Specify the name of the library where the program is located.

trace-program: Specify the name of the user supplied program to call.

TITLE

Specifies the title that is printed on each page of the spooled file which contains the collected trace information. This parameter is only valid when SET(*OFF) is specified. This parameter can be up to

50 > characters.

*DFT: The default trace description title "TRCTCPAPP Output" is used.

'trace-title': If entered, this string is placed on each page of the trace output spooled file.

USER

Only trace information associated with a specific job profile will be collected. This parameter is only valid when APP(*FTP) is specified.

user-profile-name: Specify the user profile for which trace information is to be collected.

MAILADR

Only trace information associated with a specific recipient mail address will be collected. This parameter is only valid when APP(*SMTPSVR) or APP(*SMTPCLT) is specified.

recipient-mail-address: The recipient address (up to 255 characters) must have the following format:

"userid@abc.def.com"

HOST

Specifies the recipient host name for which trace information is collected. This parameter is only valid when APP(*SMTPCLT) is specified.

recipient-host-name: The recipient host name (up to 255 characters) must have the following form:

"abc.def.com"

RMTNETADR

The user may limit the amount of information collected by entering an address family, remote TCP/IP address, subnet mask, and port number. This parameter is only valid when APP(*FTP), APP(*SMTPSVR), APP(*CENTRAL), APP(*DTAQ), APP(*RMTCMD), APP(*SIGNON), APP(*NETPRT), APP(*SVRMAP), APP(*DDM), APP(*TELNET), APP(*VTAPI), APP(*L2TP) or

APP(*DATABASE) > is specified. Note that the only valid filter for L2TP is the IP Address element.

Element 1: Address Family

*INET: Filter for AF_INET address family.

Element 2: IP Address

IP-address: Specify the remote TCP/IP address for which trace information is to be collected.

Element 3: Subnet Mask

255.255.255.255: Tracing will be done for only the IP address specified as the second element of this parameter.

subnet-mask: Specify the subnet mask for which trace information is to be collected.

Element 4: Port Number

*ANY: The TCP/IP port number defaults to *ANY which implies traffic associated with any port on the remote system (and qualified by the IP address and subnet mask) will be traced.

TCP/IP-port-number: If the user wants to specify the port, the subnet mask must also be specified.

LCLNETADR

The user may limit the amount of information collected by entering an address family, local TCP/IP address, subnet mask, and port number. This parameter is only valid when APP(*TELNET), APP(*VTAPI), APP(*CENTRAL), APP(*DTAQ), APP(*RMTCMD), APP(*SIGNON), APP(*NETPRT), APP(*SVRMAP), APP(*DDM) or

APP(*DATABASE) > is specified.

Element 1: Address Family

*INET: Filter for AF_INET address family.

*UNIX: Filter for AF_UNIX address family.

Element 2: IP Address or UNIX path

IP-address: When *INET specified for element 1 of this parameter, specify the local TCP/IP address for which trace information is to be collected.

UNIX-path: When *UNIX specified for element 1 of this parameter, specify the UNIX path for which trace data is to be collected.

Element 3: Subnet Mask

255.255.255.255: Tracing will be done for only the IP address specified as the second element of this parameter.

subnet-mask: Specify the subnet mask for which trace information is to be collected.

Element 4: Port Number

*ANY: The TCP/IP port number defaults to *ANY which implies traffic associated with any port on the local system (and qualified by the IP address and subnet mask) will be traced.

TCP/IP-port-number: If the user wants to specify the port, the subnet mask must also be specified.

DEVD

The user may limit the amount of information collected by entering a device description name. Once the device description is associated with a given TELNET or VTAPI session, all trace information associated with it will be collected. This parameter is only valid when APP(*TELNET) or APP(*VTAPI) is specified.

device-description-name: Specify the name of a device description for which trace information is to be collected.

generic*-device-description-name: Specify the generic name for device descriptions for which trace information is to be collected. A generic name is a character string of one or more characters followed by an asterisk (*); for example, CMN*. If a generic name is specified, then all device descriptions with names that begin with the generic name, and for which the user has authority, will have trace information collected.

DEVTYPE

One or more valid device types may be specified. Only the trace information associated with activity for those devices will be traced. If *DSP or *PRT is specified, no other values may be entered for this parameter. This parameter is only valid when APP(*TELNET) or APP(*VTAPI) is specified.

*DSP: The information collected is only for display device types.

*PRT: The information collected is only for printer device types.

device-type: The information collected is only for the specified device types. Up to six types may be specified. The valid types include: 5251, 5291, 5292, 3196, 3488, 3487, 3179, 3180, 5555, 3477, 3277, 3278, 3279, V100, 3812 and 5553.

TRCPNT

You can limit the trace points that are placed in the trace buffer by entering the list of those trace points for this parameter. Up to 12 trace points may be specified. This parameter is only valid when APP(*TELNET), APP(*VTAPI), APP(*CENTRAL), APP(*DTAQ), APP(*RMTCMD), APP(*SIGNON), APP(*NETPRT), APP(*SVRMAP), APP(*DDM) or

APP(*DATABASE) > is specified.

trace-point-identifier: Each trace point may be up to 8 characters. For TELNET/VTAPI trace points, specify 'TG#xxxxx', 'TG+xxxxx' or 'TG-xxxxx' where 'xxxxx' defines the specific trace point. The following TELNET/VTAPI trace points can also be specified: TGTELM, TGTELO, TGEXCP, TGREQPO, TGRIO, TGRPO, TGUTIL, TGVTERM, TGVTIN, TGVTINI, TGVTM or TGVTOUT. For host/DDM server trace points, specify 'Qcccxxxx' where 'ccc' is the component ID of the host/DDM server and 'xxxx' defines the specific trace point.

ARGLIST

Only trace information associated with this specific argument list (up to 255 characters) will be included in the trace information collected. The argument list contains data like the debug level and special trace requests. This parameter is only valid when APP(*VPN), APP(*QOS),

APP(*PKTRULES)>, APP(*PPP) or APP(*DIRSRV) is specified.

argument-list: Specify the argument list (up to 255 characters).

QoS allows the following argument list values:

lvl=1: The lvl=1 argument logs errors that are associated with system operations. One example might be that the system is out of memory. The result of these types of errors is that the QoS server will not be able to run.

lvl=2: The lvl=2 argument includes all lvl=1 information. In addition, the lvl=2 argument logs internal errors identified with the operation of the QoS server. The usual cause of these types of errors is that unexpected errors have been encountered in a server operation. A lvl=2 error is considered a condition for an APAR.

lvl=3: The lvl=3 argument includes all lvl=1 and lvl=2 information. In addition, the lvl=3 argument logs the basic operational activities of the QoS server. Examples might be the loading of rules or the sending of a STRTCPSVR SERVER(*QOS) RESTART(*QOS) command.

lvl=4: The lvl=4 argument includes all lvl=1, lvl=2 and lvl=3 information. In addition, the lvl=4 argument logs all traced activities of the QoS server.

VPNSVR

Specifies whether the trace information is to be collected for only the VPN key manager or the VPN connection manager. If no value is specified for this parameter, trace information is to be collected for both the VPN key manager and the VPN connection manager. This parameter is only valid when APP(*VPN) is specified.

*KEYMGR: Filtering of trace information is done to include the VPN key manager.

*CNNMGR: Filtering of trace information is done to include the VPN connection manager.

CERTTYPE

Only trace information associated with a specific certificate services type will be included in the trace information collected. This parameter is only valid when APP(*CERTSRV) is specified.

*ALL: No filtering of trace information is done for certificate services type.

*DCM: Filtering of trace information is done to include only the DCM certificate services type.

*KEYMGR: Filtering of trace information is done to include only the VPN key manager certificate services type.

*SSL: Filtering of trace information is done to include only the SSL certificate services type.

*OBJSIGN: Filtering of trace information is done to include only the OBJSIGN certificate services type.

*OTHER: Filtering of trace information is done to include only a certificate services type not listed above.

DNS

Specifies whether only trace information associated with domain name service (DNS) resolution will be collected. This parameter is only valid when APP(*SMTPCLT) is specified.

*NO: No filtering of trace information is done for DNS resolution.

*YES: Trace information includes only trace points associated with DNS resolution.

PPPCNNPRF

Trace information associated with a specific PPP connection profile will be collected. The default trace information provided is one joblog and one connection dialog spooled file (containing the PPP dialog trace) for each connection started by the PPP connection profile, one copy of the PPP profile settings, and one copy of the line description used by the profile. When selected by the user there could also be one SRCSINK component trace per connection, one Communications trace per connection, and a single TCPIP component trace. This parameter is required when APP(*PPP) is specified.

connection-profile-name: Specify the PPP connection profile for which trace information is to be collected.

TCPTRCDTA

Specifies what additional data will be collected when ADLTRC(*TCPIP) is selected. This parameter is only valid when APP(*PPP) is specified. If APP(*PPP) is specified and ADLTRC(*TCPIP) is not specified, this parameter will be ignored.

*PPPALL: All data on the PPP connection will be traced.

*LCPNCP: Only LCP and NCP data on the PPP connection will be traced.

QOSTRCTYPE

Only trace information associated with a specific QOS trace type will be included in the trace information collected. This parameter is only valid when APP(*QOS) is specified.

*ALL: Filtering of trace information is done to include both servers.

*POLICYD: Filtering of trace information is done to include the QOS policy server.

*RSVPD: Filtering of trace information is done to include the RSVP (Resource reSerVation Protocol) server.

HTTPSVR

This parameter will determine which HTTP server instance to trace. It is only valid and required when APP(*HTTP) is specified.

TRCLVL

Specifies the level of granularity of the service trace. This parameter is only valid when APP(*HTTP) is specified.

*ERROR: The service trace will contain trace records for all error return codes or exception conditions.

*INFO: The service trace will contain *ERROR level trace records as well as trace records for entry and exit points from application level API's and API parameters.

*VERBOSE: The service trace will contain *INFO level trace records as well as trace records for debugging control flow or data corruption.

PKTTRCPNT

Specifies a keyword that represents trace point values which will be displayed when the Trace Internal (TRCINT) panel is displayed. This parameter is only valid when APP(*PKTRULES) and ADLTRC(*TCPIP) are specified.

*TRAFFIC: The following trace points for packet filter evaluation will be displayed on the Trace Internal panel: 8110-8111, 8120-8123 and 8420.

*LOAD: The following trace points for the audit and load of rules will be displayed on the Trace Internal panel: 8100-8105 and 8430-8438.

CFGOBJ

Specifies the name of the configuration object to trace. The object can be either a line description, a network interface description, or a network server description. This parameter is only valid when ADLTRC(*CMNTRC) is specified.

CFGTYPE

Specifies the type of configuration description to trace. This parameter is only valid when ADLTRC(*CMNTRC) is specified.

*LIN: The type of configuration object is a line description.

*NWI: The type of configuration object is a network interface description.

*NWS: The type of configuration object is a network server description.

Examples for TRCTCPAPP

Example 1: Starting Trace for Database

TRCTCPAPP APP(*DATABASE) SET(*ON) TRCPNT(QZDA1050 QZDA1060)
          LCLNETADR(*INET '9.130.69.22' '255.255.255.255' 8471)
          ADLTRC(*CMNTRC) TRCPGM(PGMLIB/PROG1) CFGOBJ(TESTLIN)
          CFGTYPE(*LIN)

This will start tracing for the database host server. Tracing information associated with the AF_INET address family, a local TCP/IP address of 9.130.69.22, a subnet mask of 255.255.255.255, port number of 8471 and trace points of QZDA1050 and QZDA1060 will be collected. A communication trace will be included in the trace information. TESTLIN is the name of the configuration object to trace. This object is a line (*LIN) description. Trace program PROG1 in library PGMLIB, with its user-defined trace commands and procedures, will be called. Tracing for the other TCP applications is not affected.

Example 2: Check Status of Database Tracing

TRCTCPAPP APP(*DATABASE) SET(*CHK)

This command is used to check the status of the tracing for the database host server job. Assume that the last command entered was from "Example 1". The format of the response to this command would be a set of messages that would look similar to the following:

TCP45B7 TRCTCPAPP APP(*DATABASE) SET(*ON) TRCPNT(QZDA1050 QZDA1060)
                  LCLNETADR(*INET '9.130.69.22' '255.255.255.255' 8471)
                  MAXSTG(*DFT) TRCFULL(*WRAP) ADLTRC(*CMNTRC)
                  TRCPGM(PGMLIB/PROG1) CFGOBJ(TESTLIN) CFGTYPE(*LIN)
TCP45B1 Tracing active for *DATABASE at 20:15:14 on 03/15/01 by
        043432/TRCUSER/QPADEV000B.
TCP45B2 Data capture begun for *DATABASE.
TCP45B3 Data buffer wrapped for *DATABASE.

Example 3: Ending Database Connection Tracing

TRCTCPAPP APP(*DATABASE) SET(*OFF)

This command first ends any currently active application trace for the database host server, followed by ending the TCP/IP component trace. If tracing was active, output trace records are formatted and placed into a spool file. A similar message will be found in the user's joblog:

TCP45B8 Trace data for application DATABASE formatted: QZDA001915.

If tracing is not active, then the following message will be returned to the user:

TCP4580 Tracing off, SET(*OFF) not valid.

Example 4: Starting Trace for Packet Rules

TRCTCPAPP APP(*PKTRULES) SET(*ON) ARGLIST('DebugLvl=1 TraceLvl=2')
          ADLTRC(*TCPIP) PKTTRCPNT(*LOAD)

This will start tracing for packet rules. Tracing information associated with the specific argument list will be collected. A component trace will be included in the trace information, using trace points of 8100-8105 and 8430-8438. Tracing for the other TCP applications is not affected.

Example 5: Starting Trace for FTP

TRCTCPAPP APP(*FTP) SET(*ON)
          RMTNETADR(*INET '9.130.69.16' '255.255.255.255' 5)

This will start tracing for the FTP server. Tracing information associated with the AF_INET address family, a remote TCP/IP address of 9.130.69.16, a subnet mask of 255.255.255.255 and port number of 5 will be collected. Tracing for the other TCP applications is not affected.

Example 6: Starting Trace for TELNET

TRCTCPAPP APP(*TELNET) SET(*ON) DEVD(QPADEV*)

This will start tracing for the TELNET server. Trace information will be collected for all device descriptions with names that begin with "QPADEV". The user must have authority to these specific device descriptions. Tracing for the other TCP applications is not affected.

Error messages for TRCTCPAPP

*ESCAPE Messages

TCP4595

Trace not started.