Step 1: Configure general information

Before defining policies, you need to configure some basic operational characteristics of the Policy Agent.

Procedure

Follow these steps to configure these characteristics:

  1. Set the TZ and LIBPATH environment variables. Use the TZ environment variable to specify the correct time zone. Use the LIBPATH environment variable so that the required dynamic link library (DLL) files can be located when you start the Policy Agent. For information about how to specify these environment variables, see Starting and stopping the Policy Agent. You can also refer to comments in the sample start procedure that is shipped in SEZAINST(EZAPAGSP).
  2. Specify the name of the main configuration file. You can specify the name of the main configuration file using the following methods:
    • -c start option
    • PAGENT_CONFIG_FILE environment variable
    • Default file name /etc/pagent.conf

    For information about the search order that Policy Agent uses to locate the main configuration file, and for examples of different ways to specify the main configuration file name, see Starting and stopping the Policy Agent. You can also refer to comments in the sample start procedure that is shipped in SEZAINST(EZAPAGSP).

  3. Define the TcpImage or PEPInstance statements in the main Policy Agent configuration file. The PEPInstance statement is a synonym for TcpImage, and either can be used. PEPInstance refers to policy enforcement point (PEP), the component of a policy system that enforces policies, which for z/OS® is the TCP/IP stack.
    Results:
    • The refresh interval used for the main configuration file will be the smallest of the values specified for the image-specific configuration files.
    • When the main configuration file is an MVS™ data set, it is reread at each refresh interval (which is the smallest of the individual stack refresh intervals), regardless of whether it has actually been changed or not. Because Policy Agent restarts all stack-related processing when the main configuration file is reread, this effectively makes the refresh interval for all stacks the same as this smallest configured interval.
    • The TcpImage or PEPInstance statement and all its parameters have no effect on policies defined for policy clients.

    To install a common set of policies to a set of stacks served by a single Policy Agent, do not specify image-specific configuration files for each image. In this case, there is only one configuration file (the main one) and the policy information contained in it is installed to all of the configured stacks. Different refresh intervals can also be configured for each image, but would probably be less useful in this case.

    In either case, it is possible that TCP/IP stacks configured to the Policy Agent are not started or even defined. The Policy Agent will fail when trying to connect to those stacks and log appropriate error messages.

    Rule: To dynamically add a TCP/IP stack to the Policy Agent configuration and have active policies automatically installed, in addition to adding the TcpImage statement to the configuration file, further action might be necessary as follows:
    • If the Policy Agent was started with the -i startup option, no further action is necessary. Active policies will be automatically installed to the stack when it becomes active.
    • If the Policy Agent was not started with the -i startup option, take one of the following actions:
      • Issue the MODIFY REFRESH or MODIFY UPDATE command after the stack becomes active. If you issue the MODIFY REFRESH or MODIFY UPDATE command before the stack becomes active, policies are not automatically installed.
      • Wait on the next update interval to check for configuration changes. If the stack is not active, policies are not automatically installed.

    The Policy Agent does not end when any (or all) stacks end. When the stacks are restarted, active policies are automatically reinstalled.

    The TcpImage statement specifies a TCP/IP image and its associated configuration file to be installed to that image. The following example installs the policy control file /tmp/TCPCS.policy to the TCPCS TCP/IP image, after flushing the existing policy control data: 
    TcpImage TCPCS /tmp/TCPCS.policy FLUSH

    For information about the FLUSH, NOFLUSH, PURGE, and NOPURGE parameters, see FLUSH and PURGE considerations.

  4. Define the log file destination and the appropriate logging level. You can specify that Policy Agent log messages should be written to the syslog daemon or to a z/OS UNIX file. To indicate the syslog daemon, specify SYSLOGD in uppercase. To indicate a z/OS UNIX file, specify the file name. Specify the log file destination using the -l start option or the PAGENT_LOG_FILE environment variable, or you can use the default value /tmp/pagent.log.
    Tip: Specify SYSLOGD to take advantage of a centralized logging mechanism.
    Result: If Policy Agent cannot read the start options, then it does not have a log file destination. 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.
    Guidelines: If you run Policy Agent with a nonzero UID and you are using a z/OS UNIX log file, follow these guidelines:
    • Specify the file permissions as either 776 or 766.
    • Make sure that the syslog daemon is not configured to log to 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 the syslog daemon creates the file before Policy Agent starts.

    The LogLevel statement is used to define the amount of information to be logged by the Policy Agent. The default is to log only event, error, console, and warning messages. This might be appropriate for a stable policy configuration, but more information might be required to understand policy processing or debug problems when first setting up policies or when making significant changes. Specify the LogLevel statement with the appropriate logging level in the main configuration file.

    Note: The maximum logging level (511) can produce a significant amount of output, especially with large LDAP configurations. This is not a concern if a z/OS UNIX log file is used, because Policy Agent uses a set of log files with a finite size in a round-robin configuration (the number and size of these files is controllable with the PAGENT_LOG_FILE_CONTROL environment variable). But when using the syslog daemon as the log file, the amount of log output produced should be taken into consideration.
  5. Provide the following security authorizations. Because the Policy Agent can affect system operation significantly, the following security authorizations are required.
    • A user starting Policy Agent must be a superuser.
    • Security product authority (for example, RACF(R)) is required to start the Policy Agent. For sample commands needed to create the profile name and permit users to it, see the EZARACF sample in SEZAINST.
  6. If Policy Agent's PAPI clients, including the pasearch command, are not defined as a superuser, to retrieve policies you must define security product authority in the SERVAUTH class for that client. The security product authority is always required in cases where the image name cannot be defined as a superuser. Remote policy clients are never defined as a superuser on the policy server, so security product authority is always required for them. These profiles can be defined by image name and policy type (ptype = QoS, IDS, IPSec, TTLS, or Routing). Using a wildcard for profile names is allowed. 
    EZB.PAGENT.sysname.image.ptype
    where:
    • sysname - System name defined in sysplex
    • image - Tcp name, policy client name, or import request name for policy information that is being requested
    • ptype - Type that is being requested:
      • QOS - Policy QoS
      • IDS - Policy IDS
      • IPSec - Policy IPSec
      • TTLS - Policy AT-TLS
      • Routing - Policy Routing
      • CFGSERV - TCP/IP profile information

    For details about the import request name, see Configuration file import services.

    Tip: You can specify a wildcard on segments of the profile name.
    Rules:
    • When you use policy clients, the image portion of the profile name on the policy server must match or include the name of the policy clients. Configure each policy client name using the ClientName parameter on the PolicyServer statement, or use the default value for the ClientName parameter. For information about specifying the client name on the PolicyServer statement, see z/OS Communications Server: IP Configuration Reference.
    • When you use import requesters, the image portion of the profile name on the policy server must match or include the import request name. If you use the IBM® Configuration Assistant for z/OS Communications Server as the import requester, configure the import request name on the Import Policy Data panel or on request panels for discovery import. For information about the import request name, see Configuration file import services.

    Policy Agent checks all client requests to verify that the SERVAUTH class is active and that the profiles exist for the images and types in the request.

    If a client's request is for multiple images or policy types, and permission is granted for only a subset of what is requested, Policy Agent returns only information for the subset for which permission is granted. However, if permission is denied for an entire request, including instances when only a single image or policy type is requested, an error is returned to the client indicating that permission is denied.

    If the SERVAUTH class is not active or profiles are not active for the client's request (image, policy type), an error is returned to the client indicating that permission is denied.

    See the EZARACF sample in SEZAINST for sample commands needed to create the profile name and permit users to it.

Parent topic: Steps for configuring the Policy Agent