guile-netlink.texi
1 | \input texinfo |
2 | @setfilename guile-netlink.info |
3 | @documentencoding UTF-8 |
4 | @settitle guile-netlink |
5 | |
6 | @include version.texi |
7 | |
8 | @copying |
9 | Copyright @copyright{} 2020 Julien Lepiller |
10 | |
11 | @quotation |
12 | Permission is granted to copy, distribute and/or modify this document |
13 | under the terms of the GNU Free Documentation License, Version 1.3 or |
14 | any later version published by the Free Software Foundation; with no |
15 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A |
16 | copy of the license is included in the section entitled ``GNU Free |
17 | Documentation License''. |
18 | @end quotation |
19 | @end copying |
20 | |
21 | @titlepage |
22 | @end titlepage |
23 | |
24 | @contents |
25 | |
26 | @node Top |
27 | @top guile-netlink |
28 | |
29 | This document describes guile-netlink version @value{VERSION}, a guile |
30 | implementation of the netlink protocol. |
31 | |
32 | @menu |
33 | * Introduction:: What is netlink? |
34 | * API Reference:: Description of the library interface. |
35 | |
36 | @detailmenu |
37 | --- The Detailed Node Listing --- |
38 | |
39 | API Reference |
40 | |
41 | * Common API:: Common functions and data types for defining netlink |
42 | protocols. |
43 | * Netlink API:: Common structures and data types for every protocols. |
44 | * Rtnetlink API:: The ROUTE_NETLINK protocol. |
45 | |
46 | @end detailmenu |
47 | @end menu |
48 | |
49 | @node Introduction |
50 | @chapter Introduction |
51 | |
52 | Netlink is an inter-process communication protocol that can be used for |
53 | communication between processes, or with the kernel. It is implemented by |
54 | Linux. |
55 | |
56 | Many protocols exist on top of Netlink. The most famous are used to configure |
57 | network-related functions in the kernel, such as firewall, route table or |
58 | IP addresses of interfaces. |
59 | |
60 | This library implements the low-level bits of the code by providing data |
61 | structures that are close to their C counterpart, and basic procedures to |
62 | initiate communication. |
63 | |
64 | @node API Reference |
65 | @chapter API Reference |
66 | |
67 | @node Common API |
68 | @section Common API |
69 | |
70 | Guile-netlink implements a common API for expressing other protocols. This |
71 | section describes how to use this API to augment guile-netlink with additional |
72 | protocols. |
73 | |
74 | @node Data Types |
75 | @subsection Data Types |
76 | |
77 | Guile-netlink defines data types that are used in the various Netlink protocols. |
78 | We need to be able to serialize and deserialize data that guile-netlink |
79 | understands, but we also want to let users of guile-netlink extend this process |
80 | easily. This need has lead to the creating of the following data structure, |
81 | defined in @code{(netlink data}). |
82 | |
83 | @deffn {Datatype} nl-data |
84 | |
85 | @table @asis |
86 | @item @code{data} |
87 | The data that is held by this record. |
88 | |
89 | @item @code{size-proc} |
90 | A procedure that takes a data (of the same type as the data recorded in the |
91 | @code{data} field) and returns the size of its serialization. |
92 | |
93 | @item @code{serialization-proc} |
94 | A procedure that takes a data (of the same type as the data recorded in the |
95 | @code{data} field), the position at which to start serializing, and a |
96 | bytevector in which to serialize. This procedure should modify the bytevector |
97 | and its return value is ignored. |
98 | |
99 | @end table |
100 | @end deffn |
101 | |
102 | The module also defines the following function, that takes a @code{nl-data} |
103 | structure and provides its serialization in a bytevector: |
104 | |
105 | @deffn {Scheme Procedure} serialize @var{data} @var{pos} @var{bv} |
106 | Takes a @code{nl-data} structure as @var{data}, a position @var{pos} in |
107 | the bytevector @var{bv}, and returns an unspecified value. |
108 | |
109 | This function updates the bytevector and adds the serialization of @var{data} |
110 | into @var{bv} at @var{pos}. |
111 | @end deffn |
112 | |
113 | By providing a @code{nl-data} structure, we defer the knowledge of how to |
114 | serialize the data to the structure itself, instead of the @code{serialize} |
115 | function. This allows for more flexibility and extensibility, as the user |
116 | of the procedure can pass any kind of data, even if it is not yet supported by |
117 | guile-netlink. |
118 | |
119 | Similarly, we need to be able to deserialize netlink answers into a data |
120 | structure. To do so, we also defer the knowledge of the datastructure to |
121 | deserialize to, to a decoder structure that is passed to the deserialization |
122 | procedure. @code{(netlink data)} also defines the following procedures to |
123 | deserialize data: |
124 | |
125 | @deffn {Scheme Procedure} deserialize @var{type} @var{decoder} @var{bv} @var{pos} |
126 | Takes a bytevector @var{bv} and starts deserializing the data starting at |
127 | position @var{pos}. To do so, it uses the @var{type} variable as the lookup |
128 | key in the @var{decoder}. @var{type} is a symbol that represents the type of |
129 | data to deserialize to. |
130 | |
131 | The decoder is a structure that associates each known type to its deserializer |
132 | (a function that takes a decoder, a bytevector and a position and returns some |
133 | data) and an alist that associates a type (an integer, as returned by the |
134 | protocol in use) to the proper decoder of that type. |
135 | @end deffn |
136 | |
137 | @deffn {Scheme Procedure} get-current-deserialize @var{decoder} @var{current-type} |
138 | Takes a decoder and a type, and returns the deserialization procedure associated |
139 | with the type (a symbol) in @var{decoder}. |
140 | @end deffn |
141 | |
142 | @deffn {Scheme Procedure} get-next-deserialize @var{decoder} @var{current-type} @ |
143 | @var{target-type} |
144 | Takes a decoder, a type (a symbol that represents the type of data being |
145 | deserialized) and another type (an integer as returned by the protocol), and |
146 | returns the deserialization procedure needed to continue decoding the data |
147 | associated with the currently being deserialized data. |
148 | |
149 | For example, when decoding an answer in the netlink protocol, we first deserialize |
150 | the header into a @code{message} structure. That header contains a type field |
151 | that contains an integer constant representing the type of data of the body. |
152 | Similarly, when deserializing a routing attribute in the rtnetlink protocol, |
153 | we first find a header of the attribute that defines an integer constant |
154 | corresponding to the type of attribute in the body. |
155 | |
156 | By knowing the context in which the type is declared, this procedure can return |
157 | the correct deserializing procedure. For instance, when deserializing a |
158 | @code{message}, type @code{16} means @code{RTM_NEWLINK} in the rtnetlink |
159 | protocol, whereas it means @code{IFLA_OPERSTATE} when deserializing a |
160 | @code{route-attribute}. |
161 | @end deffn |
162 | |
163 | guile-netlink provides the following default decoder for the rtnetlink |
164 | protocol in @code{(netlink deserialize)}: |
165 | |
166 | @deffn {Scheme Variable} %default-route-decoder |
167 | Contains the default decoder for the NETLINK_ROUTE protocol. |
168 | @end deffn |
169 | |
170 | For convenience, guile-netlink defines the following structures that can be used |
171 | to create a custom decoder. |
172 | |
173 | @deffn {Scheme Variable} %default-message-decoder |
174 | Contains the default association list for the common message types of netlink, |
175 | associating each of them to a deserialization procedure. |
176 | @end deffn |
177 | |
178 | @deffn {Scheme Procedure} default-route-attr-decoder @var{deserialize-addr} |
179 | Creates the default association list for a route protocol, given the specified |
180 | address deserializer. This is useful because the @code{IFA_ADDRESS}, |
181 | @code{IFA_BROADCAST}, etc, contain a different type of address depending on |
182 | the message type or its header. This is defined an @code{(netlink route attrs)} |
183 | and used by the following variables: |
184 | @end deffn |
185 | |
186 | @deffn {Scheme Variable} %default-route-link-attr-decoder |
187 | Contains the default association list for the known types of routing attributes |
188 | for link messages. This list is defined in @code{(netlink route attrs)}. |
189 | @end deffn |
190 | |
191 | @node Constants |
192 | @subsection Constants |
193 | |
194 | Guile-netlink defines constants used by the Netlink protocols in the |
195 | @code{(netlink constant)} module. The constants are the ones present in the |
196 | kernel and are too numerous to list here. Please see the source for the |
197 | complete list. |
198 | |
199 | The module also defines the following macro: |
200 | |
201 | @deffn {Scheme Macro} define-enum @var{integer->symbol} @var{name-spec} ... |
202 | This macros defines an enumeration. @var{integer->symbol} is the name of |
203 | a procedure that is publicly defined, that takes an integer and returns the |
204 | associated symbol in the enumeration. |
205 | |
206 | The macro also publicly defines variables whose names are in @var{name-spec} |
207 | to an integer. |
208 | |
209 | A @var{name-spec} is either a single name, and the associated value is 0 for |
210 | the first @var{name-spec}, or one more than the previous @var{name-spec}. |
211 | It can also be a pair of a name and an integer, in which case the associated |
212 | value is that integer. For instance: |
213 | |
214 | @example |
215 | (define-enum get-foo FOO0 FOO1 (FOO10 10) FOO11 FOO12) |
216 | (get-foo 9) -> #<unspecified> |
217 | (get-foo 0) -> FOO0 |
218 | FOO11 -> 11 |
219 | @end example |
220 | @end deffn |
221 | |
222 | @node Netlink Connections |
223 | @subsection Netlink Connections |
224 | |
225 | The @code{(netlink connection)} module defines the following procedures, used |
226 | to connect and communicate with another process or the kernel using a netlink |
227 | socket. |
228 | |
229 | @deffn {Scheme Procedure} get-addr @var{family} @var{pid} @var{groups} |
230 | Return a bytevector that represents a netlink address. @var{family} |
231 | should be @code{AF_NETLINK}, @var{pid} is the PID of the process with which |
232 | to communicate or 0 for the kernel. @var{groups} is an integer representing |
233 | the set of broadcast groups to which the connection subscribes. |
234 | @end deffn |
235 | |
236 | @deffn {Scheme Procedure} connect @var{proto} @var{addr} |
237 | Creates a netlink socket for @var{proto} and binds it to @var{addr}. |
238 | |
239 | @var{proto} is the integer representing the protocol. For instance, rtnetlink |
240 | can be selected by usin @code{NETLINK_ROUTE} (defined in |
241 | @code{(netlink constant)}). |
242 | |
243 | @var{addr} is a bytevector, as returned by @code{get-addr}. |
244 | @end deffn |
245 | |
246 | @deffn {Scheme Procedure} connect-route [#:groups @code{0}] |
247 | This procedure is a wrapper for @code{connect} that creates a socket for the |
248 | rtnetlink protocol, binds it to the kernel and returns it. By passing the |
249 | optional @var{groups} keyword, you can select broadcast groups to subscribe to. |
250 | @end deffn |
251 | |
252 | @deffn {Scheme Procedure} close-socket @var{socket} |
253 | Closes a netlink socket. The socket cannot be used afterwards. |
254 | @end deffn |
255 | |
256 | @deffn {Scheme Procedure} send-msg @var{msg} @var{sock} [#:@var{addr}] |
257 | Send @var{msg} (it must be of type message, @xref{Netlink Headers}) to |
258 | @var{addr} using @var{sock}. If not passed, @var{addr} is the address of |
259 | the kernel. |
260 | @end deffn |
261 | |
262 | @deffn {Scheme Procedure} receive-msg @var{sock} [#:@var{addr}] |
263 | Receives a message from @var{sock} from @var{addr}. This procedure is blocking. |
264 | If not passed, @var{addr} defaults to the address of the kernel. This |
265 | procedure returns the message as a bytevector, that you can deserialize with |
266 | @code{deserialize} (@xref{Data Types}) |
267 | @end deffn |
268 | |
269 | @deffn {Scheme Procedure} receive-and-decode-msg @var{sock} @var{decoder} @ |
270 | [#:@var{addr}] |
271 | Receives one or more messages from @var{sock} from @var{addr}. this procedure |
272 | is blocking. If not passed, @var{addr} defaults to the address of the kernel. |
273 | This procedure returns a list of messages that were decoded using @var{decoder}. |
274 | |
275 | When the answer has the @code{NLM_F_MULTI} flag, this procedure decodes the next |
276 | message, until it receives a @code{NLMSG_DONE} message. It returns the list |
277 | of every netlink messages it received, including the @code{NLMSG_DONE}. |
278 | @end deffn |
279 | |
280 | @node Netlink API |
281 | @section Netlink API |
282 | |
283 | This section introduces the data structures used for all the netlink protocols. |
284 | First, we introduce the structure of a netlink message, then we present the |
285 | standard types of netlink messages, that can be used with every protocol. |
286 | |
287 | @node Netlink Headers |
288 | @subsection Netlink Headers |
289 | |
290 | The @code{(netlink message)} module defines the message structure that contains |
291 | a netlink message. It is composed of a header and a body, and is the data |
292 | structure to pass to @code{send-msg} (@xref{Netlink Connections}). |
293 | |
294 | This module defines the following data structure: |
295 | |
296 | @deffn {Datatype} message |
297 | @table @asis |
298 | @item @code{type} |
299 | The type of data in the body of the message. For instance, @code{RTM_GETLINK}. |
300 | |
301 | @item @code{flags} |
302 | The set of flags that are set in the header. For instance, |
303 | @code{(logior NLM_F_REQUEST NLM_F_DUMP)}. |
304 | |
305 | @item @code{seq} |
306 | The sequence number of the message. If this message is an answer to a request, |
307 | it must keep the same sequence number. Otherwise, you must generate a new and |
308 | unique sequence number, to track the answers. |
309 | |
310 | @item @code{pid} |
311 | The PID of the receiving process, or 0 for the kernel. |
312 | |
313 | @item @code{data} |
314 | The actual body, as an @code{nl-data} structure. |
315 | |
316 | @end table |
317 | @end deffn |
318 | |
319 | @node Standard Message Types |
320 | @subsection Standard Message Types |
321 | |
322 | The @code{(netlink standard)} module defines the set of standard message types |
323 | and their data type. |
324 | |
325 | @deffn {Datatype} error-message |
326 | @table @asis |
327 | @item @code{err} |
328 | The error code, as a negative number. |
329 | |
330 | @item @code{hdr} |
331 | The message on which this error applies. |
332 | |
333 | @end table |
334 | |
335 | @deffn {Scheme Variable} no-data |
336 | This variable defines the absence of data. This is useful when a structure |
337 | is expecting a body part, but the protocol specifically defines that it should |
338 | not take any data in some cases. For instance, a @code{NLMSG_NOOP} message |
339 | takes no data, so the @code{data} field of the message will contain this |
340 | @code{no-data} value. |
341 | @end deffn |
342 | |
343 | @end deffn |
344 | |
345 | @node Rtnetlink API |
346 | @section Rtnetlink API |
347 | @cindex rtnetlink |
348 | @cindex ROUTE_NETLINK |
349 | |
350 | This section describes the support for rtnetlink in guile-netlink. Rtnetlink |
351 | is the protocol responsible for everything related to network routing. It |
352 | allows you to manage links, addresses, routing tables, neighbor chaces, |
353 | routing rules, queueing disciplines, traffic classes, traffic filters and |
354 | more. |
355 | |
356 | @node Routing Attributes |
357 | @subsection Routing Attributes |
358 | |
359 | The @code{(netlink route attrs)} module defines the following data types: |
360 | |
361 | @deffn {Datatype} route-attr |
362 | This defines a header structure for the attribute, as well as its body. |
363 | |
364 | @table @asis |
365 | @item @code{type} |
366 | This is the type of the attribute, for instance @code{IFLA_ADDRESS}. |
367 | |
368 | @item @code{data} |
369 | This is the body of the attribute, ie.@: its value. |
370 | @end table |
371 | @end deffn |
372 | |
373 | The module also defines additional data types that are not represented as |
374 | a record, but by a simple type. For each of the following types, there is |
375 | a @code{make-*-route-attr} procedure to produce a @code{nl-data} value |
376 | for this type. There is also @code{deserialize-route-attr-data-*} procedure |
377 | to deserialize a value of this type. |
378 | |
379 | @table @asis |
380 | @item @code{u8} |
381 | A one-byte unsigned integer |
382 | @item @code{u16} |
383 | A two-bytes unsigned integer |
384 | @item @code{u32} |
385 | A four-bytes unsigned integer |
386 | @item @code{s32} |
387 | A four-bytes signed integer |
388 | @item @code{string} |
389 | A string |
390 | @item @code{ethernet} |
391 | An ethernet address. Its value is a string that represents that address, |
392 | for instnace @code{"01:23:45:67:89:ab"} |
393 | @item @code{ipv4} |
394 | An IPv4 address. Its value is a string that represents that address, |
395 | for instnace @code{"192.0.2.152"} |
396 | @item @code{ipv6} |
397 | An IPv6 address. Its value is a string that represents that address, |
398 | for instnace @code{"2001:db8::0123:4567:89ab:cdef"} |
399 | @item @code{bv} |
400 | A bytevector. This is used by default when the type is not supported. |
401 | @end table |
402 | |
403 | @node Link Messages |
404 | @subsection Link Messages |
405 | |
406 | The @code{(netlink route link)} package defines the following data type: |
407 | |
408 | @deffn {Datatype} link-message |
409 | This datatype represents a link message with its routing attributes. This type |
410 | of message is expected when using the @var{RTM_*LINK} message types. |
411 | |
412 | @table @asis |
413 | @item @code{family} |
414 | The network family, defined as @code{AF_UNSPEC} in the rtnetlink documentation, |
415 | although it holds different values in practice. |
416 | |
417 | @item @code{type} |
418 | The device type. |
419 | |
420 | @item @code{index} |
421 | The index of the device. This is used to select a specific device by its index, |
422 | or 0 to not filter by device index. |
423 | |
424 | @item @code{flags} |
425 | The device flags. See @code{man 7 netdevices} for a list. |
426 | |
427 | @item @code{attrs} |
428 | A list of attributes. This field must contain a list of @code{nl-data} |
429 | structures, not a structure by itself. |
430 | @end table |
431 | @end deffn |
432 | |
433 | @node Address Messages |
434 | @subsection Address Messages |
435 | |
436 | The @code{(netlink route addr)} package defines the following data type: |
437 | |
438 | @deffn {Datatype} addr-message |
439 | This datatype represents an address message with its routing attributes. This |
440 | type of message is expected when using the @var{RTM_*ADDR} message types. |
441 | |
442 | @table @asis |
443 | @item @code{family} |
444 | The network family, either @code{AF_INET} for IPv4 addresses, or @code{AF_INET6} |
445 | for IPv6 addresses. |
446 | |
447 | @item @code{prefix-len} |
448 | The prefix length, i.e.@: the length of the prefix mask, in bits, if defined |
449 | for the address family. |
450 | |
451 | @item @code{flags} |
452 | Address flags. This can be a flag word of @code{IFA_F_SECONDARY} for secondary |
453 | address (old alias interface), @code{IFA_F_PERMANENT} for a permanent |
454 | address set by the user and other undocumented flags. |
455 | |
456 | @item @code{scope} |
457 | The address scope. |
458 | |
459 | @item @code{index} |
460 | The index of the device this address is for. |
461 | |
462 | @item @code{attrs} |
463 | A list of attributes. This field must contain a list of @code{nl-data} |
464 | structures, not a structure by itself. |
465 | @end table |
466 | @end deffn |
467 | |
468 | @bye |
469 |