z/OS UNIX ipsec command defensive filter (-F) option parameters

display

Displays the selected defensive filters. If no filters are selected, then all defensive filter rules are displayed.

-r format

Displays defensive filter information in a given format. The default format is detail. See The ipsec command general report concepts for a description of the different report formats.

-N DefensiveFilterName

Specifies one or more defensive filters to be selected. The names used must correspond to defensive filter rule names that are specified when the defensive filters are added.

Tip: The DefensiveFilter base name can refer to more than one filter rule in a stack. In this case, the base name has an appended number that uniquely identifies the defensive filter that is generated. These names have the following format:

name: The base name.
index: An integer that is assigned to the filter rule.

The command ipsec -F display -N DefensiveFilterName displays all defensive filters with a base name that matches the DefensiveFilterName value.

add

Adds a defensive filter to the top of the defensive filters search list. You cannot add an IP security filter with this option; it must be configured in the TCPIP profile or in a policy configuration file. The following add parameters determine the characteristics of the added defensive filter:

srcip

A source IP address specification. Possible values are:

ipaddress: A single IP address. This value indicates the source address that must be contained in an IP packet for the packet to match this filter rule.
ipaddress/prefixLength: A prefix address specification that indicates the applicable source IP addresses that can be contained in an IP packet for the packet to match this filter rule. The prefixLength value is the number of unmasked leading bits in the ipaddress value. The prefixLength value can be in the range 0-32 for IPv4 addresses and in the range 0-128 for IPv6 addresses. An IP packet matches this condition if the unmasked bits of its source address are identical to the defined unmasked bits.
all: Indicates that the filter rule applies to any source IP address. This is the default value.

Rule: If both the srcip and destip parameters are specified, the IP addresses must be in the same family (IPv4 or IPv6).

destip

A destination IP address specification. Possible values are:

ipaddress: A single IP address. This value indicates the destination address that must be contained in an IP packet for the packet to match this filter rule.
ipaddress/prefixLength: A prefix address specification that indicates the applicable destination IP addresses that can be contained in an IP packet for the packet to match this filter rule. The prefixLength value is the number of unmasked leading bits in the ipaddress value. The prefixLength value can be in the range 0-32 for IPv4 addresses and in the range 0-128 for IPv6 addresses. An IP packet matches this condition if the unmasked bits of its destination address are identical to the defined unmasked bits.
all: Indicates that the filter rule applies to any destination IP address. This is the default value.

Rule: If both the srcip and destip parameters are specified, the IP addresses must be in the same family (IPv4 or IPv6).

prot

The IP protocol that must be contained in an IP packet for the packet to match this filter rule. If an n value is specified, it identifies a protocol number. The value for n can be in the range 0-255. If the value all is specified, then the filter rule applies to any protocol. The default value is all.

The protocol specification Opaque matches any IPv6 packet for which the upper-layer protocol is not known because of fragmentation. This specification always matches non-initial fragments, and it also matches initial fragments if the upper-layer protocol value is not included in the first fragment. Use of the Opaque protocol specification is applicable only to routed fragments because, for all local traffic, the stack applies IP filter rules only to fully assembled packets.

Rule: The protocol specification Opaque can be used only for IPv6 addresses.

srcport

If the protocol TCP or UDP is specified, then you can specify a srcport value. The srcport value indicates the source ports that must be contained in an IP packet for the packet to match this filter rule.

Valid values for n are in the range 1-65535. If an m value is specified, it must be greater than or equal to the n value and less than 65536. If the value all is specified, then the filter rule applies to any source port. The default value is all.

Restriction: If the Routing parameter value is Routed or Either, you must use either the default srcport value or the value all.

destport

If the protocol TCP or UDP is specified, then you can specify a destport value. The destport value indicates the destination ports that must be contained in an IP packet for the packet to match this filter rule.

Valid values for n are in the range 1-65535. If an m value is specified, it must be greater than or equal to the n value and less than 65536. If the value all is specified, then the filter rule applies to any destination port. The default value is all.

Restriction: If the Routing parameter value is Routed or Either, you must use either the default destport value or the value all.

type

If the protocol ICMP or ICMPv6 is specified, then you can specify a type value. The type value indicates the ICMP type that must be contained in an IPv4 ICMP packet or an IPv6 ICMPv6 packet for the packet to match this filter rule. Valid values for n are in the range 0-255. If the value all is specified, then the filter rule applies to any ICMP type. The default value is all.

Restriction: If the Routing parameter value is Routed or Either, you must use either the default type value or the value all.

code

If the protocol ICMP or ICMPv6 is specified, then you can specify a code value. The code value indicates the ICMP code that must be contained in an IPv4 ICMP packet or an IPv6 ICMPv6 packet for the packet to match this filter rule. Valid values for n are in the range 0-255. If you specify the value all, then the filter rule applies to any ICMP code. The default value is all.

Restriction: If the Routing parameter value is Routed or Either, you must use either the default code value or the value all.

dir

The direction a packet must take for the packet to match this filter rule. Valid values are:

inbound: Indicates that this filter rule applies to inbound packets. This is the default.
outbound: Indicates that this filter rule applies to outbound packets.

routing

The routing characteristics that a packet must have for the packet to match this filter rule. Valid values are:

local: Indicates that this filter rule applies to packets that are destined for this stack or that originate from this stack. This is the default.
routed: Indicates that this filter rule applies to packets that are being forwarded by this stack.
either: Indicates that this filter rule applies to forwarded and non-forwarded packets.

fragmentsonly

When set to Yes, this filter rule matches only fragmented packets. When set to No, this filter rule matches both fragmented packets and non-fragmented packets. Fragments are matched only in routed traffic, because the TCP/IP stack applies IP filter rules for local traffic only to fully reassembled packets.

Tip: Use this keyword to block all fragmented traffic.

mode

The defensive filter mode. The default value is block.

block: Indicates that the defensive filter blocks or denies packets that match the characteristics of the filter.
simulate: Indicates that the defensive filter simulates a block. If a packet matches a defensive filter with the mode value simulate, a log record is written to syslog indicating that the packet would have been denied by this filter. The packet is not denied and IP filtering continues.

Rule: If the mode value Simulate is configured for a TCP/IP stack in the DMD configuration file, that value overrides the individual defensive filter mode setting. For example, if a defensive filter with the mode value block is added to a stack and the DmStackConfig statement for that stack has a configured mode of Simulate, a packet that matches the defensive filter is not blocked. Instead, a block is simulated. The defensive filter retains the block mode. If the mode value in a DmStackConfig statement for the stack is updated to Active, a packet that matches the defensive filter is blocked.

log

The logging action for a defensive filter.

yes: A log record is written when a packet matches this filter rule. This is the default.
no: A log record is not written when a packet matches this filter rule.

Restriction: If the mode parameter value is simulate, the log parameter must be set to the value yes.

loglimit

The log limit for a defensive filter. The loglimit value is used to enable or disable the limiting of defensive filter match messages (EZD1721I and EZD1722I) written to syslogd. For more information, see filter-match logging in z/OS Communications Server: IP Configuration Guide.

0: Disables the limiting of defensive filter match messages written to syslogd. If logging is being done for this defensive filter, a message is generated for each packet that matches the defensive filter.
n: Enables the limiting of defensive filter-match messages written to syslogd. Valid values are in the range 1 - 9999. The value specifies the limit of the average rate of filter-match messages generated in a 5-minute interval for a defensive filter. For example, a value of 100 limits the average rate of filter-match messages to 100 messages per 5-minute interval. A burst of up to 100 messages is allowed while maintaining the long-term average of 100 messages per 5-minute interval.

Result: If loglimit is not specified, the default value is the DefaultLogLimit value specified in the DMD configuration file. See z/OS Communications Server: IP Configuration Reference for more information about the DefaultLogLimit keyword.

lifetime

The length of time, in minutes, that the defensive filter remains in use. Valid values are in the range 1-20160. The default value is 30 minutes.

Tip: If the lifetime value exceeds the maximum lifetime value that is configured for a stack, the defensive filter's lifetime value is set to the maximum allowed lifetime value. The maximum lifetime value is configured with the MaxLifetime keyword in the DMD configuration file. See z/OS Communications Server: IP Configuration Reference for more information about the MaxLifetime keyword.

Results:

If you specified the value all (or is in effect by default) for both the srcip and destip parameters, a defensive filter is added to match any IPv4 source and destination address. If a stack supports IP security for IPv6, a defensive filter is also added to match any IPv6 source and destination address. If both an IPv4 and IPv6 filter are installed, the base name is the name that was specified when the filter was added. Different index values are assigned to each filter rule by the DMD.
If you specified the value all for either the scrip or destip parameter and a specific address family is specified for the other parameter, a defensive filter is added for the specific address family. For example, srcip all and destip 10.1.1.1 result in a defensive filter being added to match any IPv4 source address and a destination address of 10.1.1.1.
If both an IPv4 and IPv6 filter are installed and the protocol value is icmp or 1, type and code values are relevant only for the IPv4 filter. The IPv6 filter does not use the type and code values to determine whether an IPv6 packet matches the filter.
If both an IPv4 and IPv6 filter are installed and the protocol value is icmpv6 or 58, type and code values are relevant only in the IPv6 filter. The IPv4 filter does not use the type and code values to determine whether an IPv4 packet matches the filter.
If both an IPv4 and IPv6 filter are installed, the loglimit is applied both to the IPv4 filter and to the IPv6 filter.
If a defensive filter add specifies IPv6 addresses, the filter is added only to a stack that supports IP security for IPv6.

-N DefensiveFilterName: A string 1-32 characters in length that specifies the name of the defensive filter that is being added. The name cannot start with a dash (-). The name also cannot contain any commas (,). A comma is treated as delimiter by the ipsec command and it is therefore ignored.
Tip: Global and stack-specific defensive filters share the same name space; therefore, a filter name cannot be used for both a global filter and a stack-specific filter. If you are manually creating defensive filters, avoid conflicts between global and stack-specific filter names by selecting a distinct naming convention for each. For example, start all global filter names with the letter G.

update

Updates a defensive filter's characteristics. You cannot update an IP security filter with this option. You must update the IP security filter in the TCPIP profile or in a policy configuration file. You can modify the following defensive filter characteristics:

mode

The defensive filter mode. Valid values are:

block: Indicates that the defensive filter blocks or denies packets that match the characteristics of the filter.
simulate: Indicates that the defensive filter simulates a block. If a packet matches a defensive filter with the mode simulate, a log record is written to syslog indicating that the packet would have been denied by this filter. The packet is not denied and IP filtering continues.
Rule: If the mode value Simulate is configured for a TCP/IP stack in the DMD configuration file, it overrides the individual defensive filter's mode setting. For example, if a defensive filter is updated to be in block mode and the DmStackConfig statement for the stack where the filter is installed has a configured mode of Simulate, a packet that matches the defensive filter is not blocked. Instead, a block is simulated. The defensive filter retains the block mode. If the DmStackConfig statement for the stack is updated to be in Active mode, a packet that matches the defensive filter is blocked.

log

The logging action for a defensive filter.

yes: A log record is written when a packet matches this filter rule.
no: A log record is not written when a packet matches this filter rule.

Restrictions:

If the mode value is simulate and the log parameter is specified, the log value must be configured as yes.
If the mode parameter is not specified and the filter's mode is simulate, the log value (if it is specified) must be configured as yes.

Result: If mode is simulate and log is not specified, the log value is set to yes in the filter.

loglimit

0: Disables the limiting of defensive filter match messages written to syslogd. If logging is being done for this defensive filter, a message is generated for each packet that matches the defensive filter.
n: Enables the limiting of defensive filter-match messages written to syslogd. Valid values are in the range 1 - 9999. The value specifies the limit of the average rate of filter-match messages generated in a 5-minute interval for a defensive filter. For example, a value of 100 limits the average rate of filter-match messages to 100 messages per 5-minute interval. A burst of up to 100 messages is allowed while maintaining the long-term average of 100 messages per 5-minute interval.

lifetime

The additional time (in minutes) that the defensive filter remains in use from the time the update command is processed.

-N DefensiveFilterName

Specifies the name of the defensive filter that is to be updated. The name must correspond to the defensive filter rule name that was specified when the defensive filter was added.

delete

Deletes one or more defensive filters. You cannot delete an IP security filter with this option. You must remove IP security filters from the TCPIP profile or the policy configuration file.

-N DefensiveFilterName: Specifies one or more defensive filters that are to be deleted. The names must correspond to defensive filter rule names that were specified when the defensive filters were added.
-N all: Specifies that all defensive filters are deleted on the target stack (-p) or deleted globally (-G).