original/man7/rtnetlink.7

   1 '\" t
   2 .\" Don't remove the line above, it tells man that tbl is needed.
   3 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
   4 .\" Permission is granted to distribute possibly modified copies
   5 .\" of this page provided the header is included verbatim,
   6 .\" and in case of nontrivial modification author and date
   7 .\" of the modification is added to the header.
   8 .\" Based on the original comments from Alexey Kuznetsov, written with
   9 .\" help from Matthew Wilcox.
  10 .\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $
  11 .TH RTNETLINK  7 2008-08-08 "Linux" "Linux Programmer's Manual"
  12 .SH NAME
  13 rtnetlink, NETLINK_ROUTE \- Linux IPv4 routing socket
  14 .SH SYNOPSIS
  15 .B #include <asm/types.h>
  16 .br
  17 .B #include <linux/netlink.h>
  18 .br
  19 .B #include <linux/rtnetlink.h>
  20 .br
  21 .B #include <sys/socket.h>
  22 .sp
  23 .BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type ", NETLINK_ROUTE);"
  24 .SH DESCRIPTION
  25 Rtnetlink allows the kernel's routing tables to be read and altered.
  26 It is used within the kernel to communicate between
  27 various subsystems, though this usage is not documented here, and for
  28 communication with user-space programs.
  29 Network routes, IP addresses, link parameters, neighbor setups, queueing
  30 disciplines, traffic classes and packet classifiers may all be controlled
  31 through
  32 .B NETLINK_ROUTE
  33 sockets.
  34 It is based on netlink messages; see
  35 .BR netlink (7)
  36 for more information.
  37 .\" FIXME ? all these macros could be moved to rtnetlink(3)
  38 .SS "Routing Attributes"
  39 Some rtnetlink messages have optional attributes after the initial header:
  40
  41 .in +4n
  42 .nf
  43 struct rtattr {
  44     unsigned short rta_len;    /* Length of option */
  45     unsigned short rta_type;   /* Type of option */
  46     /* Data follows */
  47 };
  48 .fi
  49 .in
  50
  51 These attributes should be only manipulated using the RTA_* macros
  52 or libnetlink, see
  53 .BR rtnetlink (3).
  54 .SS Messages
  55 Rtnetlink consists of these message types
  56 (in addition to standard netlink messages):
  57 .TP
  58 .BR RTM_NEWLINK ", " RTM_DELLINK ", " RTM_GETLINK
  59 Create, remove or get information about a specific network interface.
  60 These messages contain an
  61 .I ifinfomsg
  62 structure followed by a series of
  63 .I rtattr
  64 structures.
  65
  66 .nf
  67 struct ifinfomsg {
  68     unsigned char  ifi_family; /* AF_UNSPEC */
  69     unsigned short ifi_type;   /* Device type */
  70     int            ifi_index;  /* Interface index */
  71     unsigned int   ifi_flags;  /* Device flags  */
  72     unsigned int   ifi_change; /* change mask */
  73 };
  74 .fi
  75
  76 .\" FIXME ifi_type
  77 .I ifi_flags
  78 contains the device flags, see
  79 .BR netdevice (7);
  80 .I ifi_index
  81 is the unique interface index,
  82 .I ifi_change
  83 is reserved for future use and should be always set to 0xFFFFFFFF.
  84 .TS
  85 tab(:);
  86 c
  87 l l l.
  88 Routing attributes
  89 rta_type:value type:description
  90 _
  91 IFLA_UNSPEC:-:unspecified.
  92 IFLA_ADDRESS:hardware address:interface L2 address
  93 IFLA_BROADCAST:hardware address:L2 broadcast address.
  94 IFLA_IFNAME:asciiz string:Device name.
  95 IFLA_MTU:unsigned int:MTU of the device.
  96 IFLA_LINK:int:Link type.
  97 IFLA_QDISC:asciiz string:Queueing discipline.
  98 IFLA_STATS:T{
  99 see below
 100 T}:Interface Statistics.
 101 .TE
 102 .sp
 103 The value type for IFLA_STATS is \fIstruct net_device_stats\fP.
 104 .TP
 105 .BR RTM_NEWADDR ", " RTM_DELADDR ", " RTM_GETADDR
 106 Add, remove or receive information about an IP address associated with
 107 an interface.
 108 In Linux 2.2, an interface can carry multiple IP addresses,
 109 this replaces the alias device concept in 2.0.
 110 In Linux 2.2, these messages
 111 support IPv4 and IPv6 addresses.
 112 They contain an
 113 .I ifaddrmsg
 114 structure, optionally followed by
 115 .I rtattr
 116 routing attributes.
 117
 118 .nf
 119 struct ifaddrmsg {
 120     unsigned char ifa_family;    /* Address type */
 121     unsigned char ifa_prefixlen; /* Prefixlength of address */
 122     unsigned char ifa_flags;     /* Address flags */
 123     unsigned char ifa_scope;     /* Address scope */
 124     int           ifa_index;     /* Interface index */
 125 };
 126 .fi
 127
 128 .I ifa_family
 129 is the address family type (currently
 130 .B AF_INET
 131 or
 132 .BR AF_INET6 ),
 133 .I ifa_prefixlen
 134 is the length of the address mask of the address if defined for the
 135 family (like for IPv4),
 136 .I ifa_scope
 137 is the address scope,
 138 .I ifa_index
 139 is the interface index of the interface the address is associated with.
 140 .I ifa_flags
 141 is a flag word of
 142 .B IFA_F_SECONDARY
 143 for secondary address (old alias interface),
 144 .B IFA_F_PERMANENT
 145 for a permanent address set by the user and other undocumented flags.
 146 .TS
 147 tab(:);
 148 c
 149 l l l.
 150 Attributes
 151 rta_type:value type:description
 152 _
 153 IFA_UNSPEC:-:unspecified.
 154 IFA_ADDRESS:raw protocol address:interface address
 155 IFA_LOCAL:raw protocol address:local address
 156 IFA_LABEL:asciiz string:name of the interface
 157 IFA_BROADCAST:raw protocol address:broadcast address.
 158 IFA_ANYCAST:raw protocol address:anycast address
 159 IFA_CACHEINFO:struct ifa_cacheinfo:Address information.
 160 .TE
 161 .\" FIXME struct ifa_cacheinfo
 162 .TP
 163 .BR RTM_NEWROUTE ", " RTM_DELROUTE ", " RTM_GETROUTE
 164 Create, remove or receive information about a network route.
 165 These messages contain an
 166 .I rtmsg
 167 structure with an optional sequence of
 168 .I rtattr
 169 structures following.
 170 For
 171 .BR RTM_GETROUTE ,
 172 setting
 173 .I rtm_dst_len
 174 and
 175 .I rtm_src_len
 176 to 0 means you get all entries for the specified routing table.
 177 For the other fields, except
 178 .I rtm_table
 179 and
 180 .IR rtm_protocol ,
 181 0 is the wildcard.
 182
 183 .nf
 184 struct rtmsg {
 185     unsigned char rtm_family;   /* Address family of route */
 186     unsigned char rtm_dst_len;  /* Length of destination */
 187     unsigned char rtm_src_len;  /* Length of source */
 188     unsigned char rtm_tos;      /* TOS filter */
 189
 190     unsigned char rtm_table;    /* Routing table ID */
 191     unsigned char rtm_protocol; /* Routing protocol; see below */
 192     unsigned char rtm_scope;    /* See below */
 193     unsigned char rtm_type;     /* See below */
 194
 195     unsigned int  rtm_flags;
 196 };
 197 .fi
 198 .TS
 199 tab(:);
 200 l l.
 201 rtm_type:Route type
 202 _
 203 RTN_UNSPEC:unknown route
 204 RTN_UNICAST:a gateway or direct route
 205 RTN_LOCAL:a local interface route
 206 RTN_BROADCAST:T{
 207 a local broadcast route (sent as a broadcast)
 208 T}
 209 RTN_ANYCAST:T{
 210 a local broadcast route (sent as a unicast)
 211 T}
 212 RTN_MULTICAST:a multicast route
 213 RTN_BLACKHOLE:a packet dropping route
 214 RTN_UNREACHABLE:an unreachable destination
 215 RTN_PROHIBIT:a packet rejection route
 216 RTN_THROW:continue routing lookup in another table
 217 RTN_NAT:a network address translation rule
 218 RTN_XRESOLVE:T{
 219 refer to an external resolver (not implemented)
 220 T}
 221 .TE
 222 .TS
 223 tab(:);
 224 l l.
 225 rtm_protocol:Route origin.
 226 _
 227 RTPROT_UNSPEC:unknown
 228 RTPROT_REDIRECT:T{
 229 by an ICMP redirect (currently unused)
 230 T}
 231 RTPROT_KERNEL:by the kernel
 232 RTPROT_BOOT:during boot
 233 RTPROT_STATIC:by the administrator
 234 .TE
 235
 236 Values larger than
 237 .B RTPROT_STATIC
 238 are not interpreted by the kernel, they are just for user information.
 239 They may be used to tag the source of a routing information or to
 240 distinguish between multiple routing daemons.
 241 See
 242 .I <linux/rtnetlink.h>
 243 for the routing daemon identifiers which are already assigned.
 244
 245 .I rtm_scope
 246 is the distance to the destination:
 247 .TS
 248 tab(:);
 249 l l.
 250 RT_SCOPE_UNIVERSE:global route
 251 RT_SCOPE_SITE:T{
 252 interior route in the local autonomous system
 253 T}
 254 RT_SCOPE_LINK:route on this link
 255 RT_SCOPE_HOST:route on the local host
 256 RT_SCOPE_NOWHERE:destination doesn't exist
 257 .TE
 258
 259 The values between
 260 .B RT_SCOPE_UNIVERSE
 261 and
 262 .B RT_SCOPE_SITE
 263 are available to the user.
 264
 265 The
 266 .I rtm_flags
 267 have the following meanings:
 268 .TS
 269 tab(:);
 270 l l.
 271 RTM_F_NOTIFY:T{
 272 if the route changes, notify the user via rtnetlink
 273 T}
 274 RTM_F_CLONED:route is cloned from another route
 275 RTM_F_EQUALIZE:a multipath equalizer (not yet implemented)
 276 .TE
 277
 278 .I rtm_table
 279 specifies the routing table
 280 .TS
 281 tab(:);
 282 l l.
 283 RT_TABLE_UNSPEC:an unspecified routing table
 284 RT_TABLE_DEFAULT:the default table
 285 RT_TABLE_MAIN:the main table
 286 RT_TABLE_LOCAL:the local table
 287 .TE
 288
 289 The user may assign arbitrary values between
 290 .B RT_TABLE_UNSPEC
 291 and
 292 .BR RT_TABLE_DEFAULT .
 293 .TS
 294 tab(:);
 295 c
 296 l l l.
 297 Attributes
 298 rta_type:value type:description
 299 _
 300 RTA_UNSPEC:-:ignored.
 301 RTA_DST:protocol address:Route destination address.
 302 RTA_SRC:protocol address:Route source address.
 303 RTA_IIF:int:Input interface index.
 304 RTA_OIF:int:Output interface index.
 305 RTA_GATEWAY:protocol address:The gateway of the route
 306 RTA_PRIORITY:int:Priority of route.
 307 RTA_PREFSRC::
 308 RTA_METRICS:int:Route metric
 309 RTA_MULTIPATH::
 310 RTA_PROTOINFO::
 311 RTA_FLOW::
 312 RTA_CACHEINFO::
 313 .TE
 314
 315 .B Fill these values in!
 316 .TP
 317 .BR RTM_NEWNEIGH ", " RTM_DELNEIGH  ", " RTM_GETNEIGH
 318 Add, remove or receive information about a neighbor table
 319 entry (e.g., an ARP entry).
 320 The message contains an
 321 .I ndmsg
 322 structure.
 323
 324 .nf
 325 struct ndmsg {
 326     unsigned char ndm_family;
 327     int           ndm_ifindex;  /* Interface index */
 328     __u16         ndm_state;    /* State */
 329     __u8          ndm_flags;    /* Flags */
 330     __u8          ndm_type;
 331 };
 332
 333 struct nda_cacheinfo {
 334     __u32         ndm_confirmed;
 335     __u32         ndm_used;
 336     __u32         ndm_updated;
 337     __u32         ndm_refcnt;
 338 };
 339 .fi
 340
 341 .I ndm_state
 342 is a bit mask of the following states:
 343 .TS
 344 tab(:);
 345 l l.
 346 NUD_INCOMPLETE:a currently resolving cache entry
 347 NUD_REACHABLE:a confirmed working cache entry
 348 NUD_STALE:an expired cache entry
 349 NUD_DELAY:an entry waiting for a timer
 350 NUD_PROBE:a cache entry that is currently reprobed
 351 NUD_FAILED:an invalid cache entry
 352 NUD_NOARP:a device with no destination cache
 353 NUD_PERMANENT:a static entry
 354 .TE
 355
 356 Valid
 357 .I ndm_flags
 358 are:
 359 .TS
 360 tab(:);
 361 l l.
 362 NTF_PROXY:a proxy arp entry
 363 NTF_ROUTER:an IPv6 router
 364 .TE
 365
 366 .\" FIXME
 367 .\" document the members of the struct better
 368 The
 369 .I rtattr
 370 struct has the following meanings for the
 371 .I rta_type
 372 field:
 373 .TS
 374 tab(:);
 375 l l.
 376 NDA_UNSPEC:unknown type
 377 NDA_DST:a neighbor cache n/w layer destination address
 378 NDA_LLADDR:a neighbor cache link layer address
 379 NDA_CACHEINFO:cache statistics.
 380 .TE
 381
 382 If the
 383 .I rta_type
 384 field is
 385 .B NDA_CACHEINFO
 386 then a
 387 .I struct nda_cacheinfo
 388 header follows
 389 .TP
 390 .BR RTM_NEWRULE ", " RTM_DELRULE ", " RTM_GETRULE
 391 Add, delete or retrieve a routing rule.
 392 Carries a
 393 .I struct rtmsg
 394 .TP
 395 .BR RTM_NEWQDISC ", " RTM_DELQDISC ", " RTM_GETQDISC
 396 Add, remove or get a queueing discipline.
 397 The message contains a
 398 .I struct tcmsg
 399 and may be followed by a series of
 400 attributes.
 401
 402 .nf
 403 struct tcmsg {
 404     unsigned char    tcm_family;
 405     int              tcm_ifindex;   /* interface index */
 406     __u32            tcm_handle;    /* Qdisc handle */
 407     __u32            tcm_parent;    /* Parent qdisc */
 408     __u32            tcm_info;
 409 };
 410 .fi
 411 .TS
 412 tab(:);
 413 c
 414 l l l.
 415 Attributes
 416 rta_type:value type:Description
 417 _
 418 TCA_UNSPEC:-:unspecified
 419 TCA_KIND:asciiz string:Name of queueing discipline
 420 TCA_OPTIONS:byte sequence:Qdisc-specific options follow
 421 TCA_STATS:struct tc_stats:Qdisc statistics.
 422 TCA_XSTATS:qdisc specific:Module-specific statistics.
 423 TCA_RATE:struct tc_estimator:Rate limit.
 424 .TE
 425
 426 In addition various other qdisc module specific attributes are allowed.
 427 For more information see the appropriate include files.
 428 .TP
 429 .BR RTM_NEWTCLASS ", " RTM_DELTCLASS ", " RTM_GETTCLASS
 430 Add, remove or get a traffic class.
 431 These messages contain a
 432 .I struct tcmsg
 433 as described above.
 434 .TP
 435 .BR RTM_NEWTFILTER ", " RTM_DELTFILTER ", " RTM_GETTFILTER
 436 Add, remove or receive information about a traffic filter.
 437 These messages contain a
 438 .I struct tcmsg
 439 as described above.
 440 .SH VERSIONS
 441 .B rtnetlink
 442 is a new feature of Linux 2.2.
 443 .SH BUGS
 444 This manual page is incomplete.
 445 .SH "SEE ALSO"
 446 .BR cmsg (3),
 447 .BR rtnetlink (3),
 448 .BR ip (7),
 449 .BR netlink (7)