The GATEWAY statement will not be supported in a
future release. It is recommended that you use the BEGINROUTES/ENDROUTES
statement block instead of the GATEWAY statement.
To use IPCS to create BEGINROUTES
statements from the existing specification, run the TCPIPCS PROFILE
report on a dump of the TCP/IP address space. Static routes
are presented as a BEGINROUTES/ENDROUTES statement block even
if you code the static routes by using a GATEWAY statement.Use the GATEWAY statement to add static routes to the main route table. If you want to specify static routes in a BSD style syntax or if you need to define routes for interfaces defined with the INTERFACE statement, see BEGINROUTES statement. To configure policy-based route tables, use the RouteTable statement. For more information, see the policy-based routing information in z/OS Communications Server: IP Configuration Guide.
IBM® Health Checker for z/OS® can be used to check whether the total number of indirect routes in a TCP/IP stack routing table exceeds a maximum threshold. When this threshold is exceeded, OMPROUTE and the TCP/IP stack may potentially experience high CPU consumption from routing changes. A large routing table is considered to be inefficient in network design and operation. For more details about IBM Health Checker for z/OS, see z/OS Communications Server: IP Diagnosis Guide and IBM Health Checker for z/OS: User's Guide..
The IP static routes can be modified in the following ways:
- Replace the routing table using the VARY TCPIP,,OBEYFILE command.
- Use incoming ICMP redirect packets if redirects have not been disabled on the IPCONFIG statement.
The first GATEWAY statement of each configuration data set that is issued replaces all the static routes in the existing routing table with the new gateway information. All static routes and any dynamic routes added as a result of ICMP redirects are deleted. Routes created by OMPROUTE are not deleted. Subsequent GATEWAY statements in the same data set add entries to the routing table.
- The GATEWAY statement applies only to IPv4 interfaces that are defined with the LINK statement.
- A GATEWAY statement and a BEGINROUTES-ENDROUTES block cannot be intermixed in the same configuration data set. If they are intermixed, the first type found is used and the other type is discarded with warning messages being issued to the console. You can use a GATEWAY statement in the initial profile and a BEGINROUTES-ENDROUTES block in the data set specified on a later VARY TCPIP,,OBEYFILE command, and vice versa.
- Route entries on the GATEWAY statement can be coded only for LINK names that exist when the entry is processed.
- Static routes that you define using the GATEWAY statement cannot be replaced by dynamic routes learned by OMPROUTE. If you want OMPROUTE to begin managing all routes, use an empty GATEWAY statement block in a VARY TCPIP,,OBEYFILE command data set to eliminate the existing static routes. OMPROUTE discovers the changes dynamically. If you want to define static routes that can be replaced by dynamic routes learned by OMPROUTE, use the BEGINROUTES statement.
- VIPA links are not allowed on the GATEWAY statement.
- When an incorrect entry in a GATEWAY statement is encountered, it is discarded along with the remaining entries in the GATEWAY statement. All routes defined before the incorrect entry are added to the main route table. Subsequent GATEWAY statements in the same profile data set or in the VARY TCPIP,,OBEYFILE command data set are processed.
- A specific host route takes precedence over a subnetwork route, followed by a network route, followed by a supernetwork route, and finally, a default route.
- To add a route over a MPCPTP link to another IP address (for example a VIPA) on the remote host, you need to add an indirect route. This indirect route should have a destination equal to the other IP address, a first_hop value equal to the remote IP address of the MPCPTP link, and a link_name value equal to the name of the MPCPTP link.
Rule: Specify the required parameters in the order shown here. The optional parameters can be specified in any order.
Syntax
.------------------------. V | >>-GATEway----| Gateway List Entry |-+------------------------->< Gateway List Entry |--+-| Gateway Network Specification |---------+----------------> +-| Gateway Host Specification |------------+ '-| Gateway Default Network Specification |-' >--| Gateway List Entry Options |-------------------------------| Gateway Network Specification |--network--+-first_hop-+----link_name----+-max_packet_size-+---> '- = -------' '-DEFAULTSIZE-----' >--+-subnet_mask--subnet_value-+--------------------------------| '-0-------------------------' Gateway Host Specification |--host--+-first_hop-+--link_name--+-max_packet_size-+----HOST----| '- = -------' '-DEFAULTSIZE-----' Gateway Default Network Specification |--+-DEFAULTNET-+----first_hop------link_name-------------------> '-DEFAULT----' >--+-max_packet_size-+----0-------------------------------------| '-DEFAULTSIZE-----' Gateway List Entry Options .-MAXImumretransmittime 120.00----. |--+---------------------------------+--------------------------> '-MAXImumretransmittime --seconds-' .-MINImumretransmittime 0.50------. >--+---------------------------------+--------------------------> '-MINImumretransmittime --seconds-' .-ROUNDTRIPGain 0.125---. .-VARIANCEGain 0.25----. >--+-----------------------+--+----------------------+----------> '-ROUNDTRIPGain --value-' '-VARIANCEGain --value-' .-VARIANCEMultiplier 2.00----. .-DELAYAcks---. >--+----------------------------+--+-------------+--------------| '-VARIANCEMultiplier --value-' '-NODELAYAcks-'
Parameters
- network
- The IP address in dotted decimal form.
- An example of a class A network is 9.0.0.0.
- An example of a class B network is 129.34.0.0.
- An example of a class C network is 192.9.100.0.
Use the subnet_mask and subnet_value fields to completely define the route. Multiple network routes having an identical destination IP address and address mask can be specified. When multiple routes are specified, all of them are used when multipath is enabled on the IPCONFIG statement; otherwise, only the first active route specified is used.
- first_hop
- Specify one of the following values:
- An equal sign (=), meaning that datagrams are routed directly to destinations on that network or directly to that host over the interface that is identified by link_name. This is not supported for DEFAULT or DEFAULTNET.
- The IP address of a gateway or router that you can reach directly, and that forwards datagrams for the destination network or host over the interface that is identified by link_name. The address must be a host address that uniquely identifies the gateway or router. It cannot be a local IP address on this TCP/IP stack. A local IP address can be defined on the HOME, INTERFACE, VIPADEFINE, or IPCONFIG DYNAMICXCF statement. The IP address must be a fully qualified address in the form a.b.c.d.
- link_name
- The name of the link through which packets are sent to the specified network. The link name is defined in a LINK statement.
- max_packet_size
- The maximum transmission unit (MTU) in bytes for the network or
host. This value can be up to 65535.
See Figure 1 for more information about the largest MTU value supported by each link type.
The DEFAULTSIZE keyword sets the max_packet_size to 576. This value is the minimum MTU that an IPv4 network should use. See Usage notes for packet size considerations.
Tip: See z/OS Communications Server: IP Configuration Guide, under section, Maximum transmission unit considerations, for additional information about how TCP/IP uses the MTU to determine the largest size frame to send.
- subnet_mask
- A bit mask (expressed in dotted
decimal form) having bits in the network portions or host portions,
or both, that defines the subnet mask associated with the route. If
a route to the network is not subnetted, specify a subnet mask of
0 and omit the subnet value. For a specific host route, specify a
subnet mask of HOST and omit the subnet value.
Restriction: The mask bits of all ones in the host portion cannot be used for the subnet mask.
The valid values are:
- A dotted decimal bit mask
- 0
- Host
- subnet_value
- Value of the subnet. Each subnet should have a unique dotted decimal
representation. Do not include the subnet_value field
if the subnet_mask is 0, HOST, or contains
a supernet mask.
If the network has one or more subnets, specify a separate entry in the GATEWAY statement for each subnet. The network part of each GATEWAY entry is identical (contains the IP network address as if the network has no subnets). The subnet_mask part of each GATEWAY entry might be identical, but the subnet_value varies.
- host
- The host address, specified as 4 octets (192.9.100.3, for example). If a host address is specified, the keyword HOST must be specified in place of the subnet_mask value, and the subnet_value value must be omitted. Multiple host routes having an identical destination IP addresses and address masks can be specified. When multiple routes are specified, all of them are used when multipath is enabled on the IPCONFIG statement; otherwise, only the first active route specified is used.
- DEFAULTNET
- Specifies a route to use for any destination that is not covered by an explicit route. You can specify multiple DEFAULTROUTE entries to provide multiple default routes. When you specify multiple routes, all of them are used when multipath is enabled on the IPCONFIG statement; otherwise, only the first active route that is specified is used. The DEFAULT and DEFAULTROUTE parameters are interchangeable.
- DEFAULT
- Specifies a route to use for any destination that is not covered by an explicit route. You can specify multiple DEFAULT entries to provide multiple default routes. When you specify multiple routes, all of them are used when multipath is enabled on the IPCONFIG statement; otherwise, only the first active route that is specified is used. The DEFAULT and DEFAULTROUTE parameters are interchangeable.
Retransmission parameter considerations
The parameters listed in this topic affect the TCP retransmit algorithms. When TCP packets are not acknowledged, TCP begins to retransmit these packets at certain time intervals. If these packets are not acknowledged after a specified number of retransmits, TCP aborts the connection. The time interval between retransmissions increases by approximately twice the previous interval until the packets are acknowledged or the connection times out.
The time intervals between retransmissions and the number of times that packets are retransmitted before the connection times out differs for initial connection establishment and for data packets . For initial connection establishment, the initial time interval is set at approximately 3 seconds and the SYN packet is retransmitted 5 times before the connection is timed out. Data packets use a smoothed Round Trip Time (RTT) as the initial time interval, and data packets are retransmitted 15 times before the connection is timed out. All of the remaining parameters listed in this topic affect the data packet retransmission algorithm. Only the MINIMUMRETRANSMITTIME parameter affects the initial connection establishment.
- TCP typically waits to receive two packets before sending one ACK to acknowledge the data within them.
- When TCP sends a packet, it waits for an acknowledgment. If it times out before getting an acknowledgment, it resends the packet.
- MAXIMUMRETRANSMITTIME
- MINIMUMRETRANSMITTIME
- ROUNDTRIPGAIN
- VARIANCEGAIN
- VARIANCEMULTIPLIER
- DELAYACKS
- NODELAYACKS
- A smoothed round trip time (SRTT) and variance (VAR) is updated from the individual RTT derived from each packet acknowledgement.
- The retransmit time for a new packet is set to twice (approximately) the current SRTT value plus the VAR value.
- Each time a packet is retransmitted, the retransmit time value is doubled.
- The actual interval time used for the initial packet and each retransmission is the retransmit time calculated previously, but limited by the configured MINIMUMRETRANSMITTIME and MAXIMUMRETRANSMITTIME values.
- DELAYACKS | NODELAYACKS
- Controls transmission of acknowledgments when a packet is received
with the PUSH bit on in the TCP header.
- NODELAYACKS
- Specifies that an acknowledgment is returned immediately when a packet is received with the PUSH bit on in the TCP header. The NODELAYACKS parameter on the BEGINROUTES, GATEWAY, and RouteTable statements affects only the connections that use this route. Specifying NODELAYACKS on the TCP/IP stack BEGINROUTES or GATEWAY profile statements, or on the Policy Agent RouteTable statement, overrides the specification of the DELAYACKS parameter on the TCP/IP stack PORT, PORTRANGE, and TCPCONFIG profile statements.
- DELAYACKS
- Delays transmission of acknowledgments when a packet is received with the PUSH bit on in the TCP header. The DELAYACKS parameter on the BEGINROUTES, GATEWAY, and RouteTable statements affects only the connections that use this route. This is the default, but you can override the default by specifying the NODELAYACKS parameter on the TCP/IP stack PORT, PORTRANGE, or TCPCONFIG profile statements.
- MAXIMUMRETRANSMITTIME
- Limits the TCP retransmission interval. Decreasing this value might decrease the total time it takes a connection to timeout. Specifying MAXIMUMRETRANSMITTIME assures that the interval time never exceeds the specified limit. The minimum value that can be specified for MAXIMUMRETRANSMITTIME is 0. The maximum is 999.990. The default is 120 seconds. This parameter does not affect initial connection retransmission.
- MINIMUMRETRANSMITTIME
- Sets a minimum retransmit interval. Increasing this value might increase the amount of time it takes for TCP to time out a connection. The minimum value that can be specified for MINIMUMRETRANSMITTIME is 0. The maximum is 99.990. The default is 0.5 (500 milliseconds).
- ROUNDTRIPGAIN
- This value is the percentage of the latest Round Trip Time (RTT) to be applied to the smoothed RTT average. The higher this value, the more influence the latest packet RTT has on the average. The minimum value that can be specified for ROUNDTRIPGAIN is 0. The maximum value is 1.0. The default is 0.125. This parameter does not affect initial connection retransmission.
- VARIANCEGAIN
- This value is the percentage of the latest RTT variance from the RTT average to be applied to the RTT variance average. The higher this value, the more influence the latest packet's RTT has on the variance average. The minimum value that can be specified for VARIANCEGAIN is 0. The maximum value is 1.0. The default is 0.25. This parameter does not affect initial connection retransmission.
- VARIANCEMULTIPLIER
- This value is multiplied against the RTT variance in calculating the retransmission interval. The higher this value, the more affect variation in RTT has on calculating the retransmission interval. The minimum value that can be specified for VARIANCEMULTIPLIER is 0. The maximum value is 99.990. The default is 2. This parameter does not affect initial connection retransmission.
Retransmission parameters
Use the ROUNDTRIPGAIN, VARIANCEGAIN, and VARIANCEMULTIPLIER parameters to instruct TCP how heavily to weigh the most recent behavior of the network versus the long term behavior for updating the SRTT and VAR values. If you specify smaller values for these parameters, TCP attempts to correct for congestion only if the congestion is sustained. With larger values, TCP corrects for congestion more quickly, and the system is more sensitive to variations in network performance. Use the default values (unless your retransmission rate is too high).
Use DELAYACKS to delay the acknowledgments so that they can be combined with data sent to the foreign host.
Steps for modifying
- If any HOME list entries are changed or deleted, all static routes using the associated links are deleted.
- If a LINK becomes inactive, then all routes that are associated with that link are marked inactive.
- If a LINK becomes active, then all static routes that are associated with that link are marked active.
For more information about the VARY TCPIP commands, see z/OS Communications Server: IP System Administrator's Commands.
Usage notes
- Packet size considerations The actual packet size is determined by the total network connection.
- The max_packet_size varies for different networks. For example, the largest packet size for the Ethernet protocol network is 1500 bytes while the largest packet size for the IEEE 802.3 protocol network is 1492 bytes.
-
- If a locally attached host has a packet size smaller than yours, transfers to that host use the smaller size.
- The TCP maximum segment size for the 3172 Interconnect Controller Program is 4096. Any packet specifications over 4096 are limited by this restriction. For example, if you specified a packet size of 4352, the resulting packet size would still only be 4096 + the header = 4132.
- Large packets can be fragmented by intervening gateways. Fragmentation
and reassembly of packets are expensive in their use of bandwidth
and CPU time. Therefore, packets sent through gateways to other networks
should use the default size, DEFAULTSIZE, unless one of the following
situations is true:
- All intervening gateways and networks are known to accept larger packets
- Path MTU discovery is enabled on the IPCONFIG statement, which results in the TCP/IP stack dynamically learning the maximum MTU for the total network connection.
GATEWAY ; Network first-hop link packet-size subnet-mask 192.8.4 14.0.0.10 LINK1 576 0 - You cannot specify an MTU smaller than the default MTU size. For IPv4, the default MTU is 576.
- Requirement: The subnet_mask must follow the Classless Inter-Domain Routing (CIDR) convention that requires the actual mask to be one or more on-bits followed by zero or more off-bits. You cannot have on-bits followed by off-bits followed by on-bits. Therefore, a class A subnet mask of 0.255.254.0 is valid (an actual mask of 255.255.254.0 or FFFFE00), but a class A subnet mask of 0.255.253.0 is not valid (an actual mask of 255.255.253.0 or FFFFD00) because 253 is 11111101.
- The first GATEWAY statement of each profile data set or VARY TCPIP,,OBEYFILE command data set deletes only IPv4 routes. Any IPv6 static routes added previously are not deleted. The IPv6 routes must have been added using the BEGINROUTES statement.
- If the routing table is empty, all addresses in the HOME list are still route-capable. For information about testing commands with LOOPBACK, see the z/OS Communications Server: IP User's Guide and Commands.
- There is no limit on the number of equal-cost multipath routes to a destination.
- Multicast routes can be specified using host specification. A
general multicast default route can be specified using the multicast
group address of 224.0.0.0:
GATEWAY ;Host First hop Link packet size 224.0.0.0 = LINK1 DEFAULTSIZE HOSTSpecific multicast group routes can also be specified:
GATEWAY ;Host First hop Link packet size 224.1.1.1 = LINK2 DEFAULTSIZE HOSTThe order of precedence for determining the route of an outbound multicast datagram is as follows:
- Application uses setsockopt() IP_MULTICAST_IF to specify the interface to use.
- The specific multicast group route that is specified.
- Multicast network or prefix route.
- The general multicast default group address that is specified (224.0.0.0).
- If a default route is specified and the route's link is multicast capable.
- If an application sends a datagram to 224.2.2.2, LINK1 is used.
- If an application sends a datagram to 224.1.1.1, LINK2 is used.