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