route(7P)

NAME

route — kernel packet forwarding database

SYNOPSIS

#include <sys/types.h> 
#include <sys/socket.h> 
#include <net/route.h> 
#include <net/if.h> 

s = socket(AF_ROUTE, SOCK_RAW, family);

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 Message Types section below.

The family parameter in the socket system call shown in the SYNOPSIS 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 direct connection 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 economical 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, EOPNOTSUPP 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 if_msghdr header. The RTM_NEWADDR and RTM_DELADDR messages use the ifa_msghdr header. All other message types use the rt_msghdr header.

The rt_msghdr 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 if_msghdr 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 ifa_msghdr 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 rt_metrics structure included in the rt_msghdr message header. The rt_metrics structure contains the following 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 if_data structure included in the if_msghdr 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 rtm_addrs, ifm_addrs, and ifam_addrs of the message headers are bitmasks that specify what socket address structure(s) follow the message. When multiple sockaddrs 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 listeners. 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 shutdown(2) 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 following fields:

Structure: Fields Not Used
rt_msghdr: rtm_use, rtm_inits, rtm_rmx, except for rtm_rmx.rmx_mtu and rtm_rmx.rmx_rtt
if_msghdr: ifm_data, except for ifm_data.ifi_mtu, ifm_data.ifi_metric, ifm_data.ifi_ipackets, and ifm_data.ifi_opackets
ifa_msghdr: ifam_metric

ERRORS

If the kernel rejects a routing message, the rtm_errno field in the rt_msghdr structure may be set to one of the following values:

EEXIST: The specified entry already exist. Requested to duplicate an existing entry.
ENETUNREACH: Network is unreachable.
ENOENT: The specified entry does not exist. Requested to delete non-existent entry.
ENOBUFS: No buffer space is available. Insufficient resources were available to install a new route.
EOPNOTSUPP: Operation not supported. Message types RTM_CHANGE and RTM_LOCK are not supported on HP-UX.
EPERM: 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>\n",
                        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_addrs = (RTA_DST | RTA_GATEWAY);
        rtm->rtm_rmx.rmx_hopcount = 1;
        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.