Debian Codegraph @

upstream/fedora-44/man7/rtnetlink.7

raw
1 '\" t
2 .\" SPDX-License-Identifier: Linux-man-pages-1-para
3 .\"
4 .\" This man page is Copyright (C) 1999 Andi Kleen <[email protected]>.
5 .\"
6 .\" Based on the original comments from Alexey Kuznetsov, written with
7 .\" help from Matthew Wilcox.
8 .\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $
9 .\"
10 .TH rtnetlink 7 2024-11-13 "Linux man-pages 6.13"
11 .SH NAME
12 rtnetlink \- Linux routing socket
13 .SH SYNOPSIS
14 .nf
15 .B #include <asm/types.h>
16 .B #include <linux/netlink.h>
17 .B #include <linux/rtnetlink.h>
18 .B #include <sys/socket.h>
19 .P
20 .BI "rtnetlink_socket = socket(AF_NETLINK, int " socket_type ", NETLINK_ROUTE);"
21 .fi
22 .SH DESCRIPTION
23 Rtnetlink allows the kernel's routing tables to be read and altered.
24 It is used within the kernel to communicate between
25 various subsystems, though this usage is not documented here, and for
26 communication with user-space programs.
27 Network routes, IP addresses, link parameters, neighbor setups, queueing
28 disciplines, traffic classes and packet classifiers may all be controlled
29 through
30 .B NETLINK_ROUTE
31 sockets.
32 It is based on netlink messages; see
33 .BR netlink (7)
34 for more information.
35 .\" FIXME . ? all these macros could be moved to rtnetlink(3)
36 .SS Routing attributes
37 Some rtnetlink messages have optional attributes after the initial header:
38 .P
39 .in +4n
40 .EX
41 struct rtattr {
42 unsigned short rta_len; /* Length of option */
43 unsigned short rta_type; /* Type of option */
44 /* Data follows */
45 };
46 .EE
47 .in
48 .P
49 These attributes should be manipulated using only 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 .B RTM_NEWLINK
57 .TQ
58 .B RTM_DELLINK
59 .TQ
60 .B RTM_GETLINK
61 Create, remove, or get information about a specific network interface.
62 These messages contain an
63 .I ifinfomsg
64 structure followed by a series of
65 .I rtattr
66 structures.
67 .IP
68 .EX
69 struct ifinfomsg {
70 unsigned char ifi_family; /* AF_UNSPEC */
71 unsigned short ifi_type; /* Device type */
72 int ifi_index; /* Interface index */
73 unsigned int ifi_flags; /* Device flags */
74 unsigned int ifi_change; /* change mask */
75 };
76 .EE
77 .IP
78 .\" FIXME Document ifinfomsg.ifi_type
79 .I ifi_flags
80 contains the device flags, see
81 .BR netdevice (7);
82 .I ifi_index
83 is the unique interface index
84 (since Linux 3.7, it is possible to feed a nonzero value with the
85 .B RTM_NEWLINK
86 message, thus creating a link with the given
87 .IR ifindex );
88 .I ifi_change
89 is reserved for future use and should be always set to 0xFFFFFFFF.
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:int:Route metric
350 RTA_MULTIPATH::T{
351 Multipath nexthop data
352 br
353 (see below).
354 T}
355 RTA_PROTOINFO::No longer used
356 RTA_FLOW:int:Route realm
357 RTA_CACHEINFO:struct rta_cacheinfo:(see linux/rtnetlink.h)
358 RTA_SESSION::No longer used
359 RTA_MP_ALGO::No longer used
360 RTA_TABLE:int:T{
361 Routing table ID; if set,
362 .br
363 rtm_table is ignored
364 T}
365 RTA_MARK:int:
366 RTA_MFC_STATS:struct rta_mfc_stats:(see linux/rtnetlink.h)
367 RTA_VIA:struct rtvia:T{
368 Gateway in different AF
369 (see below)
370 T}
371 RTA_NEWDST:protocol address:T{
372 Change packet
373 destination address
374 T}
375 RTA_PREF:char:T{
376 RFC4191 IPv6 router
377 preference (see below)
378 T}
379 RTA_ENCAP_TYPE:short:T{
380 Encapsulation type for
381 .br
382 lwtunnels (see below)
383 T}
384 RTA_ENCAP::Defined by RTA_ENCAP_TYPE
385 RTA_EXPIRES:int:T{
386 Expire time for IPv6
387 routes (in seconds)
388 T}
389 .TE
390 .IP
391 .B RTA_MULTIPATH
392 contains several packed instances of
393 .I struct rtnexthop
394 together with nested RTAs
395 .RB ( RTA_GATEWAY ):
396 .IP
397 .in +4n
398 .EX
399 struct rtnexthop {
400 unsigned short rtnh_len; /* Length of struct + length
401 of RTAs */
402 unsigned char rtnh_flags; /* Flags (see
403 linux/rtnetlink.h) */
404 unsigned char rtnh_hops; /* Nexthop priority */
405 int rtnh_ifindex; /* Interface index for this
406 nexthop */
407 }
408 .EE
409 .in
410 .IP
411 There exist a bunch of
412 .B RTNH_*
413 macros similar to
414 .B RTA_*
415 and
416 .B NLHDR_*
417 macros
418 useful to handle these structures.
419 .IP
420 .in +4n
421 .EX
422 struct rtvia {
423 unsigned short rtvia_family;
424 unsigned char rtvia_addr[0];
425 };
426 .EE
427 .in
428 .IP
429 .I rtvia_addr
430 is the address,
431 .I rtvia_family
432 is its family type.
433 .IP
434 .B RTA_PREF
435 may contain values
436 .BR ICMPV6_ROUTER_PREF_LOW ,
437 .BR ICMPV6_ROUTER_PREF_MEDIUM ,
438 and
439 .B ICMPV6_ROUTER_PREF_HIGH
440 defined incw
441 .IR <linux/icmpv6.h> .
442 .IP
443 .B RTA_ENCAP_TYPE
444 may contain values
445 .BR LWTUNNEL_ENCAP_MPLS ,
446 .BR LWTUNNEL_ENCAP_IP ,
447 .BR LWTUNNEL_ENCAP_ILA ,
448 or
449 .B LWTUNNEL_ENCAP_IP6
450 defined in
451 .IR <linux/lwtunnel.h> .
452 .IP
453 .B Fill these values in!
454 .TP
455 .B RTM_NEWNEIGH
456 .TQ
457 .B RTM_DELNEIGH
458 .TQ
459 .B RTM_GETNEIGH
460 Add, remove, or receive information about a neighbor table
461 entry (e.g., an ARP entry).
462 The message contains an
463 .I ndmsg
464 structure.
465 .IP
466 .EX
467 struct ndmsg {
468 unsigned char ndm_family;
469 int ndm_ifindex; /* Interface index */
470 __u16 ndm_state; /* State */
471 __u8 ndm_flags; /* Flags */
472 __u8 ndm_type;
473 };
474 \&
475 struct nda_cacheinfo {
476 __u32 ndm_confirmed;
477 __u32 ndm_used;
478 __u32 ndm_updated;
479 __u32 ndm_refcnt;
480 };
481 .EE
482 .IP
483 .I ndm_state
484 is a bit mask of the following states:
485 .TS
486 tab(:);
487 lb l.
488 NUD_INCOMPLETE:a currently resolving cache entry
489 NUD_REACHABLE:a confirmed working cache entry
490 NUD_STALE:an expired cache entry
491 NUD_DELAY:an entry waiting for a timer
492 NUD_PROBE:a cache entry that is currently reprobed
493 NUD_FAILED:an invalid cache entry
494 NUD_NOARP:a device with no destination cache
495 NUD_PERMANENT:a static entry
496 .TE
497 .IP
498 Valid
499 .I ndm_flags
500 are:
501 .TS
502 tab(:);
503 lb l.
504 NTF_PROXY:a proxy arp entry
505 NTF_ROUTER:an IPv6 router
506 .TE
507 .IP
508 .\" FIXME .
509 .\" document the members of the struct better
510 The
511 .I rtattr
512 struct has the following meanings for the
513 .I rta_type
514 field:
515 .TS
516 tab(:);
517 lb l.
518 NDA_UNSPEC:unknown type
519 NDA_DST:a neighbor cache n/w layer destination address
520 NDA_LLADDR:a neighbor cache link layer address
521 NDA_CACHEINFO:cache statistics
522 .TE
523 .IP
524 If the
525 .I rta_type
526 field is
527 .BR NDA_CACHEINFO ,
528 then a
529 .I struct nda_cacheinfo
530 header follows.
531 .TP
532 .B RTM_NEWRULE
533 .TQ
534 .B RTM_DELRULE
535 .TQ
536 .B RTM_GETRULE
537 Add, delete, or retrieve a routing rule.
538 Carries a
539 .I struct rtmsg
540 .TP
541 .B RTM_NEWQDISC
542 .TQ
543 .B RTM_DELQDISC
544 .TQ
545 .B RTM_GETQDISC
546 Add, remove, or get a queueing discipline.
547 The message contains a
548 .I struct tcmsg
549 and may be followed by a series of
550 attributes.
551 .IP
552 .EX
553 struct tcmsg {
554 unsigned char tcm_family;
555 int tcm_ifindex; /* interface index */
556 __u32 tcm_handle; /* Qdisc handle */
557 __u32 tcm_parent; /* Parent qdisc */
558 __u32 tcm_info;
559 };
560 .EE
561 .TS
562 tab(:);
563 c s s
564 lb2 l2 l.
565 Attributes
566 rta_type:Value type:Description
567 _
568 TCA_UNSPEC:-:unspecified
569 TCA_KIND:asciiz string:Name of queueing discipline
570 TCA_OPTIONS:byte sequence:Qdisc-specific options follow
571 TCA_STATS:struct tc_stats:Qdisc statistics
572 TCA_XSTATS:qdisc-specific:Module-specific statistics
573 TCA_RATE:struct tc_estimator:Rate limit
574 .TE
575 .IP
576 In addition, various other qdisc-module-specific attributes are allowed.
577 For more information see the appropriate include files.
578 .TP
579 .B RTM_NEWTCLASS
580 .TQ
581 .B RTM_DELTCLASS
582 .TQ
583 .B RTM_GETTCLASS
584 Add, remove, or get a traffic class.
585 These messages contain a
586 .I struct tcmsg
587 as described above.
588 .TP
589 .B RTM_NEWTFILTER
590 .TQ
591 .B RTM_DELTFILTER
592 .TQ
593 .B RTM_GETTFILTER
594 Add, remove, or receive information about a traffic filter.
595 These messages contain a
596 .I struct tcmsg
597 as described above.
598 .SH VERSIONS
599 .B rtnetlink
600 is a new feature of Linux 2.2.
601 .SH BUGS
602 This manual page is incomplete.
603 .SH SEE ALSO
604 .BR cmsg (3),
605 .BR rtnetlink (3),
606 .BR ip (7),
607 .BR netlink (7)