Before defining policies, you need to configure some basic
operational characteristics of the Policy Agent.
- 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).
- 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).
- 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.
- 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.
- 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.
- 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.