route(7P) route(7P)
NAME
route - kernel packet forwarding database
SYNOPSIS
DESCRIPTION
This manpage describes routing socket interface to read and write kernel routing messages.
The information on how to transmit network packets is maintained by the HP-UX kernel in the routing information database, also known as the
routing table. A user process can read or update information in the routing table by sending routing messages to the kernel via an
AF_ROUTE socket. The message types are described in more detail in the section below.
The family parameter in the system call shown in the may be used to filter the routing messages the caller receives. The valid values for
family are:
AF_INET get routing messages affecting the Internet Protocol.
AF_INET6 get routing messages affecting the Internet Protocol version 6.
AF_UNSPEC get routing messages affecting both AF_INET and AF_INET6 protocols.
Entries in the routing table specify the appropriate remote host or gateway to use when transmitting packets. These entries are either
host-specific, or are applicable to all hosts located on a generic subnetwork, as specified by a netmask value.
After the system boots, each protocol family adds entries to the routing table for each network interface configured and ready to transmit
network traffic. Normally, the route entry is specified as a to the destination host or network. For direct routes, the transport layer
of the network stack sends packets directly to the host specified in the packet header. For non-direct routes, the interface forwards the
packet to the gateway listed in the routing entry for that interface.
When routing packets, the kernel attempts to find an optimal route for each destination. If more than one entry matches the netmask of the
destination, the kernel selects the route with the greater number of 1's in the netmask.
A default (wildcard) route is used if no other route to a particular remote host or network can be located. A default route is specified
with an all 0 destination address value and a netmask of all 0's. Default routes, in combination with routing redirects, provide an eco-
nomical mechanism for routing network traffic.
If no routing entry is found, the destination is declared as unreachable, and a routing-miss message (RTM_MISS) is generated to any user
processes using the routing socket facilities, as described below.
Message Types
After creating a routing socket, the process can send commands to the kernel by writing to the socket. The process can read information
from the kernel by reading from the socket. The following message types can be used to communicate routing information between the user
process and the kernel:
RTM_ADD add route
RTM_CHANGE change gateway, metrics or flags
RTM_DELADDR address being removed from interface
RTM_DELETE delete route
RTM_GET report metrics and other information
RTM_IFINFO interface going up, down, etc.
RTM_LOSING kernel suspects route is failing
RTM_LOCK lock specified metrics
RTM_MISS lookup on this address failed
RTM_NEWADDR address being added to interface
RTM_REDIRECT kernel instructs to use different route
RTM_RESOLVE request to resolve destination to link-layer address
All 12 message types can be used to read information from the kernel. To write to the kernel, the process can issue RTM_ADD, RTM_DELETE,
or RTM_GET message types to update information in the routing table.
Message types RTM_CHANGE and RTM_LOCK are not supported on HP-UX. If a user process issues these messages, error will be returned.
Message Structure
Messages are formed by a message header followed by a small number of socket address structures.
What message header to use depends on the message type. The RTM_IFINFO messages use the header. The RTM_NEWADDR and RTM_DELADDR messages
use the header. All other message types use the header.
The structure contains the following members:
uint16_t rtm_msglen; /* to skip over unrecognized messages */
uint8_t rtm_version; /* future binary compatibility */
uint8_t rtm_type; /* message type */
uint16_t rtm_index; /* index for associated ifp */
int32_t rtm_flags; /* flags, incl. kern & message,
* e.g. DONE */
int32_t rtm_addrs; /* bitmask identifying sockaddrs in
* the message */
pid_t rtm_pid; /* identify sender */
int32_t rtm_seq; /* for sender to identify action */
int32_t rtm_errno; /* error indicator */
int32_t rtm_use; /* from rtentry */
uint32_t rtm_inits; /* which metrics we are initializing */
struct rt_metrics rtm_rmx; /* metrics themselves */
The structure contains the following members:
uint16_t ifm_msglen; /* to skip over unrecognized messages */
uint8_t ifm_version; /* future binary compatibility */
uint8_t ifm_type; /* message type */
int32_t ifm_addrs; /* bitmask identifying sockaddrs in
* the message */
int32_t ifm_flags; /* value of if_flags */
uint16_t ifm_index; /* index for associated ifp */
struct if_data ifm_data; /* statistics and other data about
* interface */
The structure contains the following members:
uint16_t ifam_msglen; /* to skip over unrecognized messages */
uint8_t ifam_version; /* future binary compatibility */
uint8_t ifam_type; /* message type */
int32_t ifam_addrs; /* bitmask identifying sockaddrs in
* the message */
int32_t ifam_flags; /* value of ifa_flags */
uint16_t ifam_index; /* index for associated ifp */
int32_t ifam_metric; /* value of ifa_metric */
To determine retransmission behavior, reliable protocols use the structure included in the message header. The structure contains the fol-
lowing members:
uint32_t rmx_locks; /* Kernel must leave these values alone */
uint32_t rmx_mtu; /* MTU for this path */
uint32_t rmx_hopcount; /* max hops expected */
uint32_t rmx_expire; /* lifetime for route, e.g. redirect */
uint32_t rmx_recvpipe; /* inbound delay-bandwidth product */
uint32_t rmx_sendpipe; /* outbound delay-bandwidth product */
uint32_t rmx_ssthresh; /* outbound gateway buffer limit */
uint32_t rmx_rtt; /* estimated round trip time */
uint32_t rmx_rttvar; /* estimated rtt variance */
uint32_t rmx_pksent; /* packets sent using this route */
The structure included in the message header defines a queue for a network interface and contains the following members:
/* generic interface information */
uint8_t ifi_type; /* ethernet, tokenring, etc */
uint8_t ifi_physical; /* AUI, Thinnet, 10base-T, etc */
uint8_t ifi_addrlen; /* media address length */
uint8_t ifi_hdrlen; /* media header length */
uint8_t ifi_recvquota; /* polling quota for receive intrs */
uint8_t ifi_xmitquota; /* polling quota for xmit intrs */
uint32_t ifi_mtu; /* maximum transmission unit */
uint32_t ifi_metric; /* routing metric (external only) */
uint32_t ifi_baudrate; /* linespeed */
/* volatile statistics */
uint32_t ifi_ipackets; /* packets received on interface */
uint32_t ifi_ierrors; /* input errors on interface */
uint32_t ifi_opackets; /* packets sent on interface */
uint32_t ifi_oerrors; /* output errors on interface */
uint32_t ifi_collisions; /* collisions on csma interfaces */
uint32_t ifi_ibytes; /* total number of octets received */
uint32_t ifi_obytes; /* total number of octets sent */
uint32_t ifi_imcasts; /* packets received via multicast */
uint32_t ifi_omcasts; /* packets sent via multicast */
uint32_t ifi_iqdrops; /* dropped on input, this interface */
uint32_t ifi_noproto; /* destined for unsupported protocol */
uint32_t ifi_hwassist; /* HW offload capabilities */
uint32_t ifi_unused; /* XXX was ifi_xmittiming */
struct timeval ifi_lastchange; /* time of last administrative change */
(Note that the position of items in all previously mentioned data structures does not necessarily reflect the order of the members in the
structure.)
The members and of the message headers are bitmasks that specify what socket address structure(s) follow the message. When multiple sock-
addrs follow the message, they are interpreted based on their order in the message and the value stored in the bitmask. The sequence is
least significant to the most significant bit within the vector.
The following constants are defined to indicate which socket addresses are present in the routing message:
#define RTA_DST 0x01 /* destination sockaddr present */
#define RTA_GATEWAY 0x02 /* gateway sockaddr present */
#define RTA_NETMASK 0x04 /* netmask sockaddr present */
#define RTA_GENMASK 0x08 /* cloning mask sockaddr present */
#define RTA_IFP 0x10 /* interface name sockaddr present */
#define RTA_IFA 0x20 /* interface address sockaddr present */
#define RTA_AUTHOR 0x40 /* author of redirect sockaddr present */
#define RTA_BRD 0x80 /* for NEWADDR, broadcast or
* point-to-point destination
* address */
Any messages sent to the kernel are returned back to the process issuing the command, and message copies are sent to all interested listen-
ers. The sender may provide its process ID to be stored in the message header. An additional sequence field can be used to distinguish
between outstanding messages. However, message replies may be lost when kernel buffers are exhausted.
Any messages generated by the kernel would have process ID and sequence field set to zero.
The kernel may spontaneously emit routing messages in response to external events, such as receipt of a redirect command, or failure to
locate an appropriate route for a request. A process may ignore all messages from the routing socket by doing a system call for further
input.
Security Restrictions
Only users with appropriate privileges can make changes to the routing table.
Notes
Some fields in the message header structures are not used on HP-UX. This means when the kernel generates routing messages it sets these
fields to 0. Also, when the kernel receives routing messages, it ignores any values contained in these fields. This applies to the fol-
lowing fields:
rtm_use, rtm_inits,
rtm_rmx, except for rtm_rmx.rmx_mtu and rtm_rmx.rmx_rtt
ifm_data, except for ifm_data.ifi_mtu,
ifm_data.ifi_metric, ifm_data.ifi_ipackets, and ifm_data.ifi_opackets
ifam_metric
ERRORS
If the kernel rejects a routing message, the field in the structure may be set to one of the following values:
The specified entry already exist.
Requested to duplicate an existing entry.
Network is unreachable.
The specified entry does not exist.
Requested to delete non-existent entry.
No buffer space is available.
Insufficient resources were available to install a new route.
Operation not supported.
Message types RTM_CHANGE and RTM_LOCK are not supported on HP-UX.
Permission to issue a command is denied.
The user needs appropriate privileges to make changes to the routing table.
EXAMPLES
The following sample program illustrates how a user process can add a route to the kernel's routing table.
#include <sys/types.h>
#include <sys/socket.h>
#include <net/route.h>
#include <net/if.h>
#include <netinet/in.h>
int main(int argc, char **argv)
{
int s;
char buf[1024];
struct rt_msghdr *rtm;
struct sockaddr_in *sin1, *sin2;
if (argc != 3) {
printf("usage: %s <destinationIP> <gatewayIP>
",
argv[0]);
return -1;
}
if ((s = socket(AF_ROUTE, SOCK_RAW, AF_UNSPEC)) < 0) {
perror("failed to create socket");
return -1;
}
rtm = (struct rt_msghdr *)buf;
rtm->rtm_msglen = sizeof(struct rt_msghdr) +
(2 * sizeof(struct sockaddr_in));
rtm->rtm_version = RTM_VERSION;
rtm->rtm_type = RTM_ADD;
rtm->rtm_flags = (RTF_UP | RTF_GATEWAY | RTF_HOST);
rtm->rtm_addrs = (RTA_DST | RTA_GATEWAY);
rtm->rtm_pid = getpid();
rtm->rtm_errno = 0;
rtm->rtm_seq = 0001;
/*
* the destination address being added follows
* the routing header
*/
sin1 = (struct sockaddr_in *)(rtm + 1);
sin1->sin_family = AF_INET;
sin1->sin_addr.s_addr = inet_addr(argv[1]);
/*
* the gateway address being added follows the
* destination address
*/
sin2 = (struct sockaddr_in *)(sin1 + 1);
sin2->sin_family = AF_INET;
sin2->sin_addr.s_addr = inet_addr(argv[2]);
if (write(s, (caddr_t)rtm, rtm->rtm_msglen) < 0) {
perror("Failed to send routing message");
return -1;
}
return 0;
}
AUTHOR
Routing socket interface was developed by HP and the University of California, Berkeley.
SEE ALSO
route(1M), ioctl(2), shutdown(2), socket(2), routing(7).
route(7P)