PolicyAction statement

Use the PolicyAction statement to specify the type of service a flow of IP packets (for example, from a TCP connection, or UDP data) should receive end-to-end as they traverse the network. PolicyAction can be repeated with each having a different name so that they can be referenced later.

This statement defines a Version 2 policy action.

Parameters

name

A string 1 - 32 characters in length specifying the name of this policy action.

PolicyScope

Indicates the scope of this PolicyAction. The following values are allowed:

• DataTraffic indicates the scope is Differentiated Services.
• RSVP indicates the scope is Integrated Services (for example, RSVP).
• Both indicates the scope is both DataTraffic + RSVP (this is the default).

Certain attributes of the policy action are used only with certain scope values, as follows:

RSVP

FlowServiceType, MaxRatePerFlow, MaxTokenBucketPerFlow, MaxFlows

DataTraffic

All other attributes (Permission applies to all scope values)

When the scope value is specified as Both, both RSVP and DataTraffic attributes can be specified, but the attributes are only applied to the appropriate scope.

OutboundInterface

Specifies an outbound interface used for sysplex distributor distributing stack. Incoming connection requests can be distributed to different target stacks within the sysplex by the sysplex distributor distributing stack based on VIPADIST statements (which define DXCF interfaces) defined for the corresponding distributing stack.

This attribute selects the DXCF interfaces that are available for the incoming connection request that maps to this policy. You can specify IPv4 and IPv6 addresses. You can specify up to 32 instances of this attribute. The value 0 for IPv4 or :: for IPv6 can be specified for the interface, which indicates to the sysplex distributor distributing stack that if it cannot distribute the request to a target stack on one of the other specified interfaces, then the request can be distributed to any of the other eligible target stacks.

For example, suppose 5 target stacks are defined by VIPADIST statements (1.1.1.1 - 5.5.5.5), and 3 interfaces are defined using the OutboundInterface attribute (1.1.1.1, 2.2.2.2, and 0.0.0.0). If an incoming request cannot be distributed to either 1.1.1.1 or 2.2.2.2, then the specification of the 0 interface indicates that the request should be distributed to any of the remaining stacks (3.3.3.3 - 5.5.5.5) that are eligible to service the request. The PolicyScope attribute must specify either DataTraffic or Both to define interfaces using this attribute.

Result: If OutboundInterface specifies only one type of address (IPv4 or IPv6), then inbound connections of the other type is distributed to all available targets. For example, if only IPv6 addresses are specified for OutboundInterface, then incoming connections to IPv4 DVIPAs are not restricted by OutboundInterface; instead, they are distributed to all available IPv4 targets.

Rules:

• If the IP address is IPv6, it cannot be an IPv4-mapped IPv6 address (in hexadecimal or dotted decimal format) or an IPv6 address with the reserved prefix ::/96. If the IPv6 address is one of these two types, an error message is logged.
• IPv6 policy is installed but is not enforceable in a stack that is not IPv6 enabled.

MaxRate

An integer value representing the maximum rate in kilobits per second (Kbps) allowed for traffic in this service class. This attribute is valid only for TCP. If not specified or specified as 0, there is no enforcement of the maximum rate of a connection by the local host. If a number other than 0 is specified, each TCP connection that is mapped to this PolicyAction has its rate limited to this MaxRate. Enforcement of the MaxRate is performed by the TCP/IP stack by adjusting the TCP congestion window based on the connection round-trip time (the rate is obtained by taking the congestion window and dividing it by the round-trip time; note the units, for example, byte versus bit, second versus millisecond). Because the minimum of the congestion window is one TCP segment size, the minimum of the MaxRate that can be enforced is one TCP segment over the round-trip time. If a TCP connection has a very small round-trip delay and traverses over a very high bandwidth network (for example, Gbit Ethernet LAN), the minimum rate that this TCP connection can send (one segment per round-trip time) can be high. Therefore, users and network administrators need to know their network characteristics when setting this MaxRate; it might not be enforceable if the minimum TCP rate (for example, one segment over round-trip time) already exceeds this specified MaxRate. As noted, TCP segment size can play a role in this TCP minimum rate; for example, for a given round-trip delay, the larger the segment size, the higher the minimum TCP rate. There are different factors that can affect the TCP segment size, for example, the local MTU size definition, the Path MTU discovery flow (this mechanism is used to discover the maximum MTU size that can be sent into the network without resulting in IP fragmentation), the receivers maximum segment size, and so on.

MinRate

An integer value representing the minimum rate or throughput (Kbps) allowed for traffic in this service class. This attribute is valid only for TCP. If not specified or specified as 0, there is no enforcement on the minimum rate of a connection by the local host. If a number other than 0 is specified, the rate for any TCP connection that is mapped to this PolicyAction does not fall below this MinRate, unless the network is really congested and by maintaining the minimum rate the network throughput might collapse. Enforcement of the MinRate is performed by the TCP/IP stack by manipulating the congestion window over the connection round-trip time. Unlike the enforcement of MaxRate, if TCP minimum rate due to the segment size or the round-trip time, or both, is already high, and the specified MinRate is already below this rate, it is not necessary for the TCP/IP stack to enforce the MinRate.

OutgoingTOS

Eight bits, left-aligned, representing the ToS or Traffic Class value of outbound traffic belonging to this service class. The default is 0.

Tip: An outbound packet with a ToS or Traffic Class value that consists of zeros enables prioritizing outbound OSA-Express data using the WorkLoad Manager service class importance level. This function is enabled with the WLMPriorityQ parameter. For more information about Workload Manager provided-priorities, see prioritizing outbound OSA-Express data using the WorkLoad Manager service class importance level in z/OS Communications Server: IP Configuration Guide. When WLMPriorityQ is enabled, specify an OutgoingTOS value other than 0 if you want to prevent the assignment of QDIO priority based on the WorkLoad Manager service class importance level.

MaxDelay

An integer value representing the maximum delay (in milliseconds) allowed for traffic in this service class. This attribute is valid only for TCP. The TCP/IP stack does not enforce this delay.

Result: This parameter is no longer supported and is ignored.

MaxConnections

An integer value representing the maximum number of end-to-end connections at any instant in time. This attribute is valid only with TCP. It places a limit on the number of TCP connections mapped to this PolicyAction that can be active at a time. If there is a request for a new TCP connection that maps to this PolicyAction and this limit is exceeded, the connection request is rejected. The default is that there is no policy limit. The MaxConnections attribute is enforced by the TCP/IP stack. If the connection request is sent by a remote client, a TCP RST segment is returned to notify the client that the connection is refused. The number of rejected connections is maintained and can be retrieved with the netstat command using the -j option. If the connection request is sent by an application in the local host (for example, using a connect socket call), a return code of permission denied is returned.

Restriction: This attribute only affects new connection requests, not already active connections. For example, if a policy is activated that limits the maximum number of connections to 10, but 15 connections already existed for traffic that maps to the policy rule, then only 10 of the existing connections are mapped to the policy and no new connections are accepted. However, the five other existing connections over the limit remain active and unmapped by the policy.

FlowServiceType

Limits the Type of Service being requested by RSVP applications. Valid values are ControlledLoad (the default) and Guaranteed. Guaranteed service is considered to be greater than ControlledLoad service. If ControlledLoad service is specified, and an application requests Guaranteed, the requested service is downgraded to ControlledLoad. To allow RSVP applications to request Guaranteed service, specify Guaranteed for this parameter. All RSVP parameters, FlowServiceType, MaxRatePerFlow, MaxTokenBucketPerFlow, and MaxFlows, are enforced by the RSVP daemon application and not by the TCP/IP stack. The TCP/IP stack, however, maintains traffic statistics of RSVP policies, which can be retrieved with the netstat command with option -j.

MaxRatePerFlow

Specifies the maximum rate in kilobits per second for RSVP flows. RSVP reservations are based on a traffic specification (Tspec) from the sending application. The Tspec consists of the following values:

• r is the token bucket rate in bytes per second.
• b is the token bucket depth in bytes.
• p is the peak rate in bytes per second.
• m is the minimum packet size in bytes.
• M is the maximum packet size (MTU) in bytes.

Use this parameter to limit the r value of the Tspec. If an RSVP sender application requests a Tspec r value larger than this parameter, the request is downgraded to this parameter value.

RSVP receiving applications also specify a resource specification (Rspec) when using Guaranteed service, as part of the reservation request. The Rspec consists of the following values:

• R is the rate in bytes per second.
• S is the slack term in microseconds.

This parameter is also used to limit the R value of the Rspec for reservation requests from RSVP receiver applications using Guaranteed service.

Guideline: This parameter is specified in kilobits per second, while the Tspec and Rspec use bytes per second. To arrive at a compatible specification, multiply the desired Tspec or Rspec value by 8, then divide by 1000. For example, to specify a Tspec r value of 500000 bytes per second, specify a MaxRatePerFlow value of 4000 (500000 * 8 / 1000 = 4000).

The default for this parameter is a system defined maximum.

MaxTokenBucketPerFlow

Specifies the maximum token bucket size in kilobits per second for RSVP flows. RSVP reservations are based on a traffic specification (Tspec) from the sending application. The Tspec consists of the following values:

• r is the token bucket rate in bytes per second.
• b is the token bucket depth in bytes.
• p is the peak rate in bytes per second.
• m is the minimum packet size in bytes.
• M is the maximum packet size (MTU) in bytes.

This parameter limits the b value of the Tspec. If an RSVP sender application requests a Tspec b value larger than this parameter, the request is downgraded to this parameter value.

Guideline: This parameter is specified in kilobits, while the Tspec uses bytes. To arrive at a compatible specification, multiply the desired Tspec value by 8, then divide by 1000. For example, to specify a Tspec b value of 75000 bytes, specify a MaxTokenBucketPerFlow value of 600 (75000 * 8 / 1000 = 600).

The default for this parameter is a system defined maximum.

MaxFlows

Specifies the maximum number of reserved flows allowed for RSVP applications. The default is no limit on the number of reserved flows.

Permission

Indicates whether packets belonging to this policy rule should be discarded or allowed to proceed. Valid values are Allowed and Blocked. The default is Allowed.

DiffServInProfileRate

Specifies the mean rate at which traffic belonging to the corresponding policy must be policed. It is a Kbps value and must be policed in kilobits per second (Kbps). The default value is 0, meaning no policing mechanism is enforced. The DiffServ parameters are enforced by the TCP/IP stack. Statistics regarding in-profile byte count can be retrieved using the netstat command with option -j. This in-profile count can be used to calculate the amount of traffic sent out of profile. The in-profile count should be equal to or less than the total transmitted byte count unless the count wraps.

Unlike MaxRate/MinRate, which applies on a per TCP connection basis, these DiffServ parameters apply to aggregated flows (multiple TCP connections can be mapped to a single policy action). Also, it is important to note that when DiffServ parameters are enforced against TCP traffic, the TCP minimum rate determines whether the DiffServ parameters are enforceable, as described in the attribute MaxRate. This is due to an optimization provision where TCP is forced to slow down when it attempts to send beyond the committed bandwidth specified with DiffServ parameters in the policy action with DiffServExcessTrafficTreatment specified as Drop. TCP cannot slow down beyond the TCP minimum rate, even if a violation occurs.

This rate that is used to generate tokens in the token bucket traffic policing mechanism, but it is not necessarily the user/application generated traffic rate.

If this attribute is a nonzero value, the DiffServInProfileTokenBucket value must also be nonzero.

Guideline: This parameter is used by a token bucket mechanism to control the outbound traffic.

DiffServInProfilePeakRate

Specifies the peak rate that traffic belonging to the corresponding policy must be policed. It is a Kbps value and must be policed in kilobits per second (Kbps). The default is 0, which means no policing mechanism is enforced against the peak rate if DiffServInProfileRate is nonzero. When nonzero, it must not be less than that of the DiffServInProfileRate. If this attribute is nonzero, DiffServInProfileRate and DiffServInProfileMaxPacketSize must also be nonzero.

A token bucket mechanism used this parameter to control the outbound traffic.

DiffServInProfileTokenBucket

Specifies the maximum burst size that traffic belonging to the corresponding policy must be policed. It is a kilobits value and must be policed in kilobits (Kb). The default is 100 if DiffServInProfileRate is not 0. The DiffServInProfileTokenBucket attribute is used only when the policy action also uses the DiffServInProfileRate attribute.

A token bucket mechanism used this parameter to control the outbound traffic.

DiffServInProfileMaxPacketSize

Specifies the maximum packet size of traffic belonging to the corresponding policy. Its value is used to police traffic against the peak rate. It is a kilobits value with corresponding policy, in kilobits (Kb). The default is 100 if DiffServInProfilePeakRate is not 0.

Guideline: Due to blocking in z/OS® Communications Server, multiple packets tend to be sent back to back. If the maximum packet size is set to the size of one packet, traffic exceeds the peak rate, and those packets are sent as out of profile packets (either with a different ToS or Traffic Class value or dropped) if peak rate enforcement is in effect. To prevent this, the attribute must be set in multiples of the maximum packet size or equal to the token bucket size.

DiffServExcessTrafficTreatment

Specifies what action to take when traffic exceeds its profile. Two values can be specified with this attribute:

• Drop
• BestEffort

The default is BestEffort. These are described directly below.

When the DiffServExcessTrafficTreatment is Drop and the corresponding policy is defined for TCP traffic, z/OS Communications Server optimizes performance by simulating the TCP packet drop and reducing the TCP transmit rate in order to force the outbound traffic to conform to the policy defined bandwidth. This means that the TCP packets that result in excess traffic are transmitted, but the corresponding TCP connections are forced to slow down immediately (by half, which is the TCP behavior under packet loss). This helps avoid retransmissions and prevents further excess traffic. If the policy is defined for UDP, because there is no slowdown mechanism in UDP as in TCP, excess traffic is discarded as specified in the policy definition.

When the DiffServExcessTrafficTreatment is BestEffort, the excess packets are still sent; however, they are sent with the ToS or Traffic Class value specified on DiffServOutProfileTransmittedTOSByte.

DiffServOutProfileTransmittedTOSByte

Specifies the ToS/DS or Traffic Class value to send with the excess traffic (if action is to send excess traffic as best effort instead of dropping).

The normal in profile ToS or Traffic Class value comes from the current OutgoingTOS attribute. This value is specified as a string of eight 1s and 0s. The default is 00000000.

Tip: An outbound packet with a ToS or Traffic Class value that consists of zeros enables prioritizing outbound OSA-Express data using the WorkLoad Manager service class importance level. This function is enabled with the WLMPriorityQ parameter. For more information about Workload Manager provided-priorities, see prioritizing outbound OSA-Express data using the WorkLoad Manager service class importance level in z/OS Communications Server: IP Configuration Guide. When WLMPriorityQ is enabled, specify a DiffServOutProfileTransmittedTOSByte value othle er than 0 if you want to prevent the assignment of QDIO priority based on the WorkLoad Manager service class importance level.

Table 1 provides a mapping of PolicyAction statement parameters to LDAP object classes and attributes.