z/OS Communications Server - Group home

Egress and Ingress filtering with z/OS IP packet filters


By Chris Meyer and Joyce Anne Porter

As z/OS shops tighten their TCP/IP security, there is often a need to control which remote systems can connect outbound to other systems (egress connections) and which remote systems can connect inbound to the local system (ingress connections).   One of the lesser known, but very useful features of z/OS Communications Server is egress and ingress filtering provided through IP packet filters.  This article will explain how to use that feature through a simple example.

A couple quick notes before we start:

  • This article is not a comprehensive tutorial on coding z/OS IP packet filters. For more information on z/OS IP packet filtering, refer to the z/OS Communications Server IP Configuration Guide section on IP filtering and the z/OS Communications Server IP Configuration Reference sections on the TCPIP profile's IPSEC statement and the IP Security policy IpFilterRule statement.
  • IBM strongly encourages using the z/OSMF Network Configuration Assistant (NCA) to configure policy-based IP Security-related rules as the policy agent syntax can be rather complex -- especially if you are configuring IPsec protection. The NCA can also be used to configure your TCPIP profile, including the default IP packet filters.   For brevity of explanation, we will not focus on detailed navigation through the NCA, but will rather provide some guidelines for finding the relevant NCA dialogs and then describe the relevant rules in somewhat generalized terms.  

z/OS IP filtering basics

To get started, here is a quick review of some key points about z/OS IP packet filters.

IP packet filtering is enabled on a z/OS TCP/IP stack by specifying the IPCONFIG IPSECURITY parameter in that stack's TCPIP profile data set.   When enabled, each individual IP packet that enters or is about to leave the z/OS TCP/IP stack is evaluated against the installed set of IP packet filters.

IP packet filters are configured as part of the IP Security technology through the z/OSMF Network Configuration Assistant and the Policy Agent (IP Security also provides the z/OS IPsec implementation, but that is beyond the scope of this discussion, so we will ignore it here).  To permit specific IP traffic through the z/OS TCP/IP stack before the policy agent installs the configured policy-based IP filters, you must configure basic IP packet filters  in the TCPIP profile data set in the IPSEC statement (these are sometimes called default filters). Without these default filters, all IP packets are denied until Policy Agent installs the policy-based IP filters.

Tip: When initially enabling IPCONFIG IPSECURITY, consider creating default IP filter rules at that time to permit all traffic.  For example:



The default IP filter rules can be updated as you continue with your IP filter implementation and determine the network traffic that is required prior to the installation of policy-based IP filters.    

IP packet filter rules are composed of conditions that describe different packet attributes and the action to be taken when an IP packet is found to match the conditions. Some commonly used conditions are the packet's source and destination IP address, its IP protocol value (TCP, UDP, ICMP, etc.), and source and destination port values. The relevant actions for our purposes are to PERMIT the packet to continue to its destination or to DENY the packet, blocking it from proceeding any further (note that profile-based filters only support the PERMIT action to permit limited types of traffic while waiting for policy-based filters to be installed -- all other traffic is denied by default).  You can also configure logging actions along with the permit and deny actions but be aware that IP packet filters will produce a log message for every single IP packet that matches it, so you need to be thoughtful and careful about using the log action. Logging is best suited for debugging in a test environment.

Another condition you can code on an IP filter rule is the packet direction.  You can configure the rule to match on inbound packets only, outbound packets only, or packets going in either direction (bidirectional).  These bidirectional rules come into play for egress and ingress filtering.

When you configure a bidirectional rule, two rules are actually installed into the TCP/IP stack.  The first rule matches outbound packets with the specified source and destination IP address or port. The second rule matches inbound packets with the source and destination specification reversed from that of the outbound rule.   It is important to remember that the orientation of bidirectional rules is from the local z/OS sender's perspective.

Finally, the order in which you configure your IP packet filters is very important.  IP packet filters are evaluated in the same order as they are specified in your IP filter list.  The first filter that matches the packet is the one that is used – even if there is a more specific filter later in the list that would be a better match.  Because of this, the most specific filters should always precede those that are less specific in the list of rules.  If an IP packet does not match any of the installed packet filters, then that packet will be denied.   Think of this as having an implicit "deny all traffic" rule at the very bottom of your filter list.

Using packet filters to control non-TCP traffic

Before we dig into controlling TCP connections, let's take a quick look at how you can use IP packet filters to control the use of protocols like UDP and ICMP on your z/OS system.  For protocols other than TCP, controls are specified purely at the IP packet level. Any given packet is traveling either inbound or outbound relative to the z/OS TCP/IP stack. 

Here is a very simple example to illustrate basic IP filtering.  Assume we have the following goals for UDP and ICMP traffic using local z/OS address

  1. Allow UDP traffic inbound and outbound between local z/OS address to remote DNS server (port 53) at
  2. Do not allow any other UDP traffic
  3. Allow outbound ICMP traffic from to any IP address
  4. Block all inbound ICMP traffic to (in practice, you would probably want to allow some types and codes to allow for inbound ping requests and responses)
  5. Allow all other IP traffic

The following set of rules will accomplish these goals (remember, bidirectional rules are specified from the sender's orientation): 

  • Rule 1 – PERMIT UDP bidirectional between and port 53
  • Rule 2 – DENY UDP bidirectional between and all IP addresses
  • Rule 3 – PERMIT ICMP outbound from to all IP addresses
  • Rule 4 – DENY ICMP inbound from all IP addresses to (to allow inbound ping requests and responses, you would precede this rule with  PERMIT rules for the appropriate ICMP types and codes)
  • Rule 5 – PERMIT ALL bidirectional between and all IP addresses

These rules closely mirror the stated goals and their behavior is as described.  Note the importance of the rule order here. IP packets will be evaluated against the rules in the same order they are coded in the policy, so the most specific rules must be specified first, followed by the broader ones.  For example, if we reversed the order of rules 1 and 2, all UDP traffic (including that to port 53) would match the DENY rule.

Using packet filters to control TCP connections

So, if IP packet filters operate on individual packets, how can you control TCP connections based on their initiation direction?  To understand this, it is important to understand the basic sequence used to establish a new TCP connection. 

A TCP connection is established through something called a TCP three-way handshake.  A successful three-way handshake involves the exchange of three IP packets:

  1. The connection initiator sends a TCP SYN packet to the target
  2. The target responds with a TCP SYN-ACK packet to the initiator
  3. The initiator completes the handshake with a TCP ACK packet.

Once the ACK packet is received by the target, the TCP connection is established and it can be used to send data back and forth.

The SYN packet is the key to TCP egress and ingress filtering using z/OS IP packet filters.   Two special cases of bidirectional filters are used to recognize the TCP SYN packet, either outbound or inbound, as the initiation of a TCP connection.   These are called outbound connect (egress) rules and inbound connect (ingress) rules, respectively.

So how exactly do outbound connect and inbound connect rules work?  Remember these are special cases of bidirectional rules – those that match on both outbound and inbound IP packets between the specified endpoints.  The special part is in the way they handle TCP SYN packets:

  • The outbound connect rule matches on any outbound or inbound TCP packet except for an inbound TCP SYN packet.
  • Likewise, the inbound connect rule matches on any outbound or inbound TCP packet except for an outbound TCP SYN packet.

It is very important to understand this focus on special handling of the SYN packet, especially in relation to DENY rules.  When you want to DENY connections based on the connection direction, it is not sufficient to configure only a DENY rule for that traffic. On its own, an inbound connect or outbound connect rule with a DENY action will deny connections established in EITHER direction. The DENY rule MUST be preceded by a PERMIT rule for the direction in which traffic is to be allowed.

Here is a simple example that illustrates how these rules work in practice.  Assume we have the following goals for TCP traffic using local z/OS address

  1. Allow outbound connections from local z/OS address to remote address, only to port 45678 on the remote host
  2. Block outbound connections from to any other ports on
  3. Allow inbound connections from to any port on local z/OS address
  4. Allow all TCP connections between and any other remote IP address

The following set of rules will accomplish these goals (remember, bidirectional rules are specified from the sender's orientation): 

  • Rule 1 – PERMIT TCP bidirectional outbound connect between and port 45678
  • Rule 2 – PERMIT TCP bidirectional inbound connect and
  • Rule 3 – DENY TCP bidirectional outbound connect between and
  • Rule 4 – PERMIT TCP bidirectional between and all IP addresses

So let's see how these rules achieve our goals:

  • Outbound SYN packets from to port 45678 match rule 1 and are permitted. This rule also matches any other packets between the local address and the remote address/port EXCEPT for an inbound SYN packet, which would "fall through" to subsequent rules. (This rule covers goal 1)
  • Inbound SYN packets from to local z/OS address fall through rule 1 and match rule 2 which permits them. Any other inbound or outbound packets (SYN/ACK, ACK, and later data packets) between and would also match this PERMIT rule EXCEPT for:
    • outbound SYN packets (these fall through to subsequent rules)
    • any other packet to/from port 45678 and local z/OS address (these would have matched rule 1)

(This rule covers goal 3)

  • Outbound SYN packets from to for any other port fall through rules 1 and 2 to match rule 3 and are denied. Since the SYN is blocked, no other packets would flow between the two addresses for these outbound connections.  (This rule covers goal 2).
  • Any packets between and any other IP address would fall through rules 1 through 3 and would match rule 4. (This rule covers goal 4)

This example illustrates some key points.  First, the order of the IP filter rules is very important since each packet will be evaluated against the filter rules in the order that they are configured. More specific rules should be configured before broader rules.  For example, if we moved rule 3 to the top of the list in front of rule 1, then connections to port 4678 would match the broader rule and never get to the port-specific rule.   Second, for eqress and/or ingress rules, PERMIT rules must precede the associated DENY rules.  For example, if we moved rule 3 between rules 1 and 2, the SYN/ACK packets for both inbound and outbound connections would be denied, preventing inbound connections from completing, even though the inbound SYN was permitted.

The bottom line: When you want to DENY TCP connections based on the connection direction, it is not sufficient to configure only a DENY rule for that traffic. The DENY rule MUST be preceded by a PERMIT rule for the direction in which connection is to be allowed.

One final point.  If you wanted to combine these TCP rules with the non-TCP rules shown earlier, you would just need to place the TCP rules somewhere before the "permit all IP traffic" rule (rule 5).  Since all the other rules are protocol-specific, they would not overlap with the TCP rules.

So where do I configure these rules?

As mentioned at the beginning of this article, IBM recommends using the z/OSMF Network Configuration Assistant (NCA) to configure IP filter rules.  Use the following objects under the NCA's IPSec perspective to configure TCP outbound connect and inbound connect rules:

  • The Traffic Descriptor object describes an application's traffic. You can configure conditions like protocol, port and TCP connection direction.  To describe TCP egress and TCP ingress traffic, select TCP as the protocol and then select the appropriate connection direction.
  • The Requirement Map object associates a Traffic Descriptor with an action to cause that type of traffic to be permitted or denied.
  • Use the Rule object to associate local and/or remote IP addresses to the egress or ingress Requirement Map.

If you are not yet familiar with the NCA, there are some very good tutorials in the online help to get you started.  

If you are simply unable to use the NCA and are forced to code your IP filtering policy by hand, you can create TCP egress and ingress filters by specifying Protocol TCP with either Direction Bidirectional OutboundConnect or Direction Bidirectional InboundConnect on the IpService statement associated with the IPFilterRule statement.    Make sure to specify TCP (or 6) for the IP protocol to ensure these rules do not interfere with other IP traffic between the specified endpoints.

Wrapping it up

IP packet filtering provides very granular control over the traffic on your z/OS systems.  Rules can be fairly straightforward for most protocols like UDP and ICMP.  Using sets of TCP outbound connect and TCP inbound connect rules, with the PERMIT rules placed before the associated DENY rules, provides all the flexibility you should need to carefully craft a complete set of TCP egress and ingress rules that will help secure your z/OS systems and satisfy your auditors.   Hopefully, this article gives you the tools you need to successfully deploy your own egress and ingress filters.


Authors and Acknowledgements

Chris Meyer is a Senior Technical Staff Member and the z/OS network security architect.

Joyce Anne Porter is a Senior Software Engineer and the lead security developer on the z/OS Communications Server team.

The authors would like to thank Chad Rikansrud of BMC Software for his valuable insights and input as we wrote this article.