 |
Index for Section 7 |
|
 |
Alphabetical listing for N |
|
nr(7)
NAME
nr - Redundant Array of Independent Network Adapters (NetRAIN)
DESCRIPTION
The NetRAIN virtual interface configures multiple interfaces on the same
LAN segment into a single interface. One of the real interfaces is always
active while the others remain idle. If the active interface fails, an
idle interface comes online. The failover time is adjustable depending on
your network configuration and operation.
You can configure the NetRAIN interface with the ifconfig command or with
the ioctl system call. See ifconfig(8) for more information. You can
adjust some parameters with the sysconfig command. The SIOCIFADD ioctl
parameter creates the NetRAIN virtual interface and adds the real
interfaces to this NetRAIN set. After creating the NetRAIN virtual
interface, one or more real interfaces are attached to it. Individual
interfaces cannot be added or removed from the set once they have been
created. However, the NetRAIN set can be disassembled using the ifconfig
command by specifying all the interface names in the set on the command
line. The NetRAIN virtual interface itself must first be brought down
using the ifconfig command.
Parameters
The following list of ioctl parameters is used to configure the nr
interface:
SIOCIFADD Creates the NetRAIN virtual interface if it has not already been
created. This parameter requires an if_nrset structure for the
arg parameter (found in the <net/if.h> file). The if_nrset
structure contains the name of the nr interface (nr0, nr1,
completion of this command, the NetRAIN set is configured and the
monitoring thread is activated. The list of NetRAIN interfaces
is kept in a static table. The default size is specified by the
nr_maxdev kernel attribute. The interfaces themselves are
numbered from 0 to nr_maxdev-1 (for example, nr0, nr1,...). To
change the size of this table, change the nr_maxdev attribute for
the netrain kernel subsystem by using the sysconfig command. You
must reboot the system for the new value to take effect.
SIOCIFREMOVE
Disassembles the NetRAIN set, clears the UP flag on all members,
resets the hardware address to the default value, and clears the
hardware address for the nr interface. The nr interface may be
reused in a future SIOCIFADD command. This command requires an
ifreq structure with the ifr_name being the nr interface name
(the ifreq structure is found in the <net/if.h> file).
SIOCIFSWITCH
Forces a manual switch to another interface in the NetRAIN set.
This command requires an ifreq structure passed in the arg field
(<net/if.h>). The ifr_name field can be the nr interface name or
the name of any member in the set. If the name is the nr
interface or the active member, the next member in the set is
brought online. If any other member is specified in the ifr_name
field, that interface is brought online.
SIOCGNRSET
Retrieves the members of a NetRAIN set. This command requires an
if_nrset structure to be passed in the arg field (<net/if.h>).
The nr_name field may be the nr interface name or the name of any
member of the set. Upon return, the nr_name field contains the
nr interface name and the nr_buf field is a list of member names.
This buffer must be large enough to hold all the members or an
ENOBUFS error is returned.
SIOCAUTOFAIL
Forces the active interface to switch to the next available
interface at regular intervals. It requires an ifreq structure
in the arg field. The ifr_name field must contain the nr
interface name and the ifr_value field contains an integer number
of seconds between each switch operation. A value of zero
disables this feature.
The following ioctl parameters are used to control the interface monitoring
frequency. All of these parameters require an ifreq structure (found in
the <net/if.h> file). The ifr_name field contains the NetRAIN interface
name; the ifr_value field contains the timer value.
SIOCIFTMOISR
Sets the number of clock ticks between runs of the kernel
monitoring thread. All other timers are based on this frequency.
The other timers are loaded into a timer countdown field. This
field is decremented each time the kernel thread runs. When the
interface countdown field reaches zero, the next phase of testing
for that interface begins. The default value is 1000 ticks (1
second). Note: This timer may also be modified with the
sysconfig(8) command. The NetRAIN subsystem attribute
netrain_timeout controls the kernel monitoring thread timeout.
SIOCIFTMO Sets the time between reading interface counters during an
operability test. The default value is 1 second.
SIOCIFTMOSUCCESS
Sets the time between tests when the previous test succeeded.
The default value is 3 seconds.
SIOCIFTMORETRY
Sets the time between tests when the previous test failed. The
default value is 1. For ATM LAN Emulation (LANE) interfaces, set
this value to 2 seconds.
SIOCIFTMOFAIL
Sets the timeout value for monitoring the interface after it has
been determined to be broken. All interfaces associated with
this set will have their value changed. The default value is 5
seconds.
SIOCIFTMODOWN
Sets the time between tests when the interface UP flag is
cleared. No tests are performed if the UP flag is clear. When
the UP flag is detected, normal testing resumes. The default
value is 10 seconds.
SIOCIFMAXRETRY
Sets the number of failed tests to allow before the interface is
assumed to have failed and a backup interface is brought online.
This count may also be set with the sysconfig command. The
netrain subsystem attribute nr_max_retries controls the number of
retry attempts for all NetRAIN interfaces. The default value is
4. For ATM LAN Emulation (LANE) interfaces, set this value to 5.
The NetRAIN virtual interface supports all other ioctl parameters. The
NetRAIN driver propagates these commands to the real device driver where
appropriate. See the reference page for each individual driver for more
details.
RESTRICTIONS
The following conditions must be met at the time the NetRAIN interface is
created. If these conditions are not met, an error message will occur.
· All interfaces included in the NetRAIN set must be specified in a
single nr SIOCIFADD parameter. No additional interfaces can be added
once the set has been configured.
· All of the interfaces must be on the same LAN segment.
· All of the interfaces must have the same device type (either all
Ethernet, Fiber Distributed Data Interface (FDDI), or ATM LAN
Emulation (elan).
· Interfaces cannot have previously configured protocol addresses.
· The UP flag must be cleared.
After a NetRAIN virtual interface is created and real interfaces are added
to it, all configuration commands must be directed to the NetRAIN virtual
interface. Configuration of the member interfaces is prohibited and
results in a "Function not implemented" error.
A kernel thread runs periodically to test each interface in the NetRAIN
set. The test reads the interface counters to determine if packets are
being successfully transmitted and received. If the interface is active,
the counters are typically incremented due to existing traffic. If the
interface is idle, test packets are sent to cause the counters to change.
There are five timers that allow network administrators to tune the
monitoring process. The default timers detect a failed interface and bring
a backup interface online in under 10 seconds. You can adjust the timers
to increase or decrease this failover time. Reducing this time may
increase network traffic for testing interfaces and increase the processing
required to monitor the interfaces. Reducing the default timers may cause
false failure detection on congested networks.
See the Network Administration for additional information on NetRAIN
restrictions.
EXAMPLE
The following example creates a NetRAIN set from the specified interfaces.
The first argument is the NetRAIN virtual interface name, nrx. The second
argument is a comma-separated list of real interfaces that are added to the
NetRAIN set.
#include <stdio.h>
#include <errno.h>
#include <sys/socket.h>
#include <sys/ioctl.h>
#include <net/if.h>
#define IFNAMSZ 16
int main(int argc, char *argv[])
{
struct if_nrset ifnrset;
char *addr;
nrset_t *buf;
int sock,i;
if (argc <= 2) {
printf("Usage: add <nrdev> <dev1>[,dev2...]0);
return(0);
}
/* Load the NetRAIN interface name */
if (--argc > 0) {
argv++;
strcpy(ifnrset.nr_name,*argv);
}
/* Count the members to be included in the NetRAIN set */
if (--argc > 0) {
++argv;
addr = *argv;
ifnrset.nr_cnt = 1;
for (i = 0; addr[i] != ' '; i++) {
if (addr[i] == ',') {
addr[i] = ' ';
ifnrset.nr_cnt++;
}
}
/* Allocate a buffer large enough to hold the interface names */
buf = (nrset_t *)malloc(ifnrset.nr_cnt * IFNAMSZ);
if (buf == NULL) {
perror("malloc: ");
return(0);
}
/* Load the interface array */
for (i=0; i<ifnrset.nr_cnt; i++) {
strcpy(buf[i].name,addr);
addr += strlen(addr)+1;
}
ifnrset.nr_len = ifnrset.nr_cnt * IFNAMSIZ;
ifnrset.nr_buf = (nrset_t *)buf;
sock = socket(AF_INET, SOCK_DGRAM, 0);
if (sock < 0) {
free(buf);
perror("socket: ");
return(0);
}
if (ioctl(sock, SIOCIFADD, (char *)&ifnrset) != 0) {
close(sock);
free(buf);
perror("SIOCIFADD: ");
return(0);
}
free(buf);
close(sock);
}
return(0);
}
ERRORS
ENXIO The NetRAIN interface name was invalid or the unit number was out
of range (0-9). The interface list contained an invalid
interface type. All interfaces must be either FDDI or Ethernet.
An interface that was previously specified already belongs to a
NetRAIN set.
EBUSY A specified interface is already configured.
ENOBUFS NetRAIN could not allocate system memory for the request.
RELATED INFORMATION
Functions: ioctl(2).
Interfaces: faa(7), fta(7), fza(7), le(7), ln(7), tu(7).
Commands: ifconfig(8), sysconfig(8).
Tuning: sys_attrs_netrain(5).
Network Administration
System Configuration and Tuning