SRCIP statement

Use the SRCIP statement to do the following tasks:

Restriction: Only one SRCIP block should appear in a configuration data set. Any subsequent SRCIP blocks are ignored and an informational message is displayed. If a syntax error is encountered when this statement is processed, an error message is displayed and the entire SRCIP block is ignored (no entries are processed).

Guidelines:
  • The SRCIP block does not require you to specify the SOURCEVIPA parameter on either the IPCONFIG statement or the IPCONFIG6 statement.
  • SRCIP JOBNAME and DESTINATION entries can appear in any order. If an outbound connection matches more than one JOBNAME or DESTINATION entry, the following order of precedence is used:
    1. A match on the most specific JOBNAME entry with at least one, non-wildcard character (this excludes JOBNAME *)
    2. A match on the most specific DESTINATION entry
    3. A JOBNAME * entry

Designating source IP addresses for TCP connections

The SRCIP statement supports a combination of JOBNAME and DESTINATION entries to designate source IP addresses. Use the SRCIP JOBNAME statement to designate source IP addresses to be used for TCP applications identified by specified jobs. Use the SRCIP DESTINATION statement to designate source IP addresses to be used for outbound TCP connections destined for specified IP addresses, networks or subnets.

These source IP addresses override source IP address specification based on:

See the information about source IP address selection in z/OS Communications Server: IP Configuration Guide for the hierarchy of ways that the source IP address of an outbound connection is determined.

Guideline: Applications that bind to INADDR_ANY or to the unspecified IPv6 address (in6addr_any), and that match on a SRCIP JOBNAME or DESTINATION statement, do not have the designated IP address as its source address upon completion of the bind() call. The source address is not set to the designated address until completion of the subsequent connect() (client applications) or listen (server applications) call. This is important to note for applications that issue a getsockname() call after a bind() call.

Designating whether to prefer a public IPv6 address or a temporary IPv6 address

Use the SRCIP JOBNAME statement to indicate whether to prefer a public IPv6 address or a temporary IPv6 address for an application that is identified by the specified job name. The preference for temporary or public IPv6 addresses is part of selecting a source address for an outbound packet using the algorithm for source address selection. For more information about default source IP address selection and about using IPv6 temporary addresses, see z/OS Communications Server: IPv6 Network and Application Design Guide.

Syntax

Rule: Specify the parameters for JOBNAME or DESTINATION entries in the order shown here. 

Read syntax diagramSkip visual syntax diagram
>>-SRCIP-------------------------------------------------------->

   .----------------------------------------------------------------.   
   V                                                                |   
>----+------------------------------------------------------------+-+-->
     +-DESTINATION--+-dstv4_addr--srcv4_addr--------------------+-+     
     |              +-dstv4_addr/prefixlen--srcv4_addr----------+ |     
     |              +-dstv6_addr--+-srcv6_addr------+-----------+ |     
     |              |             '-srcv6_intf_name-'           | |     
     |              '-dstv6_addr/prefixlen--+-srcv6_addr------+-' |     
     |                                      '-srcv6_intf_name-'   |     
     '-JOBNAME--jobname--+-| Source IP |-+------------------------'     
                         +-TEMPADDRS-----+                              
                         '-PUBLICADDRS---'                              

>--ENDSRCIP----------------------------------------------------><

Source IP

                        .-CLIENT-.   
|--+-srcv4_addr------+--+--------+------------------------------|
   +-srcv6_addr------+  +-SERVER-+   
   '-srcv6_intf_name-'  '-BOTH---'   

Parameters

DESTINATION
Designates a source address or interface to be used for outbound TCP connections with destinations that match the specified destination address or network.

Restriction: The source address specified in a matching SRCIP DESTINATION entry cannot be a distributed DVIPA unless the GLOBALCONFIG EXPLICITBINDPORTRANGE profile parameter is configured and one of the following situations exist:

  • The application issued a connect request without a prior explicit bind.
  • The source port for the outbound TCP connection socket was explicitly bound to port 0, to a specified port that is less than 1024, or to a port that is reserved for this job by a PORT or PORTRANGE profile statement.

If GLOBALCONFIG EXPLICITBINDPORTRANGE is not configured or if the source port is explicitly bound to an ephemeral port (equal to or greater than 1024) that is not reserved for this job, the connection request fails.

Rule: If the source port is less than 1024 or is a port that is reserved for this job and the specified source is a distributed DVIPA, you must ensure that multiple outbound connections to the same destination IP address and port cannot occur concurrently with the same source IP address and port.

A match to a SRCIP DESTINATION entry cannot be identified until a connect request is issued and the destination is known. However, some applications establishing outbound TCP connections might issue an explicit bind socket API prior to issuing the connect request. The port that is assigned or specified during this early bind processing might not be available across the sysplex for the destination-specific source IP address that is determined later at connect request time. If the port is not available, then an ambiguous situation might occur in which multiple outbound connections to the same destination IP address and port have the same source IP address and port. For this reason, the use of distributed DVIPAs on a SRCIP DESTINATION statement is not allowed without a GLOBALCONFIG EXPLICITBINDPORTRANGE statement configured on this stack.

Guideline: If you use distributed DVIPAs for the source IP address in a SRCIP DESTINATION entry, you should specify the SYSPLEXPORTS keyword on the VIPADISTRIBUTE statement for those distributed DVIPAs.

If duplicate destination values are specified in the SRCIP block, the first DESTINATION entry is used, any subsequent DESTINATION entry with a duplicate destination value is ignored, and a message is displayed.

If an outbound TCP connection's destination address matches more than one SRCIP destination address, the source address selected is determined by the most complete match. For example, suppose the following DESTINATION entries are specified in the SRCIP statement: 
DESTINATION  9.67.0.0/16    10.1.1.1
DESTINATION  9.67.37.0/24   10.1.1.2

A destination address of 9.67.37.5 matches both DESTINATION entries, but 9.67.37.0/24 is the most specific match and 10.1.1.2 is selected as the source IP address for the outbound connection.

A DESTINATION designation is ignored if the job name for the connection matches any JOBNAME entry other than JOBNAME *.

dstv4_addr
IPv4 host address to be matched by the destination IP address of an outbound TCP connection request. This is the destination IP address with which a specified source address is associated
dstv4_addr/prefixlen
Subnet or network address to be matched by the destination IP address of an outbound TCP connection request. This is the destination IP subnet or network that a specified source address is associated with. The dstv4_addr value is a fully qualified IPv4 IP address and the prefixlen value is a decimal value in the range 1 - 32 that specifies how many of the leftmost contiguous bits of the address comprise the prefix.
dstv6_addr
IPv6 host address to be matched by the destination IP address of an outbound TCP connection request. This is the destination IP address that a specified source address or interface name is associated with. See Restrictions on IPv6 addresses configured in the TCP/IP profile for a list of restrictions that must be observed when specifying this parameter. If the stack is not IPv6-enabled and an IPv6 IP address is specified, the DESTINATION entry is ignored and a message is displayed.
dstv6_addr/prefixlen
Prefix address to be matched by the destination IP address of an outbound TCP connection request. This is the destination IP subnet or network that a specified source address or interface name is associated with. The dstv6_addr value is a fully qualified IPv6 IP address and the prefixlen value is a decimal value in the range 1 - 128 that specifies how many of the leftmost contiguous bits of the address comprise the prefix.

See Restrictions on IPv6 addresses configured in the TCP/IP profile for a list of restrictions that must be observed when specifying this parameter. If the stack is not IPv6-enabled and an IPv6 IP address is specified, the DESTINATION entry is ignored and a message is displayed.

srcv4_addr
IPv4 host address to be used as a source IP address if the associated destination address is matched. The specified IP address does not need to be defined prior to the processing of the SRCIP block but it must be defined before the first TCP connect request is issued for the associated destination, otherwise the connect request fails.

The srcv4_addr value is a static VIPA, a dynamic VIPA, or a real IPv4 address associated with a physical interface. If a dynamic VIPA is used, it can be defined by a VIPADEFINE statement or previously activated with bind() or the IOCTL SIOCSVIPA value within a range of VIPAs.

Restrictions:
  • An IPv4 source address cannot be specified for an IPv6 destination address.
  • A distributed DVIPA cannot be specified for the source IP address in a DESTINATION entry unless the EXPLICITBINDPORTRANGE parameter on a GLOBALCONFIG statement is configured on this stack.
srcv6_addr
IPv6 host address to be used as a source IP address if the associated destination address is matched. The IPv6 IP address is in colon-hexadecimal format. A prefix_length cannot be specified. See Restrictions on IPv6 addresses configured in the TCP/IP profile for a list of restrictions that must be observed when specifying this parameter. If the stack is not IPv6-enabled and an IPv6 IP address is specified, the DESTINATION entry is ignored and a message is displayed. The specified IP address does not need to be defined prior to the processing of the SRCIP block, but it must be defined before the first TCP connect request is issued for the associated destination; otherwise, the connect request fails.

The srcv6_addr value is a static VIPA, a dynamic VIPA, or a real IPv4 address associated with a physical interface. If a dynamic VIPA is used, it can be defined by a VIPADEFINE statement or previously activated with bind() or a IOCTL SIOCSVIPA6 value within a VIPARANGE statement.

Restrictions:
  • An IPv6 source address cannot be specified for an IPv4 destination address.
  • A distributed DVIPA cannot be specified for the source IP address in a DESTINATION entry unless the EXPLICITBINDPORTRANGE parameter on a GLOBALCONFIG statement is configured on this stack.
srcv6_intf_name
The name of an IPv6 static VIPA, dynamic VIPA interface, or a physical interface to be used as a source interface if the associated destination address is matched. The maximum length is 16 characters. If a dynamic VIPA is used, it can be defined by a VIPADEFINE statement or previously activated with bind() or the IOCTL SIOCSVIPA6 value within a VIPARANGE statement. If the stack is not IPv6-enabled, the DESTINATION entry is ignored and a message is displayed. The specified interface does not need to be defined prior to the processing of the SRCIP block, but it must be defined before the first TCP connect request is issued for the associated destination; otherwise, the connect request fails. If the interface has multiple IP addresses, then the source IP address for the outbound connection is selected from among these addresses according to the default source address selection algorithm. For more information, see the default source address selection algorithm information in z/OS Communications Server: IPv6 Network and Application Design Guide.
Restrictions:
  • An IPv6 source interface cannot be specified for an IPv4 destination address.
  • A distributed DVIPA cannot be specified for the source IP address in a DESTINATION entry unless the EXPLICITBINDPORTRANGE parameter on a GLOBALCONFIG statement has been configured on this stack.
JOBNAME
Use this keyword to do one of the following:

If a connection request matches both a job name value other than JOBNAME * and a SRCIP destination address, the matching JOBNAME entry is used; otherwise, the matching DESTINATION entry is used.

Designate source IP addresses for TCP connections

Use the following parameters to designate source IP addresses for TCP connections.

jobname
Specifies the MVS™ job name of the application with which the specified source IP address is associated. The jobname value can be up to 8 characters in length. A trailing asterisk (*) indicates a wildcard specification. If you specify an asterisk (*), then all qualifying TCP applications, except those whose destination matches a SRCIP destination address on connect requests, are associated with the specified source IP address or interface; any existing specifications indicated by TCPSTACKSOURCEVIPA parameter are overridden. If similar prefixes are specified (for example, PAY* and PAYR*), then the actual source IP address associated with a job name is determined by the most complete match between the prefix and the job name. For example, an application whose job name is PAYROLL would match the PAYR* JOBNAME entry, not the PAY* JOBNAME entry.

If you want to associate one job name with both an IPv4 and an IPv6 IP address, specify two JOBNAME entries in which the jobname value is the same but the IP addresses are of different IP address families. If duplicate job names are specified in the same SRCIP block, and the duplicate entries specify an IP address of the same IP type (for example, both entries specify IPv4 or both specify IPv6 IP address types) the first JOBNAME entry is in effect. Any duplicate JOBNAME entries are ignored and messages are displayed.

If duplicate job names are specified in the same SRCIP block, and one of the entries specifies an IPv6 address or interface and the other entry specifies TEMPADDRS, the first JOBNAME entry is in effect. Any duplicate JOBNAME entries that specify an IPv6 address or interface or TEMPADDRS are ignored and messages are displayed.

Restriction: Unless a GLOBALCONFIG EXPLICITBINDPORTRANGE statement is configured on this stack, you cannot use an IPv4 SRCIP JOBNAME entry that specifies a distributed DVIPA to select as the source IP address for a connection on an IPv6 socket to an IPv4-mapped destination. If you do use such an entry, the connection fails.

srcv4_addr
IPv4 host address to be used as a source IP address if it matches the associated job name. The specified IP address does not need to be defined prior to processing the SRCIP block but it must be defined before the TCP connect or listen request is issued by the associated job; otherwise, the connect or listen request fails.

The ipv4_address value can be a static VIPA, a dynamic VIPA, or a real IPv6 address associated with a physical interface. If you specify a dynamic VIPA, it can be defined by a VIPADEFINE statement or a VIPARANGE statement. If the dynamic VIPA is defined by a VIPARANGE statement, then it must have been activated with a bind() or IOCTL SIOCSVIPA value.

srcv6_addr
IPv6 host address to be used as a source IP address if it matches the associated job name. The IPv6 IP address is in colon-hexadecimal format. You cannot specify a prefix length. See Restrictions on IPv6 addresses configured in the TCP/IP profile for a list of restrictions that apply to this parameter. If the stack is not IPv6-enabled and an IPv6 IP address is specified, the JOBNAME entry is ignored and a message is displayed. The specified IP address does not need to be defined prior to processing the SRCIP block, but it must be defined before the TCP connect or listen request is issued by the associated job; otherwise, the connect or listen request fails.

The ipv6_address value is a static VIPA, a dynamic VIPA, or a real IPv6 address that is associated with a physical interface. If you specify a dynamic VIPA, it can be defined by a VIPADEFINE statement or a VIPARANGE statement. If the dynamic VIPA is defined by a VIPARANGE statement, then it must have been activated with a bind() or IOCTL SIOCSVIPA value.

srcv6_intf_name
The name of an IPv6 static VIPA, dynamic VIPA interface, or a physical interface to be used as a source interface if it matches the associated job name. The maximum length is 16 characters. If a dynamic VIPA is specified, it can be defined by a VIPADEFINE statement or it could have been previously activated with bind() or IOCTL SIOCSVIPA6 value in a VIPARANGE statement. If the stack is not IPv6-enabled, the JOBNAME entry is ignored and a message is displayed. The specified interface does not need to be defined prior to processing the SRCIP block, but it must be defined before the TCP connect or listen request is issued by the associated job; otherwise, the connect or listen request fails. If the interface has multiple IP addresses, then the source IP address for the outbound connection is selected from among these addresses according to the default source address selection algorithm. For more information, see the default source address selection algorithm information in z/OS Communications Server: IPv6 Network and Application Design Guide.

Guideline: When you are using a SRCIP JOBNAME statement for an IPv6 server application, code an IPv6 address (srcv6_addr) instead of an IPv6 interface (srcv6_intf_name); otherwise, the source address that is chosen for that IP interface might not be the best choice for the server application to be bound to. For more information, see the default source address selection algorithm information in z/OS Communications Server: IPv6 Network and Application Design Guide.

CLIENT
Specifies that the source IP address should be used for client applications that are establishing outbound TCP connections that bind to the IPv4 INADDR_ANY address to IPv6 unspecified address (in6addr_any), or to the connect() call without having first completed a bind() call. The source IP address is determined on the subsequent connect() call. This value is the default.
SERVER
Specifies that the source IP address should be used to convert TCP server applications that bind to the IPv4 INADDR_ANY address or to the IPv6 unspecified address (in6addr_any), to bind to the specific source IP address. This means that only client applications that are using the designated IP address can connect to the server application. The source IP address is determined on the subsequent listen() call. When an application issues a getsockname() call after a bind() call to retrieve the source IP address, the processing is different from the processing that occurs when a TCP server application is converted to being bind specific using the BIND keyword on the PORT statements in the TCP/IP profile. When using the BIND keyword on the PORT statement, the designated IP address is set when the bind() call completes; some applications, such as DB2®, depend on this behavior.
BOTH
Specifies that the source IP address should be used for both client and server applications. For client applications, the source IP address is used for applications that invoke the bind() call with the IP INADDR_ANY address, the IPv6 unspecified address (in6addr_any), or the connect() call (for TCP outbound connections) without having first completed a bind() call. For server applications, the source IP address is used for applications that invoke the bind() call with the IP INADDR_ANY address or the IPv6 unspecified address (in6addr_any). The source IP address is determined on the connect() call for client applications and the listen() call for server applications.

Restriction: The options SERVER and BOTH are not valid with JOBNAME * specifications.

Designate that a temporary IPv6 address is preferred over a public IPv6 address
jobname
Specifies the MVS job name of the application for which temporary IPv6 addresses should be preferred over public IPv6 addresses. The jobname value can be up to 8 characters in length. A trailing asterisk (*) is a wildcard specification.

If duplicate job names are specified in the same SRCIP block and some of the duplicate entries specify an IPv6 address or interface and the other entries specify the value TEMPADDRS or PUBLICADDRS, the first JOBNAME entry is in effect. Any subsequent duplicate JOBNAME entries are ignored and messages are displayed.

TEMPADDRS
Specifies that this JOBNAME entry causes temporary IPv6 addresses to be preferred over public IPv6 addresses for the specified job when default source IP address selection is performed for the outbound packets.
Designate that a public IPv6 address is preferred over a temporary IPv6 address
jobname
Specifies the MVS job name of the application for which public IPv6 addresses should be preferred over temporary IPv6 addresses. The jobname value can be up to 8 characters in length. A trailing asterisk (*) is a wildcard specification.

If duplicate job names are specified in the same SRCIP block and some of the duplicate entries specify an IPv6 address or interface and the other entries specify the value TEMPADDRS or PUBLICADDRS, the first JOBNAME entry is in effect. Any subsequent duplicate JOBNAME entries are ignored and messages are displayed.

PUBLICADDRS
Specifies that this JOBNAME entry causes public IPv6 addresses to be preferred over temporary IPv6 addresses for the specified job when default source IP address selection is performed for the outbound packets. The application prefers public addresses by default.
Guideline: The environment in which the application is run determines the job name to be associated with a particular client or server application as follows:
  • Applications submitted as batch jobs use the batch job name.
  • The job name associated with applications started from the MVS operator console using the START command is determined as follows:
    • If the START command is issued with the name of a member in a cataloged procedure library (for example, S APP1), the job name is the member name (for example, APP1).
    • If the member name on the START command is qualified by a started task identifier (for example, S APP1.ABC), the job name is the started task identifier (for example, ABC). The started task identifier is not visible to all MVS components, but TCP/IP uses it to match a job name specified in the SRCIP block.
  • The JOBNAME parameter can also be used on the START command to identify the job name (for example, S APP1,JOBNAME=XYZ).
  • The JOBNAME parameter can also be included on the JOB card.
  • Applications run from a TSO user ID use the TSO user ID as the job name.
  • Applications run from the z/OS® shell typically have a job name that is the user ID of the user that is logged on plus a 1-character suffix. Because this job name might not be predictable, you can use a job name ending in an asterisk (*) to ensure that these applications are governed by the SRCIP block. Because different applications might have the same job name, use care when you designate job names for applications running from the z/OS shell.
  • Authorized users can run applications from the z/OS shell and use the _BPX_JOBNAME environment variable to set the job name. In this case, the value specified for the environment variable is the job name.
  • z/OS UNIX applications started by INETD typically use the job name of the INETD server plus a 1-character suffix.

Steps for modifying

To modify parameters for the SRCIP block, consider the following:
  • When a new SRCIP block is specified in a configuration data set on a VARY TCPIP,,OBEYFILE command, the new designations completely replace the existing designations.
  • If you want to remove all the current designations, specify the SRCIP block without any entries, as indicated in the following example: 
    SRCIP ENDSRCIP
  • If you want to change one of the designations, first create a SRCIP block with the existing set of designations. Update any JOBNAME or DESTINATION entry with the designation that needs to be changed. Then issue the VARY TCPIP,,OBEYFILE command to activate the change.
  • Changing the source IP address in a JOBNAME or DESTINATION entry affects only new TCP connect requests for the job or destination address. It does not affect processing for any existing connections.
  • Changing the TEMPADDRS or PUBLICADDRS setting in a JOBNAME entry affects only new TCP connect requests; it does not affect processing for existing connections.
Guidelines:
  • While the SRCIP-ENDSRCIP statement allows the specification of real IP addresses that are associated with physical interfaces, use static or dynamic VIPA interfaces. Because static and dynamic VIPA interfaces are not associated with a specific physical interface, they provide higher availability attributes in cases where specific network interfaces fail or where connectivity is lost in specific parts of the network. In cases where a real IP address must be specified as a source IP address on the SRCIP-ENDSRCIP block statement, there are several considerations that should be carefully evaluated:
    • The IP address specified affects only the source IP address that is used for all packets associated with an outbound TCP connection for the specified jobs or destinations; it does not influence the physical network interface selected by TCP/IP for any outbound packets associated with the TCP connection. TCP/IP determines the outbound interface by consulting its routing table and determining the best route to the destination IP address for the connection. As a result, the source IP address that is selected might not be associated with the outbound physical interface selected by TCP/IP. The network routing topology must allow for any inbound packets for this connection to be routed back to this TCP/IP host regardless of the network interface that was used for any outbound traffic associated with this connection.
    • If the physical network interface associated with a specified IP address fails or is deactivated, any incoming packets destined to this IP address might not be able to reach this TCP/IP host. This could disrupt traffic for both existing TCP connections and new TCP connections that use this source IP address.
  • For JOBNAME entries, if the same VIPA source IP address is used on more than one z/OS TCP/IP stack, then the job-specific source IP address should be a distributed DVIPA with the SYSPLEXPORTS parameter enabled.
Tips: Give careful consideration if:
  • The designated source is a dynamic VIPA.
    A dynamic VIPA that becomes inactive is no longer a valid designated source for SRCIP. A dynamic VIPA might become inactive if one of the following is true:
    • It is no longer a target for sysplex distribution on this stack
    • The application that causes its creation (in the case of an address created by a VIPARANGE statement) causes its deletion
    • It has been deactivated by the VARY TCPIP,,SYSPLEX,DEACTIVATE command
    • The DVIPA is in QUIESCING status
    • The TCP/IP stack leaves the sysplex group
  • The designated source is an interface name.

    When an interface name is specified, it might be associated with multiple addresses. In this case, the address is chosen at connect time:

    • If an interface has multiple addresses defined, the address chosen as the source IP address for the outbound connection is selected according to the default source address selection algorithm. For more information, see the default source address selection algorithm information in z/OS Communications Server: IPv6 Network and Application Design Guide.
    • If the interface is a dynamic VIPA interface that is created by a VIPARANGE statement, then the actual address chosen as the source IP address for the outbound connection is not predictable or necessarily meaningful. Thus, you should specify an IPv6 address instead of an interface name if a VIPARANGE statement address is to be used.

Related topics

Parent topic: TCP/IP profile (PROFILE.TCPIP) and configuration statements