IBM: TCP/IP for VM

System SSL (GSKTRACE) Tracing Information
(Level 540 and Later)

SSL Server Tracing

The information that follows describes how to obtain a System SSL trace for an SSL server or server pool, as well as how to format the resulting trace file.

Note:
This type of tracing requires modification to the DTCPARMS configuration file, in addition to starting and stopping the SSL server(s). This is necessary because System SSL tracing (associated with use of the GSKTRACE operand) cannot be controlled dynamically via an SSLADMIN command.

Modify the :nick.SSL* (or, :nick.SSLSERV) :type.server entry (present in a SYSTEM or node_ID DTCPARMS configuration file) to include the appropriate GSKTRACE parameter for the VMSSL command, along with other pertinent tracing values. For example:
```
  ...
  :timestamp.ON
  :parms.
    ...  (any existing parms)
    TRACE DEBUG
    GSKTRACE 0xffff
  ...
```
The :timestamp.ON entry should be included whenever tracing activity is being performed, to aid with the correlation of SSL server console data with that in the System SSL trace.
Restart the SSL server pool or server, so the added GSKTRACE tracing parameter can take effect.
```
  ssladmin restart (ssl all
```
Establish (or attempt to establish) a secure connection from a selected client host. To minimize the amount of trace data acquired, strive to limit SSL server connection activity to a single client connection whenever possible.
After the subject problem has been recreated (for example, a connection has been established, but not as desired, or the connection has failed), stop the SSL server pool or server.
```
  ssladmin stop (ssl all
```
The console log for the SSL server(s) now should be available in the virtual reader of the "owner" user ID (by default, TCPMAINT). Keep the console(s) at hand for later submission to the IBM support center.
For an SSL server pool, the console of the server that has handled the subject connection or connection attempt is of most interest. This server should be the first one listed in SSLADMIN QUERY STATUS or NETSTAT CONFIG SSL command output. Depending on the problem being diagnosed, it also might be possible to determine which is the applicable server by using an SSLADMIN QUERY SESSIONS command. However, if the server of interest cannot readily be determined, provide all of the pool server consoles for review.
After all tracing is complete, any DTCPARMS changes that have been made specifically for capturing the desired trace data should be removed, with all production-use values restored as needed.
The pertinent trace files now need to be identified and formatted.
The completed tracing will have produced one or more System SSL GSK trace files, which are accessible via the GSKADMIN user ID. The system SSL trace files are (by default) created in the /../VMBFS:VMSYS:SSLSERV/ directory, and are named using the user ID of the server that created it, along with a process ID (pid) number, using this naming format:
```
  userid.gskssl.nnnnn.trc
```
The trace file (once located) can be formatted using the GSKTRACE command. Information about this command can be obtained using the CMS HELP facility (issue: HELP TCPI GSKTRACE to obtain this information).
For example, to format the trace file:
```
  s1600003.gskssl.12345.trc
```
one might issue this GSKTRACE command:
```
gsktrace /../VMBFS:VMSYS:SSLSERV/s1600003.gskssl.12345.trc > mygsktrc.trcfmt
```
The resulting mygsktrc.trcfmt file then can be copied to a CMS disk (via an OPENVM GETBFS command) for review or transfer to another host.
To simplify locating and formatting the pertinent trace file(s), a sample trace formatting utility (PROCGSKT SAMPEXEC) that makes use of the GSKTRACE command, can be used. To use this utility, download the sample file and create a copy of this as PROCGSKT EXEC on the GSKADMIN 191 disk.
To use the PROCGSKT utility to list all available trace files, or those for the SSL00003 server, issue these respective commands:
```
  procgskt * list
  procgskt ssl00003 list
```
To format a specific SSL0003 server trace file, issue (perhaps):
```
  procgskt ssl00003 12345 mygsktrc
```
This will create a formatted trace file as a packed CMS file (at file mode A) with the name: MYGSKTRC FMT-TRC
For additional information about using the PROCGSKT utility, review the he comments within the sample source, in addition to the (brief) help information provided by issuing: procgskt ?
The pertinent SSL server console log and System SSL trace files now can be submitted to the IBM support center for review.
For the case when an SSL server pool is in use, the System SSL trace file that pertains to the server handling the connection of interest is of primary concern. If this server can be readily identified, supply only the trace file for this server. However, if the server of interest cannot readily be determined, provide all of the applicable pool server trace files for review.
To deactivate the System SSL tracing in the servers, again modify the :nick.SSL* (or, :nick.SSLSERV) :type.server entry (present in a SYSTEM or node_ID DTCPARMS configuration file) to include the appropriate GSKTRACE 0 parameter for the VMSSL command, along with other pertinent tracing values. For example:
```
  ...
  :timestamp.ON
  :parms.
    ...  (any existing parms)
    NOTRACE
    GSKTRACE 0
  ...
```
Restart the SSL server pool or server, so the updated GSKTRACE tracing parameter can take effect.
```
  ssladmin restart (ssl all
```

Additional Notes

When the GSKTRACE operand is in use, new System SSL trace files are created each time a server is initialized. If multiple such traces are gathered or required, use the time stamps of the resulting files, as needed, to correlate a trace file to the scenario being run.
Note that the PROCGSKT utility does not delete any BFS-resident trace files. Such trace files must be deleted through overt measures, such as by using an OPENVM ERASE command.

GSKADMIN gskkyman Command Tracing

The information that follows describes how to obtain a System SSL trace while using the gskkyman certificate and database management utility.

Logon the user ID (GSKADMIN, for example) where the gskkyman utility is to be run.
Create a simple Rexx exec that will correctly set (and, preserve the case of) applicable System SSL tracing values. A suggested name for this exec is GSKGVSET EXEC.
```
  /* GSKGVSET EXEC */
  Address Command
  trc_mask = '0xffff'
  trc_file = '/tmp/gskadmin.pmr12345.%.trc'
  'GLOBALV SELECT CENV SETL GSK_TRACE' trc_mask
  'GLOBALV SELECT CENV SETL GSK_TRACE_FILE' trc_file
  Exit rc
```
When the exec is created, change the pmr12345 portion of the trace file name to reflect an active IBM PMR (problem record) number.
Note that the GLOBALV commands cited will store these values in storage only &mdash. so these values will not be saved across logon sessions of the subject user ID.
Invoke the GSKGVSET exec to put the System SSL tracing values into effect.
Invoke the gskkyman utility, using an applicable command line option or its interactive menus, to perform the intended certificate management operations, or to display information of interest.
After all applicable gskkyman processing has been completed, exit the utility.
You then should be able to locate and format the System SSL trace associated this gskkyman instance. The trace file should be listed by this OPENVM command:
```
  openvm list /tmp/
```
for which the results should appear similar to this:
```
  Directory = '/tmp/'
  Update-Dt  Update-Tm Type  Links      Bytes  Path name component
  09/19/2017 19:18:17   F        1      286201 gskadmin.pmr12345.62251.trc
```
Format the trace using the GSKTRACE command, or the aforementioned PROCGSKT utility.
```
  procgskt gskadmin 12345 trc12345
```

To deactivate the System SSL tracing, one needs to clear the tracing values. A second, simple Rexx exec can be created and used. A suggested name for this exec is GSKGVCLR EXEC.

  /* GSKGVCLR EXEC */
  Address Command
  trc_mask = '0x0000'
  trc_file = ''
  'GLOBALV SELECT CENV SETL GSK_TRACE' trc_mask
  'GLOBALV SELECT CENV SETL GSK_TRACE_FILE' trc_file
  Exit rc

System SSL (GSKTRACE) Tracing Information (Level 540 and Later)

SSL Server Tracing

GSKADMIN gskkyman Command Tracing

System SSL (GSKTRACE) Tracing Information
(Level 540 and Later)