VxWorks Reference Manual : Libraries
ripLib - Routing Information Protocol (RIP) v1 and v2 library
ripLibInit( ) - initialize the RIP routing library
ripRouteShow( ) - display the internal routing table maintained by RIP
ripAuthHookAdd( ) - add an authentication hook to a RIP interface
ripAuthHookDelete( ) - remove an authentication hook from a RIP interface
ripAuthHook( ) - sample authentication hook
ripLeakHookAdd( ) - add a hook to bypass the RIP and kernel routing tables
ripLeakHookDelete( ) - remove a table bypass hook from a RIP interface
ripSendHookAdd( ) - add an update filter to a RIP interface
ripSendHookDelete( ) - remove an update filter from a RIP interface
ripIfSearch( ) - add new interfaces to the internal list
ripIfReset( ) - alter the RIP configuration after an interface changes
ripFilterEnable( ) - activate strict border gateway filtering
ripFilterDisable( ) - prevent strict border gateway filtering
ripShutdown( ) - terminate all RIP processing
ripDebugLevelSet( ) - specify amount of debugging output
This library implements versions 1 and 2 of the Routing Information Protocol (RIP). The protocol is intended to operate as an interior gateway protocol within a relatively small network with a longest path of 15 hops.
The ripLibInit( ) routine links this library into the VxWorks image and begins a RIP session. This happens automatically if INCLUDE_RIP is defined at the time the image is built. Once started, RIP will maintain the network routing table until deactivated by a call to the ripShutdown( ) routine, which will remove all route entries and disable the RIP library routines. All RIP requests and responses are handled as defined in the RFC specifications. RFC 1058 defines the basic protocol operation and RFC 1723 details the extensions which implement version 2.
When acting as a supplier, outgoing route updates are filtered using simple split horizon. Split horizon with poisoned reverse is not currently available. Additional route entries may be excluded from the periodic update with the ripSendHookAdd( ) routine.
If a RIP session is terminated, the networking subsystem may not function correctly until RIP is restarted with a new call to ripLibInit( ) unless routing information is provided by some other method.
By default, a RIP session only uses the network interfaces created before it started. The ripIfSearch( ) routine allows RIP to recognize any interfaces added to the system after that point. If the address or netmask of an existing interface is changed during a RIP session, the ripIfReset( ) routine must be used to update the RIP configuration appropriately. The current RIP implementation also automatically performs the border gateway filtering required by the RFC specification. Those restrictions provide correct operation in a mixed environment of RIP-1 and RIP-2 routers. The ripFilterDisable( ) routine will remove those limitations, and may produce more efficient routing for some topologies. That routine must not be used if any version 1 routers are present. The ripFilterEnable( ) routine will restore the default behavior.
By default, authentication is disabled, but may be activated by an SNMP agent on an interface-specific basis. While authentication is disabled, any RIP-2 messages containing authentication entries are discarded. When enabled, all RIP-2 messages without authentication entries are automatically rejected. To fully support authentication, an authentication routine should be specified with the ripAuthHookAdd( ) routine. The specified function will be called to screen every RIP-1 message and all unverified RIP-2 messages containing authentication entries. It may be removed with the ripAuthHookDelete( ) routine. All RIP-1 and unverified RIP-2 messages will be discarded while authentication is enabled unless a hook is present.
The ripLeakHookAdd( ) routine allows the use of an alternative routing protocol which uses RIP as a transport mechanism. The specified function can prevent the RIP session from creating any table entries from the received messages. The ripLeakHookDelete( ) routine will restore the default operation.
As required by the RFC specification, the obsolete traceon and traceoff messages are not supported by this implementation. The ripRouteShow( ) routine will display the contents of the internal RIP routing table. Routines such as mRouteShow( ) to display the corresponding kernel routing table will also be available if INCLUDE_NET_SHOW is defined when the image is built. If additional information is required, the ripDebugLevelSet( ) routine will enable predefined debugging messages which will be sent to the standard output.
ripLib.h
ripLib, RFC 1058, RFC 1723
ripLibInit( ) - initialize the RIP routing library
STATUS ripLibInit ( BOOL supplier, /* operate in silent mode? */ BOOL gateway, /* act as gateway to the Internet? */ BOOL multicast, /* use multicast or broadcast addresses? */ int version, /* 1 or 2: selects format of outgoing messages */ int timerRate, /* update frequency for internal routing table */ int supplyInterval, /* update frequency for neighboring routers */ int expire, /* maximum interval for renewing learned routes */ int garbage /* elapsed time before deleting stale route */ )
This routine creates and initializes the global data structures used by the RIP routing library and starts a RIP session to maintain routing tables for a host. It must be called before using any other library routines, and is invoked automatically if INCLUDE_RIP is defined at the time the system is built.
The resulting RIP session will monitor all network interfaces which are currently available for messages from other RIP routers. If the supplier parameter is true, it will also respond to specific requests from other routers and transmit route updates over every known interface at the interval specified by supplyInterval.
Specifying a gateway setting of true establishes this router as a gateway to the wider Internet, capable of routing packets anywhere within the local networks. The final multicast flag indicates whether the RIP messages are sent to the pre-defined multicast address of 224.0.0.9 (which requires a version setting of 2) or to the broadcast address of the interfaces.
The version parameter determines the format used for outgoing RIP messages, and also sets the initial settings of the MIB-II compatibility switches in combination with the multicast flag. A version of 1 will restrict all incoming traffic to that older message type. A version of 2 will set the receive switch to accept either type unless multicast is true, which limits reception to version 2 messages only. SNMP agents may alter those settings on a per-interface basis once startup is complete.
The remaining parameters set various system timers used to maintain the routing table. All of the values are expressed in seconds, and must be greater than or equal to 1. The timerRate determines how often the routing table is examined for changes and expired routes. The supplyInterval must be an exact multiple of that value. The expire parameter specifies the maximum time between updates before a route is invalidated and removed from the kernel table. Expired routes are then deleted from the internal RIP routing table if no update has been received within the time set by the garbage parameter.
The following configuration parameters determine the initial values for all these settings. The default timer values match the settings indicated in the RFC specification.
Parameter Name Default Value Configuration Parameter supplier 0 (FALSE) RIP_SUPPLIER gateway 0 (FALSE) RIP_GATEWAY multicast 0 (FALSE) RIP_MULTICAST version 1 RIP_VERSION timerRate 1 RIP_TIMER_RATE supplyInterval 30 RIP_SUPPLY_INTERVAL expire 180 RIP_EXPIRE_TIME garbage 300 RIP_GARBAGE_TIME
OK, or ERROR if configuration fails.
N/A
ripRouteShow( ) - display the internal routing table maintained by RIP
void ripRouteShow()
This routine prints every entry in the local RIP routing table. The flags displayed below the destination, gateway, and netmask addresses indicate the current route status. Entries with the RTS_INTERFACE flag indicate routes to directly connected networks which are generated locally. If RTS_SUBNET is set for an entry, it is subject to border gateway filtering (if enabled). When RTS_INTERNAL is also present, the corresponding entry is an "artificial" route created to supply distant networks with legitimate destinations if border filtering excludes the actual entry. Those entries are not copied to the kernel routing table. The RTS_CHANGED flag marks entries added or modified in the last timer interval which will be included in a triggered update.
N/A
N/A
ripAuthHookAdd( ) - add an authentication hook to a RIP interface
STATUS ripAuthHookAdd ( char* pIpAddr, /* IP address in dotted decimal notation */ FUNCPTR pAuthHook /* routine to handle message authentication */ )
This routine installs a hook routine to validate incoming RIP messages for a registered interface given by pIpAddr. (Interfaces created or changed after a RIP session has started may be installed/updated with the ripIfSearch( ) and ripIfReset( ) routines). The hook is only called if an SNMP agent enables authentication for the corresponding interface. It uses the following prototype:
STATUS ripAuthHookRtn (char *pKey, RIP_PKT *pRip);The first argument contains the authentication key for the message stored in the rip2IfConfAuthKey MIB variable and the second argument uses the RIP_PKT structure (defined in rip/ripLib.h) to access the message body. The routine must return OK if the message is acceptable, or ERROR otherwise. All RIP-2 messages sent to that routine already contain an authentication entry, but have not been verified. (Any unauthenticated RIP-2 messages have already been discarded as required by the RFC specification). RIP-1 messages may be accepted or rejected. RIP-2 messages requesting simple password authentication which match the key are accepted automatically before the hook is called. The remaining RIP-2 messages either did not match that key or are using an unknown authentication type. If any messages are rejected, the MIB-II counters are updated appropriately outside of the hook routine.The current RIP implementation contains a sample authentication hook which may be added as follows:
if (ripAuthHookAdd ("90.0.0.1", ripAuthHook) == ERROR) logMsg ("Unable to add authorization hook.\n", 0, 0, 0, 0, 0, 0);The sample routine only supports simple password authentication against the key included in the MIB variable. Since all such messages have already been accepted, all RIP-2 messages received by the routine are discarded. All RIP-1 messages are also discarded, so the hook actually has no effect. The body of that routine is:
STATUS ripAuthHook ( char * pKey, /* rip2IfConfAuthKey entry from MIB-II family */ RIP_PKT * pRip /* received RIP message */ ) { if (pRip->rip_vers == 1) { /* @ The RFC specification recommends, but does not require, rejecting @ version 1 packets when authentication is enabled. */ return (ERROR); } /* @ The authentication type field in the RIP message corresponds to @ the first two bytes of the sa_data field overlayed on that @ message by the sockaddr structure contained within the RIP_PKT @ structure (see rip/ripLib.h). */ if ( (pRip->rip_nets[0].rip_dst.sa_data[0] != 0) || (pRip->rip_nets[0].rip_dst.sa_data[1] != M2_rip2IfConfAuthType_simplePassword)) { /* Unrecognized authentication type. */ return (ERROR); } /* @ Discard version 2 packets requesting simple password authentication @ which did not match the MIB variable. */ return (ERROR); }A comparison against a different key could be performed as follows:
bzero ( (char *)&key, AUTHKEYLEN); /* AUTHKEYLEN from rip/m2RipLib.h */ /* @ The start of the authorization key corresponds to the third byte @ of the sa_data field in the sockaddr structure overlayed on the @ body of the RIP message by the RIP_PKT structure. It continues @ for the final 14 bytes of that structure and the first two bytes @ of the following rip_metric field. */ bcopy ( (char *)(pRip->rip_nets[0].rip_dst.sa_data + 2), (char *)&key, AUTHKEYLEN); if (bcmp ( (char *)key, privateKey, AUTHKEYLEN) != 0) { /* Key does not match: reject message. */ return (ERROR); } return (OK);The ripAuthHookDelete( ) routine will remove the installed function. If authentication is still enabled for the interface, all incoming messages which do not use simple password authentication will be rejected until a routine is provided.
OK if hook added, or ERROR otherwise.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
ripAuthHookDelete( ) - remove an authentication hook from a RIP interface
STATUS ripAuthHookDelete ( char* pIpAddr /* IP address in dotted decimal notation */ )
This routine removes an assigned authentication hook from a registered interface indicated by pIpAddr. (Interfaces created or changed after a RIP session has started may be installed/updated with the ripIfSearch( ) and ripIfReset( ) routines). If authentication is still enabled for the interface, RIP-2 messages using simple password authentication will be accepted if they match the key in the MIB variable, but all other incoming messages will be rejected until a routine is provided.
OK, or ERROR if the interface could not be found.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
ripAuthHook( ) - sample authentication hook
STATUS ripAuthHook ( char * pKey, /* rip2IfConfAuthKey entry from MIB-II family */ RIP_PKT * pRip /* received RIP message */ )
This hook demonstrates one possible authentication mechanism. It rejects all RIP-2 messages which used simple password authentication since they did not match the key contained in the MIB variable. All other RIP-2 messages are also rejected since no other authentication type is supported and all RIP-1 messages are also rejected, as recommended by the RFC specification. This behavior is the same as if no hook were installed.
OK if message is acceptable, or ERROR otherwise.
N/A
ripLeakHookAdd( ) - add a hook to bypass the RIP and kernel routing tables
STATUS ripLeakHookAdd ( char * pIpAddr, /* IP address in dotted decimal notation */ FUNCPTR pLeakHook /* function pointer to hook */ )
This routine installs a hook routine to support alternative routing protocols for the registered interface given by pIpAddr. (Interfaces created or changed after a RIP session has started may be installed/updated with the ripIfSearch( ) and ripIfReset( ) routines).
The hook uses the following interface:
STATUS ripLeakHookRtn (long dest, long gateway, long netmask)The RIP session will not add the given route to any tables if the hook routine returns OK, but will create a route entry otherwise.The ripLeakHookDelete( ) will allow the RIP session to add new routes unconditionally.
OK, or ERROR if the interface could not be found.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
ripLeakHookDelete( ) - remove a table bypass hook from a RIP interface
STATUS ripLeakHookDelete ( char* pIpAddr /* IP address in dotted decimal notation */ )
This routine removes the assigned bypass hook from a registered interface indicated by pIpAddr. (Interfaces created or changed after a RIP session has started may be installed/updated with the ripIfSearch( ) and ripIfReset( ) routines). The RIP session will return to the default behavior and add entries to the internal RIP table and kernel routing table unconditionally.
OK, or ERROR if the interface could not be found.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
ripSendHookAdd( ) - add an update filter to a RIP interface
STATUS ripSendHookAdd ( char* pIpAddr, /* IP address in dotted */ /* notation */ BOOL (* ripSendHook) (struct rt_entry* pRt) /* Routine to use. */ )
This routine installs a hook routine to screen individual route entries for inclusion in a periodic update. The routine is installed for the registered interface given by pIpAddr. (Interfaces created or changed after a RIP session has started may be installed/updated with the ripIfSearch( ) and ripIfReset( ) routines).
The hook uses the following prototype:
BOOL ripSendHookRtn (struct rt_entry* pRt);If the hook returns FALSE, the route is not included in the update. Otherwise, it is included if it meets the other restrictions, such as simple split horizon and border gateway filtering. The ripSendHookDelete( ) routine removes this additional filter from the output processing.
OK, or ERROR if the interface could not be found.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
ripSendHookDelete( ) - remove an update filter from a RIP interface
STATUS ripSendHookDelete ( char* pIpAddr /* IP address in dotted decimal notation */ )
This routine removes the hook routine that allowed additional screening of route entries in periodic updates from the registered interface indicated by pIpAddr. (Interfaces created or changed after a RIP session has started may be installed/updated with the ripIfSearch( ) and ripIfReset( ) routines). The RIP session will return to the default behavior and include any entries which meet the other restrictions (such as simple split horizon).
OK, or ERROR if the interface could not be found.
S_m2Lib_INVALID_PARAMETER
S_m2Lib_ENTRY_NOT_FOUND
ripIfSearch( ) - add new interfaces to the internal list
void ripIfSearch (void)
By default, a RIP session will not recognize any interfaces initialized after it has started. This routine schedules a search for additional interfaces which will occur during the next update of the internal routing table. Once completed, the session will accept and send RIP messages over the new interfaces.
N/A
N/A
ripIfReset( ) - alter the RIP configuration after an interface changes
STATUS ripIfReset ( char * pIfName /* name of changed interface */ )
This routine updates the interface list and routing tables to reflect address and/or netmask changes for the device indicated by pIfName. To accommodate possible changes in the network number, all routes using the named interface are removed from the routing tables, but will be added in the next route update if appropriate. None of the removed routes are poisoned, so it may take some time for the routing tables of all the RIP participants to stabilize if the network number has changed.
OK, or ERROR if named interface not found or not added to list.
N/A
ripFilterEnable( ) - activate strict border gateway filtering
void ripFilterEnable (void)
This routine configures an active RIP session to enforce the restrictions necessary for RIP-1 and RIP-2 routers to operate correctly in the same network as described in section 3.2 of RFC 1058 and section 3.3 of RFC 1723. When enabled, routes to portions of a logical network (including host routes) will be limited to routers within that network. Updates sent outside that network will only include a single entry representing the entire network. That entry will subsume all subnets and host-specific routes. If supernets are used, the entry will advertise the largest class-based portion of the supernet reachable through the connected interface.
N/A
N/A
ripFilterDisable( ) - prevent strict border gateway filtering
void ripFilterDisable (void)
This routine configures an active RIP session to ignore the restrictions necessary for RIP-1 and RIP-2 routers to operate correctly in the same network. All border gateway filtering is ignored and all routes to subnets, supernets, and specific hosts will be sent over any available interface. This operation is only correct if no RIP-1 routers are present anywhere on the network. Results are unpredictable if that condition is not met, but high rates of packet loss and widespread routing failures are likely.
The border gateway filtering rules are in force by default.
N/A
N/A
ripShutdown( ) - terminate all RIP processing
STATUS ripShutdown (void)
This routine "poisons" all routes in the current table by transmitting updates with an infinite metric for each entry over all available interfaces. It then halts all RIP processing and removes the associated tasks and data structures. When completed successfully, the RIP services are unavailable until restarted with the ripLibInit( ) routine.
OK if shutdown completed, or ERROR otherwise.
N/A
ripDebugLevelSet( ) - specify amount of debugging output
void ripDebugLevelSet ( int level /* verbosity level (0 - 3) */ )
This routine influences the amount of debugging information sent to standard output during the RIP session. Higher values of the level parameter result in increasingly verbose output. A level of zero restores the default behavior by disabling all debugging output.
N/A
N/A