--- old/./ifconfig.txt Fri Dec 19 04:18:53 2008 +++ new/./ifconfig.txt Fri Dec 19 04:18:53 2008 @@ -1,6 +1,3 @@ - - - System Administration Commands ifconfig(1M) @@ -17,7 +14,7 @@ [broadcast address] [deprecated | -deprecated] [preferred | -preferred] [destination dest_address] [ether [address]] [failover | -failover] [group - [name | ""]] [index if_index] [metric n] [modlist] + [name | ""]] [index if_index] [ipmp] [metric n] [modlist] [modinsert mod_name@pos] [modremove mod_name@pos] [mtu n] [netmask mask] [plumb] [unplumb] [private | -private] [nud | -nud] [set [address] [/netmask]] @@ -81,12 +78,8 @@ addif address Create the next unused logical interface on the speci- - fied physical interface. If the physical interface is - part of a multipathing group, the logical interface can - be added to a different physical interface in the same - group. + fied physical interface. - all-zones Make the interface available to every shared-IP zone on @@ -140,6 +133,7 @@ -arp Disable the use of the ARP on a physical interface. + ARP cannot be disabled on an IPMP IP interface. auth_algs authentication algorithm @@ -479,7 +473,7 @@ ether [ address ] If no address is given and the user is root or has suf- - ficient privileges to open the underlying device, then + ficient privileges to open the underlying datalink, then display the current Ethernet address information. Otherwise, if the user is root or has sufficient @@ -490,54 +484,52 @@ over InfiniBand) interfaces, the address will be 20 bytes of colon-separated hex numbers between 0 and FF. - Some, though not all, Ethernet interface cards have + Some, though not all, Ethernet interface cards have their own addresses. To use cards that do not have their - own addresses, refer to section 3.2.3(4) of the IEEE + own addresses, refer to section 3.2.3(4) of the IEEE 802.3 specification for a definition of the locally - administered address space. The use of multipathing - groups should be restricted to those cards with their - own addresses (see MULTIPATHING GROUPS). + administered address space. Note that all IP interfaces + in an IPMP group must have unique hardware addresses; + see *in.mpathd(1M)*. -failover - Mark the logical interface as a non-failover interface. - Addresses assigned to non-failover logical interfaces - will not failover when the interface fails. Status - display shows NOFAILOVER as part of flags. + Set *NOFAILOVER* on the logical interface. This makes + the associated address available for use by *in.mpathd* + to perform probe-based failure detection for the + associated physical IP interface. As a side effect, + *DEPRECATED* will also be set on the logical interface. + This operation is not permitted on an IPMP IP interface. failover - Mark the logical interface as a failover interface. An - address assigned to such an interface will failover when - the interface fails. Status display does not show - NOFAILOVER as part of flags. + Clear *NOFAILOVER* on the logical interface. This is + the default. These logical interfaces are subject to + migration when brought up (see IP MULTIPATHING GROUPS). - group [ name |""] + group [ name | "" ] - Insert the logical interface in the multipathing group - specified by name. To delete an interface from a group, + When applied to a physical interface, it places the + interface into the named group. If the group does not + exist, it will be created, along with one or more IPMP + IP interfaces (for IPv4, IPv6, or both). Any *UP* + addresses that are not also marked *NOFAILOVER* are + subject to migration to the IPMP IP interface (see IP + MULTIPATHING GROUPS). Specifying a group name of *""* + removes the physical IP interface from the group. + When applied to a physical IPMP IP interface, it renames + the IPMP group to have the new name. If the name + already exists, or a name of *""* is specified, it + fails. Renaming IPMP groups is discouraged. Instead, + the IPMP IP interface should be given a meaningful name + when it is created via the *ipmp* subcommand, which the + system will also use as the IPMP group name. -SunOS 5.11 Last change: 21 Jan 2007 8 - - - - - - -System Administration Commands ifconfig(1M) - - - - use a null string "". When invoked on the logical inter- - face with id zero, the status display shows the group - name. - - index n Change the interface index for the interface. The value @@ -547,6 +539,15 @@ interface on the system. + ipmp + + Create an IPMP IP interface with the specified name. An + interface must be separately created for use by IPv4 and + IPv6. The *address_family* parameter controls whether + the command applies to IPv4 or IPv6 (IPv4 if + unspecified). All IPMP IP interfaces have the *IPMP* + flag set. + metric n Set the routing metric of the interface to n; if no @@ -739,18 +740,21 @@ plumb - Open the device associated with the physical interface - name and set up the streams needed for IP to use the - device. When used with a logical interface name, this - command is used to create a specific named logical - interface. An interface must be separately plumbed for - use by IPv4 and IPv6. The address_family parameter con- - trols whether the ifconfig command applies to IPv4 or - IPv6. + For a physical IP interface, open the datalink + associated with the physical interface name and set up + the plumbing needed for IP to use the datalink. When + used with a logical interface name, this command is used + to create a specific named logical interface on an + existing physical IP interface. - Before an interface has been plumbed, the interface will - not show up in the output of the ifconfig -a command. + An interface must be separately plumbed for IPv4 and + IPv6 according to the *address_family* parameter (IPv4 + if unspecified). Before an interface has been plumbed, + it will not be shown by *ifconfig -a*. + Note that IPMP IP interfaces are not tied to a specific + datalink and are instead created with the *ipmp* + subcommand. private @@ -766,23 +770,23 @@ removeif address Remove the logical interface on the physical interface - specified that matches the address specified. When the - interface is part of a multipathing group, the logical - interface will be removed from the physical interface in - the group that holds the address. + specified that matches the address specified. - router Enable IP forwarding on the interface. When enabled, the - interface is marked ROUTER, and IP packets can be for- - warded to and from the interface. + interface is marked *ROUTER*, and IP packets can be for- + warded to and from the interface. Enabling *ROUTER* on + any IP interface in an IPMP group applies the flag to + all IP interfaces in that IPMP group. -router - Disable IP forwarding on the interface. IP packets are - not forwarded to and from the interface. + Disable IP forwarding on the interface. IP packets are + not forwarded to and from the interface. Disabling + *ROUTER* on any IP interface in an IPMP group disables + it on all IP interfaces in that IPMP group. @@ -805,24 +809,19 @@ standby - Marks the physical interface as a standby interface. If - the interface is marked STANDBY and is part of the mul- - tipathing group, the interface will not be selected to - send out packets unless some other interface in the - group has failed and the network access has been failed - over to this standby interface. + Mark the physical IP interface as a *STANDBY* interface. + If an interface is marked *STANDBY* and is part of an + IPMP group, the interface will not be used for data + traffic unless another interface in the IPMP group + becomes unusable. When a *STANDBY* interface is + functional but not being used for data traffic, it will + also be marked *INACTIVE*. This operation is not + permitted on an IPMP IP interface. - The status display shows "STANDBY, INACTIVE" indicating - that that the interface is a standby and is also inac- - tive. IFF_INACTIVE will be cleared when some other - interface belonging to the same multipathing group fails - over to this interface. Once a failback happens, the - status display will return to INACTIVE. - -standby - Turns off standby on this interface. + Clear *STANDBY* on this interface. This is the default. subnet @@ -894,20 +893,26 @@ unplumb - Close the device associated with this physical interface - name and any streams that ifconfig set up for IP to use - the device. When used with a logical interface name, the - logical interface is removed from the system. After this - command is executed, the device name will no longer - appear in the output of ifconfig -a. + For a physical or IPMP interface, remove all associated + logical IP interfaces and tear down any plumbing needed + for IP to use the interface. For an IPMP IP interface, + this command will fail if the group is not empty. For a + logical interface, the logical interface is removed. + An interface must be separately unplumbed for IPv4 and + IPv6 according to the *address_family* parameter (IPv4 + if unspecified). Upon success, the interface name will + no longer appear in the output of *ifconfig -a*. + up - Mark a logical interface "up". This happens automati- - cally when assigning the first address to a logical - interface. The up option enables an interface after an - ifconfig down, which reinitializes the hardware. + Mark a logical interface *UP*. As a result, the IP + module will accept packets destined to the associated + address (unless the address is zero), along with any + associated multicast and broadcast IP addresses. + Similarly, the IP module will allow packets to be sent + with the associated address as a source address. usesrc [ name | none ] @@ -973,17 +978,13 @@ (route subcommand), in that order. The use of the usesrc option is mutually exclusive of - the IP multipathing ifconfig options, group and standby. - That is, if an interface is already part of a IP mul- - tipathing group or specified as a standby interface, - then it cannot be specified with a usesrc option, and - vice-versa. For more details on IP multipathing, see - in.mpathd(1M) and the . + the IPMP *group* and *standby* subcommands. That is, if + an interface is already part of a IPMP group or + specified as a *STANDBY* interface, then it cannot be + specified with a usesrc option, and vice-versa. - - SunOS 5.11 Last change: 21 Jan 2007 15 @@ -1238,7 +1239,9 @@ This interface supports some form of Class of Service (CoS) marking. An example is the 802.1D user priority - marking supported on VLAN interfaces. + marking supported on VLAN interfaces. For IPMP IP + interfaces, this will only be set if all interfaces in + the group have CoS set. DEPRECATED @@ -1245,35 +1248,19 @@ This address is deprecated. This address will not be used as a source address for outbound packets unless - - - -SunOS 5.11 Last change: 21 Jan 2007 19 - - - - - - -System Administration Commands ifconfig(1M) - - - there are no other addresses on this interface or an - application has explicitly bound to this address. An - IPv6 deprecated address will eventually be deleted when - not used, whereas an IPv4 deprecated address is often - used with IP network multipathing IPv4 test addresses, - which are determined by the setting of the NOFAILOVER - flag. Further, the DEPRECATED flag is part of the stan- - dard mechanism for renumbering in IPv6. + application has explicitly bound to this address. An + IPv6 deprecated address is part of the standard + mechanism for renumbering in IPv6 and will eventually be + deleted when not used. For both IPv4 and IPv6, + *DEPRECATED* is also set on all *NOFAILOVER* addresses, + though this may change in a future release. + DHCPRUNNING - DHCP + The logical interface is managed by *dhcpagent(1M)*. - DHCP is used to manage this address. - DUPLICATE The logical interface has been disabled because the IP @@ -1292,10 +1279,14 @@ FAILED - The interface has failed. New addresses cannot be - created on this interface. If this interface is part of - an IP network multipathing group, a failover will occur - to another interface in the group, if possible + The *in.mpathd* daemon has determined that the interface + has failed. *FAILED* interfaces will not be used to + send or receive IP data traffic. If this is set on a + physical IP interface in an IPMP group, IP data traffic + will continue to flow over other usable IP interfaces in + the IPMP group. If this is set on an IPMP IP interface, + the entire group has failed and no data traffic can be + sent or received over any interfaces in that group. FIXEDMTU @@ -1309,40 +1300,25 @@ INACTIVE - Indicates that the interface is not currently being used - for regular traffic by the system. New addresses cannot + The physical interface is functioning but is not used to + send or receive data traffic according to administrative + policy. This flag is initially set by the *standby* + subcommand and is subsequently controlled by + *in.mpathd*. It also set when *FAILBACK=no* mode is + enabled (see *in.mpathd(1M)*) to indicate that the IP + interface has repaired but is not being used. + IPMP -SunOS 5.11 Last change: 21 Jan 2007 20 + Indicates that this is an IPMP IP interface. - - - - -System Administration Commands ifconfig(1M) - - - - be created on this interface. The flag is set automati- - cally on standby interfaces. It can also be set when the - system detects that a failed interface has been repaired - and FAILBACK=no is configured in /etc/default/mpathd. - The flag is cleared when the interface fails or when a - failover to that interface occurs. - - LOOPBACK Indicates that this is the loopback interface. - MIP - - Indicates that mobile IP controls this interface. - - MULTI_BCAST Indicates that the broadcast address is used for multi- @@ -1366,9 +1342,9 @@ NOFAILOVER - This address will not failover if the interface fails. - IP network multipathing test addresses must be marked - nofailover. + The address associated with this logical interface is + available to *in.mpathd* for probe-based failure + detection of the associated physical IP interface. NOLOCAL @@ -1419,11 +1395,9 @@ OFFLINE - Indicates that the interface has been offlined. New - addresses cannot be created on this interface. Inter- - faces in an IP network multipathing group are offlined - prior to removal and replacement using dynamic reconfi- - guration. + The interface is offline and thus cannot send or receive + IP data traffic. This is only set on IP interfaces in + an IPMP group. See *if_mpadm(1M)* and *cfgadm(1M)*. POINTOPOINT @@ -1473,20 +1447,19 @@ RUNNING - Indicates that the required resources for an interface + Indicates that the required resources for an i nterface are allocated. For some interfaces this also indicates - that the link is up. + that the link is up. For IPMP IP interfaces, *RUNNING* + is set as long as one IP interface in the group is + active. STANDBY - Indicates that this is a standby interface to be used on - failures. Only interfaces in an IP network multipathing - group should be designated as standby interfaces. If - this interface is part of a IP network multipathing - group, the interface will not be selected to send out - packets unless some other interface in the group fails - over to it. + Indicates that this physical interface will not be used + for data traffic unless another interface in the IPMP + group becomes unusable. The *INACTIVE* and *FAILED* + flags indicate whether it is actively being used. TEMPORARY @@ -1504,14 +1477,15 @@ UP - Indicates that the interface is up, that is, all the - routing entries and the like for this interface have - been set up. + Indicates that the logical interface (and the associated + physical interface) is up. The IP module will accept + packets destined to UP addresses (unless the address is + zero), along with any associated multicast and broadcast + IP addresses. Similarly, the IP module will allow + packets to be sent with an UP address as a source + address. - - - SunOS 5.11 Last change: 21 Jan 2007 23 @@ -1529,7 +1503,7 @@ hardware. It is not possible to transmit or receive packets through a virtual interface. These interfaces are useful for configuring local addresses that can be - used on multiple interfaces. (See also the -usesrc + used on multiple interfaces. (See also the *usesrc* option.) @@ -1600,31 +1574,84 @@ eri0 has been plumbed. - To delete a logical interface, use the -unplumb or -removeif - options. For example, + To delete a logical interface, use the *unplumb* or + *removeif* options. For example, example% ifconfig eri0:1 down unplumb + will delete the logical interface *eri0:1*. +IP MULTIPATHING GROUPS + Physical interfaces that share the same IP broadcast domain + _must_ be collected into a single IP Multipathing (IPMP) + group using the *group* subcommand. Each IPMP group has an + associated IPMP IP interface, which can either be explicitly + created (the preferred method) by using the *ipmp* + subcommand or implicitly created by *ifconfig* in response + to placing an IP interface into a new IPMP group. + Implicitly-created IPMP interfaces will be named ipmp_N_ + where _N_ is the lowest integer that doesn't conflict with + an existing IP interface name or IPMP group name. - will delete the logical interface eri0:1. + Each IPMP IP interface is created with a matching IPMP group + name, though it can be changed using the *group* subcommand. + Each IPMP IP interface hosts a set of highly-available IP + addresses. These addresses will remain reachable so long as + at least one interface in the group is active, where + "active" is defined as having at least one UP address and + having *INACTIVE*, *FAILED*, and *OFFLINE* clear. IP + addresses hosted on the IPMP IP interface may either be + configured statically or configured through DHCP via the + *dhcp* subcommand. -MULTIPATHING GROUPS - Physical interfaces that share the same IP broadcast domain - can be collected into a multipathing group using the group - keyword. Interfaces assigned to the same multipathing group - are treated as equivalent and outgoing traffic is spread - across the interfaces on a per-IP-destination basis. In - addition, individual interfaces in a multipathing group are - monitored for failures; the addresses associated with failed - interfaces are automatically transferred to other function- - ing interfaces within the group. + Interfaces assigned to the same IPMP group are treated as + equivalent and monitored for failure by *in.mpathd*. + Provided that active interfaces in the group remain, IP + interface failures (and any subsequent repairs) are handled + transparently to sockets-based applications. IPMP is also + integrated with the Dynamic Reconfiguration framework (see + *cfgadm(1M)*), which enables network adapters to be replaced + transparently to sockets-based applications. + + The IP module automatically load-spreads all outbound + traffic across all active interfaces in an IPMP group. + Similarly, all *UP* addresses hosted on the IPMP IP + interface and will be distributed across the active + interfaces to promote inbound load-spreading. The + *ipmpstat(1M)* utility allows many aspects of the IPMP + subsystem to be observed, including the current binding of + IP data addresses to IP interfaces. + When an interface is placed into an IPMP group, any *UP* + logical interfaces are "migrated" to the IPMP IP interface + for use by the group, unless: - For more details on IP multipathing, see in.mpathd(1M) and - the . See netstat(1M) for per-IP-destination information. + * The logical interface is marked *NOFAILOVER* + * The logical interface hosts an IPv6 link-local address. + * The logical interface hosts an IPv4 0.0.0.0 address. + Likewise, once an interface is in a group, if changes are + made to a logical interface such that it is *UP* and not + exempted by one of the conditions above, it will also + migrate to the associated IPMP IP interface. Logical + interfaces never migrate back, even if the physical + interface that contributed the address is removed from the + group. + + Each interface placed into an IPMP group may be optionally + configured with a "test" address that *in.mpathd* will use + for probe-based failure detection; see *in.mpathd(1M)*. + These addresses must be marked *NOFAILOVER* (using the + *-failover* subcommand) prior to being marked *UP*. Test + addresses may also be acquired through DHCP via the *dhcp* + subcommand. + + For more background on IPMP, please see the "IPMP + Administrative Overview" and "IPMP Configuration Tasks" + chapters of the administrator documentation. + + CONFIGURING IPV6 INTERFACES When an IPv6 physical interface is plumbed and configured "up" with ifconfig, it is automatically assigned an IPv6 @@ -2097,7 +2124,7 @@ The following command, using the none keyword, undoes the - effect of the preceding ifconfig usersrc command. + effect of the preceding *ifconfig* *usesrc* command. example% ifconfig qfe2 usesrc none @@ -2329,7 +2356,7 @@ SEE ALSO dhcpinfo(1), dhcpagent(1M), in.mpathd(1M), in.ndpd(1M), - in.routed(1M), ipsecconf(1M), ndd(1M), netstat(1M), + in.routed(1M), ipmpstat(1M), ipsecconf(1M), netstat(1M), zoneadm(1M), zonecfg(1M), ethers(3SOCKET), gethostbyname(3NSL), getnetbyname(3SOCKET), hosts(4), inet_type(4), ndpd.conf(4), netmasks(4), networks(4),