Starting Policy Agent from the z/OS shell

The Policy Agent executable program resides in /usr/lpp/tcpip/sbin. There is also a link from /usr/sbin. Make sure the PATH statement contains either /usr/sbin or /usr/lpp/tcpip/sbin.

The Policy Agent requires access to one or more DLLs at runtime. The LIBPATH environment variable must be set to include the /usr/lib directory, which normally includes all the required DLLs.

In order for policy time specifications to be properly acted upon, the TZ environment variable needs to be set to local time.

Set the LIBPATH and TZ environment variables as follows:

Export the LIBPATH and TZ environment variables before starting the Policy Agent. Use /etc/profile or in .profile in the HOME directory. For example, in the Eastern time zone in the United States:

export LIBPATH=/usr/lib
export TZ=EST5EDT4

See z/OS Language Environment Programming Guide for more information about specifying run time options and environment variables. Also, see z/OS UNIX System Services Command Reference for details about setting the LIBPATH and TZ environment variables.


>>-pagent------------------------------------------------------->

>--+-------------------------------------------------------------------------------+-><
   '- -c/C --filename-- -d/D --n-- -i/I -- -t/T --n-- -l/L --logfile-- -m/M --n--&-'

Guideline: The options can be in either upper- or lowercase (for example, C or c).

Rule: To avoid interfering with the shell session, run Policy Agent in the background. To run Policy Agent in the background, add a trailing & to the command line used to start Policy Agent.

Parameters

-c/C

The -c/C option allows a policy configuration file name to be specified. If it is not specified, the configuration file is located using the search order.

This value can be an z/OS® UNIX or MVS™ data set.

The z/OS UNIX file or MVS data set is specified by the -c startup option. The syntax for a z/OS UNIX file is '/dir/file' and the syntax for an MVS data set is "//'MVS.DATASET.NAME'".

Tip: Note the differences in the single and double quotation marks.

-d/D

When -d is specified, all debug messages are logged in the Policy Agent log file. If -d is not used, log messages are written to the Policy Agent log file as specified by the LogLevel configuration statement. The log file should be the first place checked for error messages.

n is an integer that specifies the level of debugging. Specify a desired debug level or a combination of levels. If this start option is absent, the default level is 0. To combine debug levels, add debug level numbers. For example, to request base messages (level 1) and sysplex summary messages (Level 4), request a debug level of 5 (for example, -d 5).

0: None. No debug messages are logged. This is the default.
1: Base. The Policy Agent logs internal debug information.
When this level is selected, the Policy Agent also uses the maximum LogLevel value, regardless of what is configured.
2: LDAP. The Policy Agent logs information about each LDAP object attribute that is processed.
4: Sysplex summary. The Policy Agent logs summary information about performance monitor QoS fraction calculations at target stacks.
8: Sysplex detail. The Policy Agent logs detailed information about performance monitor QoS fraction calculations at target stacks, and additional sysplex distributor information.
16: Memory trace. The Policy Agent logs inline details of all memory allocation and free requests. This debug level is independent of the -m startup option.
32: Policy install trace. The Policy Agent logs details of all policies as the policies are installed in the TCP/IP stack.
64: Lock trace. The Policy Agent logs information about locks.
128: Remote connection trace. The Policy Agent logs details about remote PAPI connections on the policy server and about connections to the policy server on the policy client.
256: Discovery connection trace. The Policy Agent logs details about requests to discover TCP/IP profile information from import requestors.

-i/I

When specified, the Policy Agent monitors its local files (all configuration files) in real time for changes. The time interval configured on the TcpImage statement is also used to monitor configuration files and the LDAP server for updates. Use of the -i/I option provides more timely updating of policy statements when a configuration file is changed. Change the configuration file to cause an immediate refresh of policy from the LDAP server, which causes the file to be reread. If the file is configured to read policy from the LDAP server, Policy Agent does so at that time.

Restrictions:

Dynamic monitoring for file updates using the -i startup option is not supported for files configured with the DynamicConfigPolicyLoad statement.
Dynamic monitoring for file updates using the -i startup option is supported only for z/OS UNIX files; MVS data sets are not monitored for changes (these files are reread at each refresh interval).

-t/T

The -t/T options specify whether to turn on LDAP client debugging. The following levels are supported:

0

No LDAP client debugging. This is the default.

1

This level turns on LDAP client debugging.

Tip: The destination of LDAP client debug messages is stderr.

This is controlled by the LDAP client library, not the Policy Agent. This turns on the following LDAP DEBUG Options:

LDAP_DEBUG_TRACE
LDAP_DEBUG_PACKETS
LDAP_DEBUG_ARGS
LDAP_DEBUG_CONNS
LDAP_DEBUG_BER
LDAP_DEBUG_FILTER
LDAP_DEBUG_MESSAGE
LDAP_DEBUG_STATS
LDAP_DEBUG_THREAD
LDAP_DEBUG_PARSE
LDAP_DEBUG_PERFORMANCE
LDAP_DEBUG_REFERRAL
LDAP_DEBUG_ERROR

For details about debug options, see z/OS Security Server LDAP Client Application Development Guide and Reference.

Restriction: If Policy Agent was started with the trace option disabled, then the output destination of stderr is closed. This option cannot later be enabled by using the MODIFY command.

-l/L logfile

The -l/L option can be used to specify the destination of the log output file. Either SYSLOGD or a z/OS UNIX file can be specified. If you specify SYSLOGD, you can take advantage of a centralized logging mechanism. The environment variable PAGENT_LOG_FILE also specifies the destination of the log file, using the same format as this option. The -l/-L option overrides the PAGENT_LOG_FILE environment variable. Another environment variable, PAGENT_LOG_FILE_CONTROL, specifies the number and size of log files (if SYSLOGD is not specified). The format is: PAGENT_LOG_FILE_CONTROL=x,y where x is the log file size (kilobytes). A maximum value of 1 000 000 can be specified. y is the number of log files. The default is 3 log files, each 300 kilobytes in size.

The default is /tmp/pagent.log.

Result: If for some reason Policy Agent cannot read the start options, then it does not have a log file destination and Policy Agent might fail to open a z/OS UNIX log file. In these situations, Policy Agent logs error messages to the syslog daemon and exits abnormally.

If you run Policy Agent with a nonzero UID and you are using a z/OS UNIX log file, be sure to perform the following tasks:

Specify the file permissions as either 776 or 766.
Ensure that the syslog daemon is not configured to log the same z/OS UNIX file. The syslog daemon runs with UID 0 so Policy Agent might not be able to access its log file if syslogd creates the file before Policy Agent starts.

-m/M n

When specified, the Policy Agent records all memory allocation and free requests in a buffer. The number of entries in this buffer is specified on the -m option. The minimum value is 1 000 and the maximum value is 25 000. Values specified outside of this range are rounded up or down as needed. The number of entries in the buffer determines how many concurrent memory allocations can be recorded.

The memory request buffer can be used in two ways:

To provide a snapshot of Policy Agent memory allocations, by using the MODIFY MEMTRC command. See z/OS Communications Server: IP System Administrator's Commands and z/OS Communications Server: IP Diagnosis Guide for more information about this command.
To detect memory leakage by the Policy Agent. Memory leakage can only be determined when Policy Agent terminates. At the end of termination, after all memory free requests have been processed, any entries left in the memory request buffer are by definition memory leaks. If the -m option was specified, Policy Agent logs the contents of the memory request buffer at the end of Policy Agent termination.

If the number of entries specified on the -m option is too small to contain the total number of concurrent memory allocations at any point in time, Policy Agent turns off the memory trace function and stops recording in the buffer. If this occurs, the contents of the buffer are not usable, and Policy Agent logs this fact along with the high water mark number of entries at termination. Increase the number of entries the next time Policy Agent is started.

If the Policy Agent cannot successfully parse the start options, log output is written to the syslog daemon (SYSLOGD).