]>
Commit | Line | Data |
---|---|---|
fea681da MK |
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 | |
c13182ef | 9 | .\" help from Matthew Wilcox. |
fea681da | 10 | .\" $Id: rtnetlink.7,v 1.8 2000/01/22 01:55:04 freitag Exp $ |
69289f8a | 11 | .TH RTNETLINK 7 1999-04-30 "Linux" "Linux Programmer's Manual" |
fea681da MK |
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);" | |
fea681da | 24 | .SH DESCRIPTION |
c13182ef | 25 | Rtnetlink allows the kernel's routing tables to be read and altered. |
fea681da | 26 | It is used within the kernel to communicate between |
c13182ef | 27 | various subsystems, though this usage is not documented here, and for |
fea681da | 28 | communication with user-space programs. |
d9bfdb9c | 29 | Network routes, ip addresses, link parameters, neighbor setups, queueing |
fea681da MK |
30 | disciplines, traffic classes and packet classifiers may all be controlled |
31 | through | |
32 | .B NETLINK_ROUTE | |
c13182ef MK |
33 | sockets. |
34 | It is based on netlink messages, see | |
fea681da | 35 | .BR netlink (7) |
c13182ef MK |
36 | for more information. |
37 | .\" FIXME all these macros could be moved to rtnetlink(3) | |
051815fe | 38 | .SS "Routing Attributes" |
fea681da MK |
39 | Some rtnetlink messages have optional attributes after the initial header: |
40 | ||
41 | .nf | |
56185b42 | 42 | struct rtattr { |
87866492 MK |
43 | unsigned short rta_len; /* Length of option */ |
44 | unsigned short rta_type; /* Type of option */ | |
c13182ef | 45 | /* Data follows */ |
fea681da MK |
46 | }; |
47 | .fi | |
48 | ||
c13182ef | 49 | These attributes should be only manipulated using the RTA_* macros |
9fdfa163 | 50 | or libnetlink, see |
fea681da | 51 | .BR rtnetlink (3). |
051815fe | 52 | .SS Messages |
fea681da MK |
53 | Rtnetlink consists of these message types |
54 | (in addition to standard netlink messages): | |
55 | .TP | |
56 | .BR RTM_NEWLINK ", " RTM_DELLINK ", " RTM_GETLINK | |
c13182ef | 57 | Create, remove or get information about a specific network interface. |
fea681da MK |
58 | These messages contain an |
59 | .B ifinfomsg | |
60 | structure followed by a series of | |
61 | .B rtattr | |
62 | structures. | |
63 | ||
64 | .nf | |
56185b42 | 65 | struct ifinfomsg { |
87866492 | 66 | unsigned char ifi_family; /* AF_UNSPEC */ |
c13182ef | 67 | unsigned short ifi_type; /* Device type */ |
87866492 MK |
68 | int ifi_index; /* Interface index */ |
69 | unsigned int ifi_flags; /* Device flags */ | |
70 | unsigned int ifi_change; /* change mask */ | |
fea681da MK |
71 | }; |
72 | .fi | |
73 | ||
a749f870 | 74 | .\" FIXME ifi_type |
c13182ef | 75 | .B ifi_flags |
fea681da | 76 | contains the device flags, see |
a7e1c01a | 77 | .BR netdevice (7); |
fea681da MK |
78 | .B ifi_index |
79 | is the unique interface index, | |
80 | .B ifi_change | |
c13182ef | 81 | is reserved for future use and should be always set to 0xFFFFFFFF. |
fea681da MK |
82 | .TS |
83 | tab(:); | |
84 | c | |
85 | l l l. | |
86 | Routing attributes | |
87 | rta_type:value type:description | |
88 | _ | |
89 | IFLA_UNSPEC:-:unspecified. | |
c13182ef | 90 | IFLA_ADDRESS:hardware address:interface L2 address |
fea681da MK |
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{ | |
be1d83d4 | 97 | see below |
fea681da MK |
98 | T}:Interface Statistics. |
99 | .TE | |
be1d83d4 MK |
100 | .sp |
101 | The value type for IFLA_STATS is \fIstruct net_device_stats\fP. | |
87866492 MK |
102 | .TP |
103 | .BR RTM_NEWADDR ", " RTM_DELADDR ", " RTM_GETADDR | |
c13182ef MK |
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 | |
fea681da MK |
111 | .B ifaddrmsg |
112 | structure, optionally followed by | |
113 | .B rtaddr | |
114 | routing attributes. | |
115 | ||
116 | .nf | |
56185b42 | 117 | struct ifaddrmsg { |
87866492 MK |
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 */ | |
fea681da MK |
123 | }; |
124 | .fi | |
125 | ||
126 | .B ifa_family | |
c13182ef | 127 | is the address family type (currently |
fea681da MK |
128 | .B AF_INET |
129 | or | |
c13182ef | 130 | .BR AF_INET6 ), |
fea681da | 131 | .B ifa_prefixlen |
c13182ef MK |
132 | is the length of the address mask of the address if defined for the |
133 | family (like for IPv4), | |
fea681da MK |
134 | .B ifa_scope |
135 | is the address scope, | |
136 | .B ifa_index | |
c13182ef | 137 | is the interface index of the interface the address is associated with. |
fea681da MK |
138 | .B ifa_flags |
139 | is a flag word of | |
140 | .B IFA_F_SECONDARY | |
c13182ef | 141 | for secondary address (old alias interface), |
fea681da MK |
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 | |
c13182ef | 158 | IFA_CACHEINFO:struct ifa_cacheinfo:Address information. |
fea681da | 159 | .TE |
a749f870 | 160 | .\" FIXME struct ifa_cacheinfo |
87866492 MK |
161 | .TP |
162 | .BR RTM_NEWROUTE ", " RTM_DELROUTE ", " RTM_GETROUTE | |
fea681da MK |
163 | Create, remove or receive information about a network route. |
164 | These messages contain an | |
165 | .B rtmsg | |
c13182ef | 166 | structure with an optional sequence of |
fea681da | 167 | .B rtattr |
c13182ef MK |
168 | structures following. |
169 | For | |
fea681da | 170 | .B RTM_GETROUTE |
c13182ef MK |
171 | setting |
172 | .B rtm_dst_len | |
173 | and | |
174 | .B rtm_src_len | |
fea681da | 175 | to 0 means you get all entries for the specified routing table. |
c13182ef MK |
176 | For the other fields except |
177 | .B rtm_table | |
178 | and | |
fea681da MK |
179 | .B rtm_protocol |
180 | 0 is the wildcard. | |
181 | ||
182 | .nf | |
56185b42 | 183 | struct rtmsg { |
87866492 MK |
184 | unsigned char rtm_family; /* Address family of route */ |
185 | unsigned char rtm_dst_len; /* Length of source */ | |
c13182ef | 186 | unsigned char rtm_src_len; /* Length of destination */ |
87866492 | 187 | unsigned char rtm_tos; /* TOS filter */ |
fea681da | 188 | |
87866492 MK |
189 | unsigned char rtm_table; /* Routing table ID */ |
190 | unsigned char rtm_protocol; /* Routing protocol; see below */ | |
c13182ef | 191 | unsigned char rtm_scope; /* See below */ |
87866492 | 192 | unsigned char rtm_type; /* See below */ |
fea681da | 193 | |
87866492 | 194 | unsigned int rtm_flags; |
fea681da MK |
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 | |
9fdfa163 | 240 | are not interpreted by the kernel, they are just for user information. |
c13182ef MK |
241 | They may be used to tag the source of a routing information or to |
242 | distinguish between multiple routing daemons. | |
243 | See | |
bd12ab88 | 244 | .IR <linux/rtnetlink.h> |
c13182ef | 245 | for the routing daemon identifiers which are already assigned. |
fea681da | 246 | |
c13182ef MK |
247 | .B rtm_scope |
248 | is the distance to the destination: | |
fea681da MK |
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 | ||
9fdfa163 | 294 | The user may assign arbitrary values between |
fea681da MK |
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! | |
87866492 MK |
322 | .TP |
323 | .BR RTM_NEWNEIGH ", " RTM_DELNEIGH ", " RTM_GETNEIGH | |
d9bfdb9c | 324 | Add, remove or receive information about a neighbor table |
c13182ef MK |
325 | entry (e.g. an ARP entry). |
326 | The message contains an | |
fea681da MK |
327 | .B ndmsg |
328 | structure. | |
329 | ||
330 | .nf | |
56185b42 | 331 | struct ndmsg { |
87866492 MK |
332 | unsigned char ndm_family; |
333 | int ndm_ifindex; /* Interface index */ | |
c13182ef | 334 | __u16 ndm_state; /* State */ |
87866492 | 335 | __u8 ndm_flags; /* Flags */ |
c13182ef | 336 | __u8 ndm_type; |
fea681da MK |
337 | }; |
338 | ||
56185b42 | 339 | struct nda_cacheinfo { |
87866492 MK |
340 | __u32 ndm_confirmed; |
341 | __u32 ndm_used; | |
342 | __u32 ndm_updated; | |
343 | __u32 ndm_refcnt; | |
fea681da MK |
344 | }; |
345 | .fi | |
346 | ||
347 | .B ndm_state | |
c13182ef | 348 | is a bitmask of the following states: |
fea681da MK |
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 | |
d9bfdb9c MK |
386 | NDA_DST:a neighbor cache n/w layer destination address |
387 | NDA_LLADDR:a neighbor cache link layer address | |
fea681da MK |
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 | |
8478ee02 | 396 | .I struct nda_cacheinfo |
fea681da MK |
397 | header follows |
398 | .TP | |
399 | .BR RTM_NEWRULE ", " RTM_DELRULE ", " RTM_GETRULE | |
c13182ef MK |
400 | Add, delete or retrieve a routing rule. |
401 | Carries a | |
8478ee02 | 402 | .I struct rtmsg |
fea681da MK |
403 | .TP |
404 | .BR RTM_NEWQDISC ", " RTM_DELQDISC ", " RTM_GETQDISC | |
c13182ef MK |
405 | Add, remove or get a queueing discipline. |
406 | The message contains a | |
8478ee02 | 407 | .I struct tcmsg |
fea681da MK |
408 | and may be followed by a series of |
409 | attributes. | |
410 | ||
411 | .nf | |
56185b42 | 412 | struct tcmsg { |
87866492 MK |
413 | unsigned char tcm_family; |
414 | int tcm_ifindex; /* interface index */ | |
c13182ef | 415 | __u32 tcm_handle; /* Qdisc handle */ |
87866492 MK |
416 | __u32 tcm_parent; /* Parent qdisc */ |
417 | __u32 tcm_info; | |
fea681da MK |
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 | |
c13182ef MK |
440 | Add, remove or get a traffic class. |
441 | These messages contain a | |
8478ee02 | 442 | .I struct tcmsg |
fea681da MK |
443 | as described above. |
444 | .TP | |
445 | .BR RTM_NEWTFILTER ", " RTM_DELTFILTER ", " RTM_GETTFILTER | |
c13182ef MK |
446 | Add, remove or receive information about a traffic filter. |
447 | These messages contain a | |
8478ee02 | 448 | .I struct tcmsg |
fea681da MK |
449 | as described above. |
450 | .SH VERSIONS | |
c13182ef | 451 | .B rtnetlink |
fea681da MK |
452 | is a new feature of Linux 2.2. |
453 | .SH BUGS | |
27fcc638 | 454 | This manual page is incomplete. |
fea681da MK |
455 | .SH "SEE ALSO" |
456 | .BR cmsg (3), | |
457 | .BR rtnetlink (3), | |
458 | .BR ip (7), | |
459 | .BR netlink (7) |