Content-type: text/html Man page of nr

nr

Section: Environments, Tables, and Troff Macros (7)
Index Return to Main Contents
 

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: 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. 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). 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. 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. 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. 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. Sets the time between reading interface counters during an operability test. The default value is 1 second. Sets the time between tests when the previous test succeeded. The default value is 3 seconds. 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. 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. 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. 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...]);
        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

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. A specified interface is already configured. 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 delim off


 

Index

NAME
DESCRIPTION
Parameters
RESTRICTIONS
EXAMPLE
ERRORS
RELATED INFORMATION

This document was created by man2html, using the manual pages.
Time: 02:40:26 GMT, October 02, 2010