Debian Codegraph @

upstream/opensuse-tumbleweed/man7/rtnetlink.7

raw
1 '\" t
2 .\" Copyright 1999, Andi Kleen <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-1-para
6 .\"
7 .TH rtnetlink 7 2026-02-08 "Linux man-pages (unreleased)"
8 .SH NAME
9 rtnetlink \- Linux routing socket
10 .SH SYNOPSIS
11 .nf
12 .B #include <asm/types.h>
13 .B #include <linux/netlink.h>
14 .B #include <linux/rtnetlink.h>
15 .B #include <sys/socket.h>
16 .P
17 .BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type ", NETLINK_ROUTE);"
18 .fi
19 .SH DESCRIPTION
20 Rtnetlink allows the kernel's routing tables to be read and altered.
21 It is used within the kernel to communicate between
22 various subsystems, though this usage is not documented here, and for
23 communication with user-space programs.
24 Network routes, IP addresses, link parameters, neighbor setups, queueing
25 disciplines, traffic classes and packet classifiers may all be controlled
26 through
27 .B NETLINK_ROUTE
28 sockets.
29 It is based on netlink messages;
30 see
31 .BR netlink (7)
32 for more information.
33 .\" FIXME . ? all these macros could be moved to rtnetlink(3)
34 .SS Routing attributes
35 Some rtnetlink messages have optional attributes after the initial header:
36 .P
37 .in +4n
38 .EX
39 struct rtattr {
40 unsigned short rta_len; /* Length of option */
41 unsigned short rta_type; /* Type of option */
42 /* Data follows */
43 };
44 .EE
45 .in
46 .P
47 These attributes should be manipulated using only the RTA_* macros
48 or libnetlink, see
49 .BR rtnetlink (3).
50 .SS Messages
51 Rtnetlink consists of these message types
52 (in addition to standard netlink messages):
53 .TP
54 .B RTM_NEWLINK
55 .TQ
56 .B RTM_DELLINK
57 .TQ
58 .B 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 .IP
66 .EX
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 .EE
75 .IP
76 .\" FIXME Document ifinfomsg.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 (since Linux 3.7, it is possible to feed a nonzero value with the
83 .B RTM_NEWLINK
84 message, thus creating a link with the given
85 .IR ifindex );
86 .I ifi_change
87 is a mask specifying which bits of
88 .I ifi_flags
89 should be applied to the device.
90 .TS
91 tab(:);
92 c s s
93 lb l l.
94 Routing attributes
95 rta_type:Value type:Description
96 _
97 IFLA_UNSPEC:-:unspecified
98 IFLA_ADDRESS:hardware address:interface L2 address
99 IFLA_BROADCAST:hardware address:L2 broadcast address
100 IFLA_IFNAME:asciiz string:Device name
101 IFLA_MTU:unsigned int:MTU of the device
102 IFLA_LINK:int:Link type
103 IFLA_QDISC:asciiz string:Queueing discipline
104 IFLA_STATS:T{
105 see below
106 T}:Interface Statistics
107 IFLA_PERM_ADDRESS:hardware address:T{
108 hardware address provided by device (since Linux 5.5)
109 T}
110 .TE
111 .IP
112 The value type for
113 .B IFLA_STATS
114 is
115 .I struct rtnl_link_stats
116 .RI ( "struct net_device_stats"
117 in Linux 2.4 and earlier).
118 .TP
119 .B RTM_NEWADDR
120 .TQ
121 .B RTM_DELADDR
122 .TQ
123 .B RTM_GETADDR
124 Add, remove, or receive information about an IP address associated with
125 an interface.
126 In Linux 2.2, an interface can carry multiple IP addresses,
127 this replaces the alias device concept in Linux 2.0.
128 In Linux 2.2, these messages
129 support IPv4 and IPv6 addresses.
130 They contain an
131 .I ifaddrmsg
132 structure, optionally followed by
133 .I rtattr
134 routing attributes.
135 .IP
136 .EX
137 struct ifaddrmsg {
138 unsigned char ifa_family; /* Address type */
139 unsigned char ifa_prefixlen; /* Prefixlength of address */
140 unsigned char ifa_flags; /* Address flags */
141 unsigned char ifa_scope; /* Address scope */
142 unsigned int ifa_index; /* Interface index */
143 };
144 .EE
145 .IP
146 .I ifa_family
147 is the address family type (currently
148 .B AF_INET
149 or
150 .BR AF_INET6 ),
151 .I ifa_prefixlen
152 is the length of the address mask of the address if defined for the
153 family (like for IPv4),
154 .I ifa_scope
155 is the address scope,
156 .I ifa_index
157 is the interface index of the interface the address is associated with.
158 .I ifa_flags
159 is a flag word of
160 .B IFA_F_SECONDARY
161 for secondary address (old alias interface),
162 .B IFA_F_PERMANENT
163 for a permanent address set by the user and other undocumented flags.
164 .TS
165 tab(:);
166 c s s
167 lb l l.
168 Attributes
169 rta_type:Value type:Description
170 _
171 IFA_UNSPEC:-:unspecified
172 IFA_ADDRESS:raw protocol address:interface address
173 IFA_LOCAL:raw protocol address:local address
174 IFA_LABEL:asciiz string:name of the interface
175 IFA_BROADCAST:raw protocol address:broadcast address
176 IFA_ANYCAST:raw protocol address:anycast address
177 IFA_CACHEINFO:struct ifa_cacheinfo:Address information
178 .TE
179 .IP
180 .EX
181 struct ifa_cacheinfo {
182 __u32 ifa_prefered; // Preferred lifetime remaining, in seconds
183 __u32 ifa_valid; // Valid lifetime remaining, in seconds
184 __u32 cstamp; // Creation timestamp, in centiseconds
185 __u32 tstamp; // Update timestamp, in centiseconds
186 };
187 .EE
188 .IP
189 .I ifa_valid
190 cannot be zero, and
191 .I ifa_prefered
192 cannot be greater than
193 .IR ifa_valid .
194 A value of
195 .B UINT32_MAX
196 represents an infinite lifetime.
197 .TP
198 .B RTM_NEWROUTE
199 .TQ
200 .B RTM_DELROUTE
201 .TQ
202 .B RTM_GETROUTE
203 Create, remove, or receive information about a network route.
204 These messages contain an
205 .I rtmsg
206 structure with an optional sequence of
207 .I rtattr
208 structures following.
209 For
210 .BR RTM_GETROUTE ,
211 setting
212 .I rtm_dst_len
213 and
214 .I rtm_src_len
215 to 0 means you get all entries for the specified routing table.
216 For the other fields, except
217 .I rtm_table
218 and
219 .IR rtm_protocol ,
220 0 is the wildcard.
221 .IP
222 .EX
223 struct rtmsg {
224 unsigned char rtm_family; /* Address family of route */
225 unsigned char rtm_dst_len; /* Length of destination */
226 unsigned char rtm_src_len; /* Length of source */
227 unsigned char rtm_tos; /* TOS filter */
228 unsigned char rtm_table; /* Routing table ID;
229 see RTA_TABLE below */
230 unsigned char rtm_protocol; /* Routing protocol; see below */
231 unsigned char rtm_scope; /* See below */
232 unsigned char rtm_type; /* See below */
233 \&
234 unsigned int rtm_flags;
235 };
236 .EE
237 .TS
238 tab(:);
239 lb l.
240 rtm_type:Route type
241 _
242 RTN_UNSPEC:unknown route
243 RTN_UNICAST:a gateway or direct route
244 RTN_LOCAL:a local interface route
245 RTN_BROADCAST:T{
246 a local broadcast route (sent as a broadcast)
247 T}
248 RTN_ANYCAST:T{
249 a local broadcast route (sent as a unicast)
250 T}
251 RTN_MULTICAST:a multicast route
252 RTN_BLACKHOLE:a packet dropping route
253 RTN_UNREACHABLE:an unreachable destination
254 RTN_PROHIBIT:a packet rejection route
255 RTN_THROW:continue routing lookup in another table
256 RTN_NAT:a network address translation rule
257 RTN_XRESOLVE:T{
258 refer to an external resolver (not implemented)
259 T}
260 .TE
261 .TS
262 tab(:);
263 lb l.
264 rtm_protocol:Route origin
265 _
266 RTPROT_UNSPEC:unknown
267 RTPROT_REDIRECT:T{
268 by an ICMP redirect (currently unused)
269 T}
270 RTPROT_KERNEL:by the kernel
271 RTPROT_BOOT:during boot
272 RTPROT_STATIC:by the administrator
273 .TE
274 .IP
275 Values larger than
276 .B RTPROT_STATIC
277 are not interpreted by the kernel, they are just for user information.
278 They may be used to tag the source of a routing information or to
279 distinguish between multiple routing daemons.
280 See
281 .I <linux/rtnetlink.h>
282 for the routing daemon identifiers which are already assigned.
283 .IP
284 .I rtm_scope
285 is the distance to the destination:
286 .TS
287 tab(:);
288 lb l.
289 RT_SCOPE_UNIVERSE:global route
290 RT_SCOPE_SITE:T{
291 interior route in the local autonomous system
292 T}
293 RT_SCOPE_LINK:route on this link
294 RT_SCOPE_HOST:route on the local host
295 RT_SCOPE_NOWHERE:destination doesn't exist
296 .TE
297 .IP
298 The values between
299 .B RT_SCOPE_UNIVERSE
300 and
301 .B RT_SCOPE_SITE
302 are available to the user.
303 .IP
304 The
305 .I rtm_flags
306 have the following meanings:
307 .TS
308 tab(:);
309 lb l.
310 RTM_F_NOTIFY:T{
311 if the route changes, notify the user via rtnetlink
312 T}
313 RTM_F_CLONED:route is cloned from another route
314 RTM_F_EQUALIZE:a multipath equalizer (not yet implemented)
315 .TE
316 .IP
317 .I rtm_table
318 specifies the routing table
319 .TS
320 tab(:);
321 lb l.
322 RT_TABLE_UNSPEC:an unspecified routing table
323 RT_TABLE_DEFAULT:the default table
324 RT_TABLE_MAIN:the main table
325 RT_TABLE_LOCAL:the local table
326 .TE
327 .IP
328 The user may assign arbitrary values between
329 .B RT_TABLE_UNSPEC
330 and
331 .BR RT_TABLE_DEFAULT .
332 .\" Keep table on same page
333 .bp +1
334 .TS
335 tab(:);
336 c s s
337 lb2 l2 l.
338 Attributes
339 rta_type:Value type:Description
340 _
341 RTA_UNSPEC:-:ignored
342 RTA_DST:protocol address:Route destination address
343 RTA_SRC:protocol address:Route source address
344 RTA_IIF:int:Input interface index
345 RTA_OIF:int:Output interface index
346 RTA_GATEWAY:protocol address:The gateway of the route
347 RTA_PRIORITY:int:Priority of route
348 RTA_PREFSRC:protocol address:Preferred source address
349 RTA_METRICS::T{
350 Route metrics
351 .br
352 (see below).
353 T}
354 RTA_MULTIPATH::T{
355 Multipath nexthop data
356 .br
357 (see below).
358 T}
359 RTA_PROTOINFO::No longer used
360 RTA_FLOW:int:Route realm
361 RTA_CACHEINFO:struct rta_cacheinfo:(see linux/rtnetlink.h)
362 RTA_SESSION::No longer used
363 RTA_MP_ALGO::No longer used
364 RTA_TABLE:int:T{
365 Routing table ID;
366 if set,
367 .br
368 rtm_table is ignored
369 T}
370 RTA_MARK:int:
371 RTA_MFC_STATS:struct rta_mfc_stats:(see linux/rtnetlink.h)
372 RTA_VIA:struct rtvia:T{
373 Gateway in different AF
374 (see below)
375 T}
376 RTA_NEWDST:protocol address:T{
377 Change packet
378 destination address
379 T}
380 RTA_PREF:char:T{
381 RFC4191 IPv6 router
382 preference (see below)
383 T}
384 RTA_ENCAP_TYPE:short:T{
385 Encapsulation type for
386 .br
387 lwtunnels (see below)
388 T}
389 RTA_ENCAP::Defined by RTA_ENCAP_TYPE
390 RTA_EXPIRES:int:T{
391 Expire time for IPv6
392 routes (in seconds)
393 T}
394 .TE
395 .IP
396 .B RTA_METRICS
397 contains an array of
398 .I struct rtattr
399 with their corresponding attributes:
400 .RS
401 .IP
402 .TS
403 tab(:);
404 c s s
405 lb l lx.
406 Attributes
407 rta_type:Value type:Description
408 _
409 RTAX_UNSPEC:-:unspecified
410 RTAX_LOCK:__u32:T{
411 Bit field indicating which RTAX_* attributes are locked.
412 T}
413 RTAX_MTU:__u32:T{
414 Maximum Transmission Unit for this route.
415 T}
416 RTAX_WINDOW:__u32:T{
417 Maximum size of the receive window for this route.
418 T}
419 RTAX_RTT:__u32:T{
420 Estimated round-trip time for this route.
421 T}
422 RTAX_RTTVAR:__u32:T{
423 Estimated round-trip time variation for this route.
424 T}
425 RTAX_SSTHRESH:__u32:T{
426 Slow start threshold to use for this route.
427 T}
428 RTAX_CWND:__u32:T{
429 Maximum size of the congestion window for this route.
430 T}
431 RTAX_ADVMSS:__u32:T{
432 Maximum Segment Size to advertise for this route.
433 T}
434 RTAX_REORDERING:__u32:T{
435 Initial reordering level of packets for this route.
436 T}
437 RTAX_HOPLIMIT:__u32:T{
438 Hop limit (TTL) to use for this route.
439 T}
440 RTAX_INITCWND:__u32:T{
441 Initial congestion window to use for this route.
442 T}
443 RTAX_FEATURES:__u32:T{
444 Features to enable for this route specifically.
445 T}
446 RTAX_RTO_MIN:__u32:T{
447 Minimum Retransmission TimeOut to use for this route.
448 T}
449 RTAX_INITRWND:__u32:T{
450 Initial size of the receive window for this route.
451 T}
452 RTAX_QUICKACK:__u32:T{
453 Use quick ack for this route.
454 T}
455 RTAX_CC_ALGO:asciiz string:T{
456 Congestion Control algorithm to use for this route.
457 T}
458 RTAX_FASTOPEN_NO_COOKIE:__u32:T{
459 Allow TCP Fast Open without cookie.
460 T}
461 .TE
462 .RE
463 .IP
464 Metrics that are locked with
465 .B RTAX_LOCK
466 take precedence over the values normally used by the kernel
467 (computed or assigned by a sysctl or setsockopt(2)).
468 Therefore, some metrics, like
469 .BR RTAX_RTO_MIN ,
470 have no effect unless their bit is set in
471 .BR RTAX_LOCK .
472 .IP
473 .B RTA_MULTIPATH
474 contains several packed instances of
475 .I struct rtnexthop
476 together with nested RTAs
477 .RB ( RTA_GATEWAY ):
478 .IP
479 .in +4n
480 .EX
481 struct rtnexthop {
482 unsigned short rtnh_len; /* Length of struct + length
483 of RTAs */
484 unsigned char rtnh_flags; /* Flags (see
485 linux/rtnetlink.h) */
486 unsigned char rtnh_hops; /* Nexthop priority */
487 int rtnh_ifindex; /* Interface index for this
488 nexthop */
489 }
490 .EE
491 .in
492 .IP
493 There exist a bunch of
494 .B RTNH_*
495 macros similar to
496 .B RTA_*
497 and
498 .B NLHDR_*
499 macros
500 useful to handle these structures.
501 .IP
502 .in +4n
503 .EX
504 struct rtvia {
505 unsigned short rtvia_family;
506 unsigned char rtvia_addr[0];
507 };
508 .EE
509 .in
510 .IP
511 .I rtvia_addr
512 is the address,
513 .I rtvia_family
514 is its family type.
515 .IP
516 .B RTA_PREF
517 may contain values
518 .BR ICMPV6_ROUTER_PREF_LOW ,
519 .BR ICMPV6_ROUTER_PREF_MEDIUM ,
520 and
521 .B ICMPV6_ROUTER_PREF_HIGH
522 defined incw
523 .IR <linux/icmpv6.h> .
524 .IP
525 .B RTA_ENCAP_TYPE
526 may contain values
527 .BR LWTUNNEL_ENCAP_MPLS ,
528 .BR LWTUNNEL_ENCAP_IP ,
529 .BR LWTUNNEL_ENCAP_ILA ,
530 or
531 .B LWTUNNEL_ENCAP_IP6
532 defined in
533 .IR <linux/lwtunnel.h> .
534 .IP
535 .B Fill these values in!
536 .TP
537 .B RTM_NEWNEIGH
538 .TQ
539 .B RTM_DELNEIGH
540 .TQ
541 .B RTM_GETNEIGH
542 Add, remove, or receive information about a neighbor table
543 entry (e.g., an ARP entry).
544 The message contains an
545 .I ndmsg
546 structure.
547 .IP
548 .EX
549 struct ndmsg {
550 unsigned char ndm_family;
551 int ndm_ifindex; /* Interface index */
552 __u16 ndm_state; /* State */
553 __u8 ndm_flags; /* Flags */
554 __u8 ndm_type;
555 };
556 \&
557 struct nda_cacheinfo {
558 __u32 ndm_confirmed;
559 __u32 ndm_used;
560 __u32 ndm_updated;
561 __u32 ndm_refcnt;
562 };
563 .EE
564 .IP
565 .I ndm_state
566 is a bit mask of the following states:
567 .TS
568 tab(:);
569 lb l.
570 NUD_INCOMPLETE:a currently resolving cache entry
571 NUD_REACHABLE:a confirmed working cache entry
572 NUD_STALE:an expired cache entry
573 NUD_DELAY:an entry waiting for a timer
574 NUD_PROBE:a cache entry that is currently reprobed
575 NUD_FAILED:an invalid cache entry
576 NUD_NOARP:a device with no destination cache
577 NUD_PERMANENT:a static entry
578 .TE
579 .IP
580 Valid
581 .I ndm_flags
582 are:
583 .TS
584 tab(:);
585 lb l.
586 NTF_PROXY:a proxy arp entry
587 NTF_ROUTER:an IPv6 router
588 .TE
589 .IP
590 .\" FIXME .
591 .\" document the members of the struct better
592 The
593 .I rtattr
594 struct has the following meanings for the
595 .I rta_type
596 field:
597 .TS
598 tab(:);
599 lb l.
600 NDA_UNSPEC:unknown type
601 NDA_DST:a neighbor cache n/w layer destination address
602 NDA_LLADDR:a neighbor cache link layer address
603 NDA_CACHEINFO:cache statistics
604 .TE
605 .IP
606 If the
607 .I rta_type
608 field is
609 .BR NDA_CACHEINFO ,
610 then a
611 .I struct nda_cacheinfo
612 header follows.
613 .TP
614 .B RTM_NEWRULE
615 .TQ
616 .B RTM_DELRULE
617 .TQ
618 .B RTM_GETRULE
619 Add, delete, or retrieve a routing rule.
620 Carries a
621 .I struct rtmsg
622 .TP
623 .B RTM_NEWQDISC
624 .TQ
625 .B RTM_DELQDISC
626 .TQ
627 .B RTM_GETQDISC
628 Add, remove, or get a queueing discipline.
629 The message contains a
630 .I struct tcmsg
631 and may be followed by a series of
632 attributes.
633 .IP
634 .EX
635 struct tcmsg {
636 unsigned char tcm_family;
637 int tcm_ifindex; /* interface index */
638 __u32 tcm_handle; /* Qdisc handle */
639 __u32 tcm_parent; /* Parent qdisc */
640 __u32 tcm_info;
641 };
642 .EE
643 .TS
644 tab(:);
645 c s s
646 lb2 l2 l.
647 Attributes
648 rta_type:Value type:Description
649 _
650 TCA_UNSPEC:-:unspecified
651 TCA_KIND:asciiz string:Name of queueing discipline
652 TCA_OPTIONS:byte sequence:Qdisc-specific options follow
653 TCA_STATS:struct tc_stats:Qdisc statistics
654 TCA_XSTATS:qdisc-specific:Module-specific statistics
655 TCA_RATE:struct tc_estimator:Rate limit
656 .TE
657 .IP
658 In addition, various other qdisc-module-specific attributes are allowed.
659 For more information see the appropriate include files.
660 .TP
661 .B RTM_NEWTCLASS
662 .TQ
663 .B RTM_DELTCLASS
664 .TQ
665 .B RTM_GETTCLASS
666 Add, remove, or get a traffic class.
667 These messages contain a
668 .I struct tcmsg
669 as described above.
670 .TP
671 .B RTM_NEWTFILTER
672 .TQ
673 .B RTM_DELTFILTER
674 .TQ
675 .B RTM_GETTFILTER
676 Add, remove, or receive information about a traffic filter.
677 These messages contain a
678 .I struct tcmsg
679 as described above.
680 .SH VERSIONS
681 .B rtnetlink
682 is a new feature of Linux 2.2.
683 .SH BUGS
684 This manual page is incomplete.
685 .SH SEE ALSO
686 .BR cmsg (3),
687 .BR rtnetlink (3),
688 .BR ip (7),
689 .BR netlink (7)