HOME statement

Use the HOME statement to provide the list of home IPv4 addresses and associated link names.

Restriction:

The HOME statement applies only to IPv4 interfaces that are defined with DEVICE and LINK statements. Specify the home IP address on the INTERFACE statement for the following interfaces:
- An IPv6 interface.
- An IPv4 interface that is defined by using the INTERFACE statement for QDIO Ethernet, HiperSockets™, or static VIPA.
See Summary of INTERFACE statements for more information.

Syntax

Rule: Specify the parameters in the order shown here.


         .------------------------------.   
         V                              |   
>>-HOME----+--------------------------+-+----------------------><
           '-internet_addr--link_name-'

Parameters

internet_addr: The IP address valid for this host. The IP address can be associated with a physical or VIPA link.
Requirement: The IP address must be specified in dotted decimal form.
link_name: The name of the link defined in a previous LINK statement (or the reserved name LOOPBACK) that is associated with the home address.

Steps for modifying

To modify the HOME statement, use a VARY TCPIP,,OBEYFILE command with a data set that defines a new HOME statement.

Rules:

If you use the HOME statement to change the IP addresses of any links, you should stop and restart the affected devices. Furthermore, if the OSPF dynamic routing protocol is being used over an affected interface, you should wait between stopping and restarting the device to enable the OSPF protocol to fully propagate the deletion of the old IP address. The duration of this wait should be at least three times the dead router interval configured for the interface.
The first HOME statement of each configuration data set that is set replaces the existing HOME list with the new list. Subsequent HOME statements in the same data set add entries to the list; however, dynamically defined HOME list entries created by XCF dynamics, by a VIPADEFINE statement, or by an application binding to an IP address in a currently valid VIPARANGE statement are not deleted by a new HOME statement. You can display dynamically created HOME list entries with the Netstat HOME/-h command. A dynamic XCF HOME list entry has the link name EZASAMEMVS or begins with EZAXCF. A dynamic VIPA HOME list entry has a link name that begins with VIPL, followed by the hexadecimal value of its IP address.
If the first HOME statement of a profile contains no entries, then all IP addresses that were specified in a HOME statement from a previous profile are removed from the HOME list.
If you change the IP address of a link that was used by previously specified default routes and you want to maintain those default routes, you must include your GATEWAY or BEGINROUTES statements in the VARY TCPIP,,OBEYFILE command data set that contains the new HOME list. If you do not include your GATEWAY or BEGINROUTES statements, the static routes using that link are deleted.
If you had previously specified the PRIMARYINTERFACE statement and want to preserve the primary interface that was previously specified, you must include your PRIMARYINTERFACE statement in the VARY TCPIP,,OBEYFILE command data set that contains the new HOME list. If you do not include the original PRIMARYINTERFACE statement, the primary interface is reset to the first entry in the new HOME list.

Usage notes

Only one home address can be associated with a link. If the same link is specified in more than one HOME list entry, only the home address in the last entry is associated with the link. The only exception to this is the LOOPBACK link.
The default LOOPBACK address of 127.0.0.1 is internally defined by the TCP/IP stack. If you try to define this LOOPBACK address, it is flagged as a duplicate entry. You can use a link_name value of LOOPBACK in the HOME list to define additional LOOPBACK addresses. No DEVICE or LINK statement is needed for LOOPBACK, and it cannot be started or stopped (LOOPBACK is always active).
IP addresses from 127.0.0.128 through 127.0.0.255 are reserved for IBM® use and cannot be coded on the HOME statement as the IP address of any link; this includes LOOPBACK addresses.
To improve server application performance, use a non-loopback home address instead of a loopback address. This can result in improved throughput for applications that reside on the same MVS™ system and communicate with one another on the same TCP/IP stack.

A HOME address used by an ATM LINK referencing an ATMLIS should be within the logical IP subnetwork defined by the LIS subnet_value and subnet_mask. If it is not within the subnetwork, the link cannot be used for sending or receiving any ATM SVC traffic.
If a default local address is not specified using the PRIMARYINTERFACE statement, the first address in the HOME list is used as the default local address. This default local address is the value obtained by the GETHOSTID() function.
If an outgoing packet has the limited broadcast address (255.255.255.255) as its destination address and the source address is not specified by the sender, the default local address (see previous bullet) is used as the source address as long as it is associated with a link (other than LOOPBACK) that supports broadcast. If the link associated with the default local address is LOOPBACK or it does not support broadcast, the first address in the HOME list that is associated with a link (other than LOOPBACK) that supports broadcast is used as the source address.
When an incorrect HOME entry is encountered, all entries following that entry on that HOME statement are ignored. Subsequent HOME statements are processed.
When defining static VIPA addresses, observe the following rules:
- Code a primary VIPA address first in the HOME list or on the PRIMARYINTERFACE statement to serve as the default local address for use by the GETHOSTID() function.
  A static VIPA address must be a unique host address in the network and not be a duplicate of any physical IP address in the network.
  If using the RIP routing protocol and host route broadcasting is not supported by adjacent routers (that is, adjacent routers are unable to learn host routes), the following restrictions for VIPA addresses must be applied in order to benefit from fault tolerance support:
  - If you use subnetting and VIPA addresses are in the same network as the physical IP addresses, the subnetwork portion of any VIPA addresses must not be the subnetwork portion of any physical IP addresses in the network. In this case, assign a new subnetwork for the VIPA address.
    If subnetting is not used on any physical interface, the network portion of any VIPA address must not be the network portion of any physical IP address in the network. In this case, assign a new network for the VIPA address, preferably a class C network address.
  If using the RIP routing protocol and host route broadcasting is supported by adjacent routers (that is, adjacent routers are able to learn host routes), the network or subnetwork portions of VIPA addresses can be the same across multiple z/OS® TCP/IP stacks in the network. See OMPROUTE for more information.
  
  While a VIPA address can be assigned to each TCP/IP stack in one z/OS image, you should define an internal point-to-point link (for example, CTC) between the stacks. This ensures that the VIPA address in one z/OS TCP/IP stack attached to a failing adapter/controller (for example, 3172) can be reached by way of another z/OS TCP/IP stack channel-attached to the same controller through another adapter or to another controller across the point-to-point link.
  
  For information about what routing protocols to use to achieve nondisruptive TCP-connection fault tolerance, see the VIPA information in z/OS Communications Server: IP Configuration Guide.
  
  If you are using a name server to resolve host names by way of UDP and any of the related resolver configuration files have only one name server address coded that specifies a VIPA address, the host the name server is running on must be configured to use the SOURCEVIPA option.
- In general, the static VIPA addresses can be coded in any order in the HOME list; however, if you specify the SOURCEVIPA option on the IPCONFIG statement, the order of the VIPA addresses is important in terms of how source IP addresses are used for outbound datagrams originating at the host. In this case, the following rules apply:
  - In the HOME list, the static VIPA address that precedes a physical IP address is used as the source IP address if not overridden by another method of source address selection. See the information about source IP address selection in z/OS Communications Server: IP Configuration Guidefor the hierarchy of ways that the source IP address of an outbound packet is determined.
  - If static VIPA addresses are coded after all of the physical IP addresses, no VIPA addresses are used as the source IP address.
- More than one VIPA address can be defined in one network or subnetwork.
- You can use the VIPA address as the primary or only destination for the name of a z/OS server on the domain name server. A workstation on the network would use the z/OS server name (translated into the VIPA address) to access applications on the z/OS server.
- If you use DEVICE and LINK statements to define an IPv4 interface and you want to designate a static VIPA as the source VIPA for that interface, use DEVICE and LINK statements to define the static VIPA.
- If you use the INTERFACE statement to define an IPv4 interface and you want to designate a static VIPA as the source VIPA for that interface, take the following steps:
  - Use the INTERFACE VIRTUAL statement to define the static VIPA that will be used as the source VIPA.
  - Specify the SOURCEVIPAINTERFACE parameter on the INTERFACE statement for the IPv4 interface.

Examples

This example shows a HOME statement that defines the IP addresses of each link in the host.

HOME
   151.4.1.2      TR2 
   192.1.1.1      VIPA1
   130.50.75.1    TR1
   193.5.2.1      ETH1
   192.2.1.1      VIPA2
   9.67.43.110    FDDI1
   193.7.2.1      SNA1

VIPA1 and VIPA2 are examples of static VIPA links associated with static VIPA addresses, the other values are examples of physical links associated with physical IP addresses. If you specify SOURCEVIPA on the IPCONFIG statement, VIPA1 serves as the VIPA address for TR1 and ETH1, and VIPA2 for links FDDI1 and SNA1. Because there is no VIPA definition preceding TR2 in the HOME list, it is not affected by SOURCEVIPA. The VIPA addresses are used in the outbound IP datagrams. For more information, see IPCONFIG statement.

The following example shows the definition of an additional LOOPBACK address:

HOME  9.67.113.105   CTCD00   ; CTC IP address for this system
      127.0.0.2      LOOPBACK ; additional LOOPBACK address

If using the SOURCEVIPA option for the outbound datagrams originating at a z/OS TCP/IP stack, see the following example for details:

HOME                                                
  172.2.1.1     VIPA1  ; <-- Source for ETH1 and TR1
  151.2.3.1     ETH1                                
  151.4.1.1     TR1                                 
  172.2.1.2     VIPA2  ; <-- Source for ETH2 and TR2
  151.2.3.2     ETH2                                
  151.4.1.2     TR2

Select a VIPA address in the HOME statement to provide as the local address. The address that closely precedes a physical IP address is used as the local address. For example:

Optionally, additional VIPA addresses can be defined to associate a group of interfaces and serve as local addresses. In this example, VIPA1 is associated with ETH1 and TR1, and VIPA2 is associated with ETH2 and TR2.

If an outbound datagram is not to contain a SOURCEVIPA address for a particular interface (that is, use a physical IP address), then use the following example:

HOME                                                          
  151.4.1.1     TR1    ; <-- No SOURCEVIPA for outbound on TR1
  172.2.1.1     VIPA   ; <-- Source for ETH1 and TR2          
  151.2.3.1     ETH1                                          
  151.4.1.2     TR2

If traffic over an interface should not use a source VIPA address, put the HOME entry for that interface before all VIPA addresses in the HOME list.