Debian Codegraph @

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