| blob | 86ed459bba675222a13e345191c5f69a8a9ac4f7 |
1 '\" t
2 .\" SPDX-License-Identifier: Linux-man-pages-1-para
3 .\"
4 .\" This man page is Copyright (C) 1999 Andi Kleen <ak@muc.de>.
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 (date) "Linux man-pages (unreleased)"
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 .\" FIXME Document struct ifa_cacheinfo
180 .TP
181 .B RTM_NEWROUTE
182 .TQ
183 .B RTM_DELROUTE
184 .TQ
185 .B RTM_GETROUTE
186 Create, remove, or receive information about a network route.
187 These messages contain an
188 .I rtmsg
189 structure with an optional sequence of
190 .I rtattr
191 structures following.
192 For
193 .BR RTM_GETROUTE ,
194 setting
195 .I rtm_dst_len
196 and
197 .I rtm_src_len
198 to 0 means you get all entries for the specified routing table.
199 For the other fields, except
200 .I rtm_table
201 and
202 .IR rtm_protocol ,
203 0 is the wildcard.
204 .IP
205 .EX
206 struct rtmsg {
207 unsigned char rtm_family; /* Address family of route */
208 unsigned char rtm_dst_len; /* Length of destination */
209 unsigned char rtm_src_len; /* Length of source */
210 unsigned char rtm_tos; /* TOS filter */
211 unsigned char rtm_table; /* Routing table ID;
212 see RTA_TABLE below */
213 unsigned char rtm_protocol; /* Routing protocol; see below */
214 unsigned char rtm_scope; /* See below */
215 unsigned char rtm_type; /* See below */
216 \&
217 unsigned int rtm_flags;
218 };
219 .EE
220 .TS
221 tab(:);
222 lb l.
223 rtm_type:Route type
224 _
225 RTN_UNSPEC:unknown route
226 RTN_UNICAST:a gateway or direct route
227 RTN_LOCAL:a local interface route
228 RTN_BROADCAST:T{
229 a local broadcast route (sent as a broadcast)
230 T}
231 RTN_ANYCAST:T{
232 a local broadcast route (sent as a unicast)
233 T}
234 RTN_MULTICAST:a multicast route
235 RTN_BLACKHOLE:a packet dropping route
236 RTN_UNREACHABLE:an unreachable destination
237 RTN_PROHIBIT:a packet rejection route
238 RTN_THROW:continue routing lookup in another table
239 RTN_NAT:a network address translation rule
240 RTN_XRESOLVE:T{
241 refer to an external resolver (not implemented)
242 T}
243 .TE
244 .TS
245 tab(:);
246 lb l.
247 rtm_protocol:Route origin
248 _
249 RTPROT_UNSPEC:unknown
250 RTPROT_REDIRECT:T{
251 by an ICMP redirect (currently unused)
252 T}
253 RTPROT_KERNEL:by the kernel
254 RTPROT_BOOT:during boot
255 RTPROT_STATIC:by the administrator
256 .TE
257 .IP
258 Values larger than
259 .B RTPROT_STATIC
260 are not interpreted by the kernel, they are just for user information.
261 They may be used to tag the source of a routing information or to
262 distinguish between multiple routing daemons.
263 See
264 .I <linux/rtnetlink.h>
265 for the routing daemon identifiers which are already assigned.
266 .IP
267 .I rtm_scope
268 is the distance to the destination:
269 .TS
270 tab(:);
271 lb l.
272 RT_SCOPE_UNIVERSE:global route
273 RT_SCOPE_SITE:T{
274 interior route in the local autonomous system
275 T}
276 RT_SCOPE_LINK:route on this link
277 RT_SCOPE_HOST:route on the local host
278 RT_SCOPE_NOWHERE:destination doesn't exist
279 .TE
280 .IP
281 The values between
282 .B RT_SCOPE_UNIVERSE
283 and
284 .B RT_SCOPE_SITE
285 are available to the user.
286 .IP
287 The
288 .I rtm_flags
289 have the following meanings:
290 .TS
291 tab(:);
292 lb l.
293 RTM_F_NOTIFY:T{
294 if the route changes, notify the user via rtnetlink
295 T}
296 RTM_F_CLONED:route is cloned from another route
297 RTM_F_EQUALIZE:a multipath equalizer (not yet implemented)
298 .TE
299 .IP
300 .I rtm_table
301 specifies the routing table
302 .TS
303 tab(:);
304 lb l.
305 RT_TABLE_UNSPEC:an unspecified routing table
306 RT_TABLE_DEFAULT:the default table
307 RT_TABLE_MAIN:the main table
308 RT_TABLE_LOCAL:the local table
309 .TE
310 .IP
311 The user may assign arbitrary values between
312 .B RT_TABLE_UNSPEC
313 and
314 .BR RT_TABLE_DEFAULT .
315 .\" Keep table on same page
316 .bp +1
317 .TS
318 tab(:);
319 c s s
320 lb2 l2 l.
321 Attributes
322 rta_type:Value type:Description
323 _
324 RTA_UNSPEC:-:ignored
325 RTA_DST:protocol address:Route destination address
326 RTA_SRC:protocol address:Route source address
327 RTA_IIF:int:Input interface index
328 RTA_OIF:int:Output interface index
329 RTA_GATEWAY:protocol address:The gateway of the route
330 RTA_PRIORITY:int:Priority of route
331 RTA_PREFSRC:protocol address:Preferred source address
332 RTA_METRICS:int:Route metric
333 RTA_MULTIPATH::T{
334 Multipath nexthop data
335 br
336 (see below).
337 T}
338 RTA_PROTOINFO::No longer used
339 RTA_FLOW:int:Route realm
340 RTA_CACHEINFO:struct rta_cacheinfo:(see linux/rtnetlink.h)
341 RTA_SESSION::No longer used
342 RTA_MP_ALGO::No longer used
343 RTA_TABLE:int:T{
344 Routing table ID; if set,
345 .br
346 rtm_table is ignored
347 T}
348 RTA_MARK:int:
349 RTA_MFC_STATS:struct rta_mfc_stats:(see linux/rtnetlink.h)
350 RTA_VIA:struct rtvia:T{
351 Gateway in different AF
352 (see below)
353 T}
354 RTA_NEWDST:protocol address:T{
355 Change packet
356 destination address
357 T}
358 RTA_PREF:char:T{
359 RFC4191 IPv6 router
360 preference (see below)
361 T}
362 RTA_ENCAP_TYPE:short:T{
363 Encapsulation type for
364 .br
365 lwtunnels (see below)
366 T}
367 RTA_ENCAP::Defined by RTA_ENCAP_TYPE
368 RTA_EXPIRES:int:T{
369 Expire time for IPv6
370 routes (in seconds)
371 T}
372 .TE
373 .IP
374 .B RTA_MULTIPATH
375 contains several packed instances of
376 .I struct rtnexthop
377 together with nested RTAs
378 .RB ( RTA_GATEWAY ):
379 .IP
380 .in +4n
381 .EX
382 struct rtnexthop {
383 unsigned short rtnh_len; /* Length of struct + length
384 of RTAs */
385 unsigned char rtnh_flags; /* Flags (see
386 linux/rtnetlink.h) */
387 unsigned char rtnh_hops; /* Nexthop priority */
388 int rtnh_ifindex; /* Interface index for this
389 nexthop */
390 }
391 .EE
392 .in
393 .IP
394 There exist a bunch of
395 .B RTNH_*
396 macros similar to
397 .B RTA_*
398 and
399 .B NLHDR_*
400 macros
401 useful to handle these structures.
402 .IP
403 .in +4n
404 .EX
405 struct rtvia {
406 unsigned short rtvia_family;
407 unsigned char rtvia_addr[0];
408 };
409 .EE
410 .in
411 .IP
412 .I rtvia_addr
413 is the address,
414 .I rtvia_family
415 is its family type.
416 .IP
417 .B RTA_PREF
418 may contain values
419 .BR ICMPV6_ROUTER_PREF_LOW ,
420 .BR ICMPV6_ROUTER_PREF_MEDIUM ,
421 and
422 .B ICMPV6_ROUTER_PREF_HIGH
423 defined incw
424 .IR <linux/icmpv6.h> .
425 .IP
426 .B RTA_ENCAP_TYPE
427 may contain values
428 .BR LWTUNNEL_ENCAP_MPLS ,
429 .BR LWTUNNEL_ENCAP_IP ,
430 .BR LWTUNNEL_ENCAP_ILA ,
431 or
432 .B LWTUNNEL_ENCAP_IP6
433 defined in
434 .IR <linux/lwtunnel.h> .
435 .IP
436 .B Fill these values in!
437 .TP
438 .B RTM_NEWNEIGH
439 .TQ
440 .B RTM_DELNEIGH
441 .TQ
442 .B RTM_GETNEIGH
443 Add, remove, or receive information about a neighbor table
444 entry (e.g., an ARP entry).
445 The message contains an
446 .I ndmsg
447 structure.
448 .IP
449 .EX
450 struct ndmsg {
451 unsigned char ndm_family;
452 int ndm_ifindex; /* Interface index */
453 __u16 ndm_state; /* State */
454 __u8 ndm_flags; /* Flags */
455 __u8 ndm_type;
456 };
457 \&
458 struct nda_cacheinfo {
459 __u32 ndm_confirmed;
460 __u32 ndm_used;
461 __u32 ndm_updated;
462 __u32 ndm_refcnt;
463 };
464 .EE
465 .IP
466 .I ndm_state
467 is a bit mask of the following states:
468 .TS
469 tab(:);
470 lb l.
471 NUD_INCOMPLETE:a currently resolving cache entry
472 NUD_REACHABLE:a confirmed working cache entry
473 NUD_STALE:an expired cache entry
474 NUD_DELAY:an entry waiting for a timer
475 NUD_PROBE:a cache entry that is currently reprobed
476 NUD_FAILED:an invalid cache entry
477 NUD_NOARP:a device with no destination cache
478 NUD_PERMANENT:a static entry
479 .TE
480 .IP
481 Valid
482 .I ndm_flags
483 are:
484 .TS
485 tab(:);
486 lb l.
487 NTF_PROXY:a proxy arp entry
488 NTF_ROUTER:an IPv6 router
489 .TE
490 .IP
491 .\" FIXME .
492 .\" document the members of the struct better
493 The
494 .I rtattr
495 struct has the following meanings for the
496 .I rta_type
497 field:
498 .TS
499 tab(:);
500 lb l.
501 NDA_UNSPEC:unknown type
502 NDA_DST:a neighbor cache n/w layer destination address
503 NDA_LLADDR:a neighbor cache link layer address
504 NDA_CACHEINFO:cache statistics
505 .TE
506 .IP
507 If the
508 .I rta_type
509 field is
510 .BR NDA_CACHEINFO ,
511 then a
512 .I struct nda_cacheinfo
513 header follows.
514 .TP
515 .B RTM_NEWRULE
516 .TQ
517 .B RTM_DELRULE
518 .TQ
519 .B RTM_GETRULE
520 Add, delete, or retrieve a routing rule.
521 Carries a
522 .I struct rtmsg
523 .TP
524 .B RTM_NEWQDISC
525 .TQ
526 .B RTM_DELQDISC
527 .TQ
528 .B RTM_GETQDISC
529 Add, remove, or get a queueing discipline.
530 The message contains a
531 .I struct tcmsg
532 and may be followed by a series of
533 attributes.
534 .IP
535 .EX
536 struct tcmsg {
537 unsigned char tcm_family;
538 int tcm_ifindex; /* interface index */
539 __u32 tcm_handle; /* Qdisc handle */
540 __u32 tcm_parent; /* Parent qdisc */
541 __u32 tcm_info;
542 };
543 .EE
544 .TS
545 tab(:);
546 c s s
547 lb2 l2 l.
548 Attributes
549 rta_type:Value type:Description
550 _
551 TCA_UNSPEC:-:unspecified
552 TCA_KIND:asciiz string:Name of queueing discipline
553 TCA_OPTIONS:byte sequence:Qdisc-specific options follow
554 TCA_STATS:struct tc_stats:Qdisc statistics
555 TCA_XSTATS:qdisc-specific:Module-specific statistics
556 TCA_RATE:struct tc_estimator:Rate limit
557 .TE
558 .IP
559 In addition, various other qdisc-module-specific attributes are allowed.
560 For more information see the appropriate include files.
561 .TP
562 .B RTM_NEWTCLASS
563 .TQ
564 .B RTM_DELTCLASS
565 .TQ
566 .B RTM_GETTCLASS
567 Add, remove, or get a traffic class.
568 These messages contain a
569 .I struct tcmsg
570 as described above.
571 .TP
572 .B RTM_NEWTFILTER
573 .TQ
574 .B RTM_DELTFILTER
575 .TQ
576 .B RTM_GETTFILTER
577 Add, remove, or receive information about a traffic filter.
578 These messages contain a
579 .I struct tcmsg
580 as described above.
581 .SH VERSIONS
582 .B rtnetlink
583 is a new feature of Linux 2.2.
584 .SH BUGS
585 This manual page is incomplete.
586 .SH SEE ALSO
587 .BR cmsg (3),
588 .BR rtnetlink (3),
589 .BR ip (7),
590 .BR netlink (7)