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 | * IP Library:: High-level functions for network devices. |
36 | |
37 | * Concept Index:: Concepts. |
38 | * Programming Index:: Data types, procedures, and variables. |
39 | |
40 | @detailmenu |
41 | --- The Detailed Node Listing --- |
42 | |
43 | API Reference |
44 | |
45 | * Common API:: Common functions and data types for defining netlink |
46 | protocols. |
47 | * Netlink API:: Common structures and data types for every protocols. |
48 | * Rtnetlink API:: The ROUTE_NETLINK protocol. |
49 | |
50 | IP Library |
51 | |
52 | * Link:: Actions on network links. |
53 | * Addr:: Actions on network addresses. |
54 | * Route:: Actions on network routes. |
55 | |
56 | @end detailmenu |
57 | @end menu |
58 | |
59 | @node Introduction |
60 | @chapter Introduction |
61 | |
62 | Netlink is an inter-process communication protocol that can be used for |
63 | communication between processes, or with the kernel. It is implemented by |
64 | Linux. |
65 | |
66 | Many protocols exist on top of Netlink. The most famous are used to configure |
67 | network-related functions in the kernel, such as firewall, route table or |
68 | IP addresses of interfaces. |
69 | |
70 | This library implements the low-level bits of the code by providing data |
71 | structures that are close to their C counterpart, and basic procedures to |
72 | initiate communication. |
73 | |
74 | @node API Reference |
75 | @chapter API Reference |
76 | |
77 | @node Common API |
78 | @section Common API |
79 | |
80 | Guile-netlink implements a common API for expressing other protocols. This |
81 | section describes how to use this API to augment guile-netlink with additional |
82 | protocols. |
83 | |
84 | @node Data Types |
85 | @subsection Data Types |
86 | |
87 | Guile-netlink defines data types that are used in the various Netlink protocols. |
88 | We need to be able to serialize and deserialize data that guile-netlink |
89 | understands, but we also want to let users of guile-netlink extend this process |
90 | easily. This need has lead to the creating of the following data structure, |
91 | defined in @code{(netlink data}). |
92 | |
93 | @deffn {Datatype} nl-data |
94 | |
95 | @table @asis |
96 | @item @code{data} |
97 | The data that is held by this record. |
98 | |
99 | @item @code{size-proc} |
100 | A procedure that takes a data (of the same type as the data recorded in the |
101 | @code{data} field) and returns the size of its serialization. |
102 | |
103 | @item @code{serialization-proc} |
104 | A procedure that takes a data (of the same type as the data recorded in the |
105 | @code{data} field), the position at which to start serializing, and a |
106 | bytevector in which to serialize. This procedure should modify the bytevector |
107 | and its return value is ignored. |
108 | |
109 | @end table |
110 | @end deffn |
111 | |
112 | The module also defines the following function, that takes a @code{nl-data} |
113 | structure and provides its serialization in a bytevector: |
114 | |
115 | @deffn {Scheme Procedure} serialize @var{data} @var{pos} @var{bv} |
116 | Takes a @code{nl-data} structure as @var{data}, a position @var{pos} in |
117 | the bytevector @var{bv}, and returns an unspecified value. |
118 | |
119 | This function updates the bytevector and adds the serialization of @var{data} |
120 | into @var{bv} at @var{pos}. |
121 | @end deffn |
122 | |
123 | By providing a @code{nl-data} structure, we defer the knowledge of how to |
124 | serialize the data to the structure itself, instead of the @code{serialize} |
125 | function. This allows for more flexibility and extensibility, as the user |
126 | of the procedure can pass any kind of data, even if it is not yet supported by |
127 | guile-netlink. |
128 | |
129 | Similarly, we need to be able to deserialize netlink answers into a data |
130 | structure. To do so, we also defer the knowledge of the datastructure to |
131 | deserialize to, to a decoder structure that is passed to the deserialization |
132 | procedure. @code{(netlink data)} also defines the following procedures to |
133 | deserialize data: |
134 | |
135 | @deffn {Scheme Procedure} deserialize @var{type} @var{decoder} @var{bv} @var{pos} |
136 | Takes a bytevector @var{bv} and starts deserializing the data starting at |
137 | position @var{pos}. To do so, it uses the @var{type} variable as the lookup |
138 | key in the @var{decoder}. @var{type} is a symbol that represents the type of |
139 | data to deserialize to. |
140 | |
141 | The decoder is a structure that associates each known type to its deserializer |
142 | (a function that takes a decoder, a bytevector and a position and returns some |
143 | data) and an alist that associates a type (an integer, as returned by the |
144 | protocol in use) to the proper decoder of that type. |
145 | @end deffn |
146 | |
147 | @deffn {Scheme Procedure} get-current-deserialize @var{decoder} @var{current-type} |
148 | Takes a decoder and a type, and returns the deserialization procedure associated |
149 | with the type (a symbol) in @var{decoder}. |
150 | @end deffn |
151 | |
152 | @deffn {Scheme Procedure} get-next-deserialize @var{decoder} @var{current-type} @ |
153 | @var{target-type} |
154 | Takes a decoder, a type (a symbol that represents the type of data being |
155 | deserialized) and another type (an integer as returned by the protocol), and |
156 | returns the deserialization procedure needed to continue decoding the data |
157 | associated with the currently being deserialized data. |
158 | |
159 | For example, when decoding an answer in the netlink protocol, we first deserialize |
160 | the header into a @code{message} structure. That header contains a type field |
161 | that contains an integer constant representing the type of data of the body. |
162 | Similarly, when deserializing a routing attribute in the rtnetlink protocol, |
163 | we first find a header of the attribute that defines an integer constant |
164 | corresponding to the type of attribute in the body. |
165 | |
166 | By knowing the context in which the type is declared, this procedure can return |
167 | the correct deserializing procedure. For instance, when deserializing a |
168 | @code{message}, type @code{16} means @code{RTM_NEWLINK} in the rtnetlink |
169 | protocol, whereas it means @code{IFLA_OPERSTATE} when deserializing a |
170 | @code{route-attribute}. |
171 | @end deffn |
172 | |
173 | guile-netlink provides the following default decoder for the rtnetlink |
174 | protocol in @code{(netlink deserialize)}: |
175 | |
176 | @deffn {Scheme Variable} %default-route-decoder |
177 | Contains the default decoder for the NETLINK_ROUTE protocol. |
178 | @end deffn |
179 | |
180 | For convenience, guile-netlink defines the following structures that can be used |
181 | to create a custom decoder. |
182 | |
183 | @deffn {Scheme Variable} %default-message-decoder |
184 | Contains the default association list for the common message types of netlink, |
185 | associating each of them to a deserialization procedure. |
186 | @end deffn |
187 | |
188 | @deffn {Scheme Procedure} default-route-attr-decoder @var{deserialize-addr} |
189 | Creates the default association list for a route protocol, given the specified |
190 | address deserializer. This is useful because the @code{IFA_ADDRESS}, |
191 | @code{IFA_BROADCAST}, etc, contain a different type of address depending on |
192 | the message type or its header. This is defined an @code{(netlink route attrs)} |
193 | and used by the following variables: |
194 | @end deffn |
195 | |
196 | @deffn {Scheme Variable} %default-route-link-attr-decoder |
197 | Contains the default association list for the known types of routing attributes |
198 | for link messages. This list is defined in @code{(netlink route attrs)}. |
199 | @end deffn |
200 | |
201 | @node Constants |
202 | @subsection Constants |
203 | |
204 | Guile-netlink defines constants used by the Netlink protocols in the |
205 | @code{(netlink constant)} module. The constants are the ones present in the |
206 | kernel and are too numerous to list here. Please see the source for the |
207 | complete list. |
208 | |
209 | The module also defines the following macro: |
210 | |
211 | @deffn {Scheme Macro} define-enum @var{integer->symbol} @var{name-spec} ... |
212 | This macros defines an enumeration. @var{integer->symbol} is the name of |
213 | a procedure that is publicly defined, that takes an integer and returns the |
214 | associated symbol in the enumeration. |
215 | |
216 | The macro also publicly defines variables whose names are in @var{name-spec} |
217 | to an integer. |
218 | |
219 | A @var{name-spec} is either a single name, and the associated value is 0 for |
220 | the first @var{name-spec}, or one more than the previous @var{name-spec}. |
221 | It can also be a pair of a name and an integer, in which case the associated |
222 | value is that integer. For instance: |
223 | |
224 | @example |
225 | (define-enum get-foo FOO0 FOO1 (FOO10 10) FOO11 FOO12) |
226 | (get-foo 9) -> #<unspecified> |
227 | (get-foo 0) -> FOO0 |
228 | FOO11 -> 11 |
229 | @end example |
230 | @end deffn |
231 | |
232 | @node Netlink Connections |
233 | @subsection Netlink Connections |
234 | |
235 | The @code{(netlink connection)} module defines the following procedures, used |
236 | to connect and communicate with another process or the kernel using a netlink |
237 | socket. |
238 | |
239 | @deffn {Scheme Procedure} get-addr @var{family} @var{pid} @var{groups} |
240 | Return a bytevector that represents a netlink address. @var{family} |
241 | should be @code{AF_NETLINK}, @var{pid} is the PID of the process with which |
242 | to communicate or 0 for the kernel. @var{groups} is an integer representing |
243 | the set of broadcast groups to which the connection subscribes. |
244 | @end deffn |
245 | |
246 | @cindex non-blocking socket |
247 | @deffn {Scheme Procedure} connect @var{proto} @var{addr} [#:flags 0] |
248 | Creates a netlink socket for @var{proto} and binds it to @var{addr}. |
249 | |
250 | @var{proto} is the integer representing the protocol. For instance, rtnetlink |
251 | can be selected by usin @code{NETLINK_ROUTE} (defined in |
252 | @code{(netlink constant)}). |
253 | |
254 | @var{addr} is a bytevector, as returned by @code{get-addr}. |
255 | |
256 | @var{flags} is a set of additional flags to pass as the second argument |
257 | to the @code{socket} system call---e.g., @code{SOCK_NONBLOCK}. |
258 | @end deffn |
259 | |
260 | @deffn {Scheme Procedure} connect-route [#:groups 0] [#:flags 0] |
261 | This procedure is a wrapper for @code{connect} that creates a socket for the |
262 | rtnetlink protocol, binds it to the kernel and returns it. By passing the |
263 | optional @var{groups} keyword, you can select broadcast groups to subscribe to. |
264 | |
265 | @var{flags} is a set of additional flags to pass as the second argument |
266 | to the @code{socket} system call---e.g., @code{SOCK_NONBLOCK}. |
267 | @end deffn |
268 | |
269 | @cindex subscribing, to an rtnetlink group |
270 | @deffn {Scheme Procedure} add-socket-membership @var{sock} @var{group} |
271 | Make @var{sock} a member of @var{group}, an @code{RTNLGRP_} constant, |
272 | meaning that it will be subscribed to events of that group. |
273 | |
274 | For example, here is how you could create a netlink socket and subscribe |
275 | it to the ``link'' group so that it receives notifications for new and |
276 | removed links: |
277 | |
278 | @lisp |
279 | (let ((sock (connect-route))) |
280 | (add-socket-membership sock RTNLGRP_LINK) |
281 | @dots{}) |
282 | @end lisp |
283 | |
284 | This procedure is implemented as a @code{setsockopt} call. |
285 | @end deffn |
286 | |
287 | @deffn {Scheme Procedure} send-msg @var{msg} @var{sock} [#:@var{addr}] |
288 | Send @var{msg} (it must be of type message, @xref{Netlink Headers}) to |
289 | @var{addr} using @var{sock}. If not passed, @var{addr} is the address of |
290 | the kernel. |
291 | @end deffn |
292 | |
293 | @deffn {Scheme Procedure} receive-msg @var{sock} [#:@var{addr}] |
294 | Receives a message from @var{sock} from @var{addr}. This procedure is blocking. |
295 | If not passed, @var{addr} defaults to the address of the kernel. This |
296 | procedure returns the message as a bytevector, that you can deserialize with |
297 | @code{deserialize} (@xref{Data Types}) |
298 | @end deffn |
299 | |
300 | @deffn {Scheme Procedure} receive-and-decode-msg @var{sock} @var{decoder} @ |
301 | [#:@var{addr}] |
302 | Receives one or more messages from @var{sock} from @var{addr}. this procedure |
303 | is blocking. If not passed, @var{addr} defaults to the address of the kernel. |
304 | This procedure returns a list of messages that were decoded using @var{decoder}. |
305 | |
306 | When the answer has the @code{NLM_F_MULTI} flag, this procedure decodes the next |
307 | message, until it receives a @code{NLMSG_DONE} message. It returns the list |
308 | of every netlink messages it received, including the @code{NLMSG_DONE}. |
309 | @end deffn |
310 | |
311 | @node Netlink API |
312 | @section Netlink API |
313 | |
314 | This section introduces the data structures used for all the netlink protocols. |
315 | First, we introduce the structure of a netlink message, then we present the |
316 | standard types of netlink messages, that can be used with every protocol. |
317 | |
318 | @node Netlink Headers |
319 | @subsection Netlink Headers |
320 | |
321 | The @code{(netlink message)} module defines the message structure that contains |
322 | a netlink message. It is composed of a header and a body, and is the data |
323 | structure to pass to @code{send-msg} (@xref{Netlink Connections}). |
324 | |
325 | This module defines the following data structure: |
326 | |
327 | @deffn {Datatype} message |
328 | @table @asis |
329 | @item @code{type} |
330 | The type of data in the body of the message. For instance, @code{RTM_GETLINK}. |
331 | |
332 | @item @code{flags} |
333 | The set of flags that are set in the header. For instance, |
334 | @code{(logior NLM_F_REQUEST NLM_F_DUMP)}. |
335 | |
336 | @item @code{seq} |
337 | The sequence number of the message. If this message is an answer to a request, |
338 | it must keep the same sequence number. Otherwise, you must generate a new and |
339 | unique sequence number, to track the answers. |
340 | |
341 | @item @code{pid} |
342 | The PID of the receiving process, or 0 for the kernel. |
343 | |
344 | @item @code{data} |
345 | The actual body, as an @code{nl-data} structure. |
346 | |
347 | @end table |
348 | @end deffn |
349 | |
350 | @node Standard Message Types |
351 | @subsection Standard Message Types |
352 | |
353 | The @code{(netlink standard)} module defines the set of standard message types |
354 | and their data type. |
355 | |
356 | @deffn {Datatype} error-message |
357 | @table @asis |
358 | @item @code{err} |
359 | The error code, as a negative number. |
360 | |
361 | @item @code{hdr} |
362 | The message on which this error applies. |
363 | |
364 | @end table |
365 | |
366 | @deffn {Scheme Variable} no-data |
367 | This variable defines the absence of data. This is useful when a structure |
368 | is expecting a body part, but the protocol specifically defines that it should |
369 | not take any data in some cases. For instance, a @code{NLMSG_NOOP} message |
370 | takes no data, so the @code{data} field of the message will contain this |
371 | @code{no-data} value. |
372 | @end deffn |
373 | |
374 | @end deffn |
375 | |
376 | @node Rtnetlink API |
377 | @section Rtnetlink API |
378 | @cindex rtnetlink |
379 | @cindex ROUTE_NETLINK |
380 | |
381 | This section describes the support for rtnetlink in guile-netlink. Rtnetlink |
382 | is the protocol responsible for everything related to network routing. It |
383 | allows you to manage links, addresses, routing tables, neighbor chaces, |
384 | routing rules, queueing disciplines, traffic classes, traffic filters and |
385 | more. |
386 | |
387 | @node Routing Attributes |
388 | @subsection Routing Attributes |
389 | |
390 | The @code{(netlink route attrs)} module defines the following data types: |
391 | |
392 | @deffn {Datatype} route-attr |
393 | This defines a header structure for the attribute, as well as its body. |
394 | |
395 | @table @asis |
396 | @item @code{type} |
397 | This is the type of the attribute, for instance @code{IFLA_ADDRESS}. |
398 | |
399 | @item @code{data} |
400 | This is the body of the attribute, ie.@: its value. |
401 | @end table |
402 | @end deffn |
403 | |
404 | The module also defines additional data types that are not represented as |
405 | a record, but by a simple type. For each of the following types, there is |
406 | a @code{make-*-route-attr} procedure to produce a @code{nl-data} value |
407 | for this type. There is also @code{deserialize-route-attr-data-*} procedure |
408 | to deserialize a value of this type. |
409 | |
410 | @table @asis |
411 | @item @code{u8} |
412 | A one-byte unsigned integer |
413 | @item @code{u16} |
414 | A two-bytes unsigned integer |
415 | @item @code{u32} |
416 | A four-bytes unsigned integer |
417 | @item @code{s32} |
418 | A four-bytes signed integer |
419 | @item @code{string} |
420 | A string |
421 | @item @code{ethernet} |
422 | An ethernet address. Its value is a string that represents that address, |
423 | for instnace @code{"01:23:45:67:89:ab"} |
424 | @item @code{ipv4} |
425 | An IPv4 address. Its value is a string that represents that address, |
426 | for instnace @code{"192.0.2.152"} |
427 | @item @code{ipv6} |
428 | An IPv6 address. Its value is a string that represents that address, |
429 | for instnace @code{"2001:db8::0123:4567:89ab:cdef"} |
430 | @item @code{bv} |
431 | A bytevector. This is used by default when the type is not supported. |
432 | @end table |
433 | |
434 | @node Link Messages |
435 | @subsection Link Messages |
436 | |
437 | The @code{(netlink route link)} package defines the following data type: |
438 | |
439 | @deffn {Datatype} link-message |
440 | This datatype represents a link message with its routing attributes. This type |
441 | of message is expected when using the @var{RTM_*LINK} message types. |
442 | |
443 | @table @asis |
444 | @item @code{family} |
445 | The network family, defined as @code{AF_UNSPEC} in the rtnetlink documentation, |
446 | although it holds different values in practice. |
447 | |
448 | @item @code{type} |
449 | The device type. |
450 | |
451 | @item @code{index} |
452 | The index of the device. This is used to select a specific device by its index, |
453 | or 0 to not filter by device index. |
454 | |
455 | @item @code{flags} |
456 | The device flags. See @code{man 7 netdevices} for a list. |
457 | |
458 | @item @code{attrs} |
459 | A list of attributes. This field must contain a list of @code{nl-data} |
460 | structures, not a structure by itself. |
461 | @end table |
462 | @end deffn |
463 | |
464 | @node Address Messages |
465 | @subsection Address Messages |
466 | |
467 | The @code{(netlink route addr)} package defines the following data type: |
468 | |
469 | @deffn {Datatype} addr-message |
470 | This datatype represents an address message with its routing attributes. This |
471 | type of message is expected when using the @var{RTM_*ADDR} message types. |
472 | |
473 | @table @asis |
474 | @item @code{family} |
475 | The network family, either @code{AF_INET} for IPv4 addresses, or @code{AF_INET6} |
476 | for IPv6 addresses. |
477 | |
478 | @item @code{prefix-len} |
479 | The prefix length, i.e.@: the length of the prefix mask, in bits, if defined |
480 | for the address family. |
481 | |
482 | @item @code{flags} |
483 | Address flags. This can be a flag word of @code{IFA_F_SECONDARY} for secondary |
484 | address (old alias interface), @code{IFA_F_PERMANENT} for a permanent |
485 | address set by the user and other undocumented flags. |
486 | |
487 | @item @code{scope} |
488 | The address scope. |
489 | |
490 | @item @code{index} |
491 | The index of the device this address is for. |
492 | |
493 | @item @code{attrs} |
494 | A list of attributes. This field must contain a list of @code{nl-data} |
495 | structures, not a structure by itself. |
496 | @end table |
497 | @end deffn |
498 | |
499 | @node IP Library |
500 | @chapter IP Library |
501 | |
502 | This library comes with higher-level procedures that let you access and modify |
503 | the state of network on your computer. |
504 | |
505 | @node Link |
506 | @section Link |
507 | |
508 | The @code{(ip link)} module introduces procedures to access and modify the |
509 | network links on your machine. They are equivalent to the @command{ip link} |
510 | family of commands, from @code{iproute2}. |
511 | |
512 | @deffn {Datatype} <link> |
513 | |
514 | Datatype representing the status of a network link. |
515 | |
516 | get-links |
517 | print-link |
518 | |
519 | <link> make-link link? |
520 | link-name link-id link-type link-flags link-mtu link-qdisc |
521 | link-state link-mode link-group link-qlen link-addr link-brd |
522 | |
523 | @table @asis |
524 | @item @code{name} |
525 | Name of the link, such as @code{"enp1s0"}. |
526 | |
527 | @item @code{id} |
528 | Index of the link, a unique number used to identify the link. |
529 | |
530 | @item @code{type} |
531 | Type of the link, as an integer. |
532 | |
533 | @item @code{flags} |
534 | Flags associated with the device, as a list of symbols, such as |
535 | @code{'(UP LOOPBACK)}. |
536 | |
537 | @item @code{mtu} |
538 | MTU of the link, as an integer. |
539 | |
540 | @item @code{qdisc} |
541 | Queuing discipline of the link, as a string, such as @code{"noqueue"}. |
542 | |
543 | @item @code{state} |
544 | State of the link, as an integer. Use @code{int->operstate} from |
545 | @code{(netlink constant)} to get a symbol, such as @code{IF_OPER_UP}. |
546 | |
547 | @item @code{mode} |
548 | Mode of the link. 0 means @code{DORMANT}, 1 means @code{DEFAULT}. |
549 | |
550 | @item @code{group} |
551 | Identifier of the group it belongs to. 0 for @code{default}. |
552 | |
553 | @item @code{qlen} |
554 | Size of the queue. |
555 | |
556 | @item @code{addr} |
557 | Ethernet address of the link, as a string. |
558 | |
559 | @item @code{brd} |
560 | Broadcast (ethernet) address of the link, as a string. |
561 | |
562 | @end table |
563 | @end deffn |
564 | |
565 | @deffn {Scheme Procedure} get-links |
566 | Returns the list of existing links in the system, as a list of @code{<link>} |
567 | objects. |
568 | @end deffn |
569 | |
570 | @deffn {Scheme Procedure} wait-for-link @var{name} [#:blocking? #t] |
571 | Wait until a link called @var{name} (a string such as @code{"ens3"}) shows |
572 | up. |
573 | |
574 | When @var{blocking?} is false, use a non-blocking socket and cooperate via |
575 | @code{current-read-waiter}---useful when using Fibers. |
576 | @end deffn |
577 | |
578 | @deffn {Sceme Procedure} print-link @var{link} |
579 | Display @var{link} on the standard output, using a format similar to |
580 | @command{ip link} from @code{iproute2}. |
581 | @end deffn |
582 | |
583 | @deffn {Scheme Procedure} link-set @var{device} [#:up @code{#f}] @ |
584 | [#:down @code{#f}] [#:type @code{#f}] [#:arp-on @code{#f}] @ |
585 | [#:arp-off @code{#f}] [#:dynamic-on @code{#f}] [#:dynamic-off @code{#f}] @ |
586 | [#:multicast-on @code{#f}] [#:multicast-off @code{#f}] @ |
587 | [#:allmulticast-on @code{#f}] [#:allmulticast-off @code{#f}] @ |
588 | [#:promisc-on @code{#f}] [#:promisc-off @code{#f}] [#:trailers-on @code{#f}] @ |
589 | [#:trailers-off @code{#f}] [#:carrier-on @code{#f}] [#:carrier-off @code{#f}] @ |
590 | [#:txqueuelen @code{#f}] [#:name @code{#f}] [#:address @code{#f}] @ |
591 | [#:broadcast @code{#f}] [#:mtu @code{#f}] [#:netns @code{#f}] |
592 | Modify an existing link and set its flags and attributes to the ones specified |
593 | by the various keywords. When a keyword is omited, the corresponding attribute |
594 | is not changed. |
595 | |
596 | @var{device} can be a device index (as a number) or a device name (as a string). |
597 | |
598 | Do not set @code{#:up} and @code{#:down} at the same time. Do not set |
599 | @code{*-on} and @code{*-off} at the same time. |
600 | @end deffn |
601 | |
602 | @deffn {Scheme Procedure} link-show [#:device @code{#f}] [#:group @code{#f}] @ |
603 | [#:up @code{#f}] [#:master @code{#f}] [#:vrf @code{#f}] [#:type @code{#f}] |
604 | Print the set of devices on standard output. Setting any of the keyword to a |
605 | non-false value will filter the results to only show results that match the |
606 | corresponding value. You may set more than one keyword. |
607 | @end deffn |
608 | |
609 | @deffn {Scheme Procedure} link-add @var{name} @var{type} [#:type-args @code{'()}] |
610 | Add a new link with given name and type. Additional arguments can be passed to |
611 | control the state of the link at creation. @var{type-args} is an association |
612 | list containing additional values for the given type. |
613 | |
614 | When @var{type} is @code{"vlan"}, @var{type-args} can contain a number associated |
615 | with @code{'id}: the VLAN id to be created and a link name associated with |
616 | @code{"link"}: the name of the link on which the vlan is created. |
617 | |
618 | The following is an example in which we create a new vlan link: |
619 | @example |
620 | ;; same as "ip l add link eth0 name eth0.7 type vlan id 7" |
621 | (link-add "eth0.7" "vlan" #:type-args '((id . 7) (link . "eth0"))) |
622 | @end example |
623 | |
624 | When @var{type} is @code{"veth"}, @var{type-args} can contain a string associated |
625 | with @code{'peer}: the name of the peer. |
626 | |
627 | The following is an example in which we create a new veth (virtual ethernet) |
628 | pair and give them a name: |
629 | @example |
630 | ;; same as "ip l add v0p0 type veth peer v0p1" |
631 | (link-add "v0p0" "veth" #:type-args '((peer . "v0p1"))) |
632 | @end example |
633 | @end deffn |
634 | |
635 | @deffn {Scheme Procedure} link-del @var{device} |
636 | Delete a link. @var{device} can contain the name of the link, as a string, |
637 | or its index, as a number. |
638 | @end deffn |
639 | |
640 | @node Addr |
641 | @section Addr |
642 | |
643 | The @code{(ip addr)} module introduces procedures to access and modify the |
644 | network addresses on your machine. They are equivalent to the @command{ip addr} |
645 | family of commands, from @code{iproute2}. |
646 | |
647 | @deffn {Scheme Procedure} addr-add @var{device} @var{cidr} [@var{#:ipv6?} #f] @ |
648 | [@var{#:peer} @code{(cidr->addr cidr)}] [@var{#:broadcast} #f] @ |
649 | [@var{#:anycast} #f] [@var{#:label} #f] [@var{#:scope} @code{'global}] @ |
650 | [@var{#:metric} #f] [@var{#:home?} #f] [@var{#:mngtmpaddr?} #f] @ |
651 | [@var{#:nodad?} #f] [@var{optimistic?} #f] [@var{noprefixroute?} #f] @ |
652 | [@var{#:autojoin?} #f] |
653 | Add the address given in @var{cidr} to @var{device}. @var{device} can |
654 | contain the name of the link, as a string, or its index, as a number. |
655 | |
656 | @var{cidr} must be a string containing the address and prefix length, in |
657 | CIDR notation (@code{addr/prefix}). |
658 | |
659 | @example |
660 | (addr-add "enp1s0" "192.0.2.15/24") |
661 | @end example |
662 | |
663 | If you wish to add an IPv6 address instead, set @code{#:ipv6} to @code{#t}, |
664 | as in the following example. |
665 | |
666 | @example |
667 | (addr-add "enp1s0" "2001:db8::1a4c/64" #:ipv6? #t) |
668 | @end example |
669 | |
670 | Note that using the wrong ip type with the wrong value for the @code{#:ipv6?} |
671 | flag will result in a @code{Bad address} exception from inet-pton. |
672 | |
673 | Additional flags are available; they follow the same semantics as Iproute2. |
674 | For pointopoint interfaces, you can specify the address of the remote endpoint |
675 | with @var{#:peer}. You can specify a broadcast or anycast address with |
676 | @var{#:broadcast} and @var{#:anycast}. All three require an IP address passed |
677 | as a string when specified. |
678 | |
679 | You can specify a label for the address with @var{#:label}. The parameter must |
680 | be a string that is either the name of the device, or starts with the name of |
681 | the device, followed by a colon and must contain at most 15 characters. |
682 | |
683 | You can specify a scope with @var{#:scope}, whose value is either @code{'global}, |
684 | @code{'link}, @code{'host} or a numeric value. |
685 | |
686 | You can specify the priority of the prefix route associated with this address |
687 | using @code{#:metric}, a number. |
688 | |
689 | Finally, this procedures accepts address configuration flags, whose values are |
690 | booleans. They are unset by default. Some flags only work for IPv6 addresses, |
691 | those are @var{#:home?} to designate this address as the ``home address'', |
692 | @var{#:mngtmpaddr?}, @var{#:nodad?} and @var{#:optimistic?}. The flags |
693 | @var{#:noprefixroute?} and @var{#:autojoin?} can be set for IPv4 and IPv6 |
694 | addresses. |
695 | @end deffn |
696 | |
697 | @deffn {Scheme Procedure} addr-del @var{device} @var{cidr} [@var{#:ipv6?} #f] @ |
698 | [@var{#:peer} @code{(cidr->addr cidr)}] [@var{#:broadcast} #f] @ |
699 | [@var{#:anycast} #f] [@var{#:label} #f] [@var{#:scope} @code{'global}] @ |
700 | [@var{#:metric} #f] [@var{#:home?} #f] [@var{#:mngtmpaddr?} #f] @ |
701 | [@var{#:nodad?} #f] [@var{optimistic?} #f] [@var{noprefixroute?} #f] @ |
702 | [@var{#:autojoin?} #f] |
703 | Delete the address given in @var{cidr} from @var{device}. @var{device} can |
704 | contain the name of the link, as a string, or its index, as a number. |
705 | |
706 | @var{cidr} must be a string containing the address and prefix length, in |
707 | CIDR notation (@code{addr/prefix}). |
708 | |
709 | @example |
710 | (addr-del "enp1s0" "192.0.2.15/24") |
711 | @end example |
712 | |
713 | If you wish to remove an IPv6 address instead, set @code{#:ipv6} to @code{#t}, |
714 | as in the following example. |
715 | |
716 | @example |
717 | (addr-del "enp1s0" "2001:db8::1a4c/64" #:ipv6? #t) |
718 | @end example |
719 | |
720 | Note that using the wrong ip type with the wrong value for the @code{#:ipv6?} |
721 | flag will result in a @code{Bad address} exception from inet-pton. |
722 | |
723 | Additional flags are available, see the description in @code{addr-add} for more |
724 | details. |
725 | @end deffn |
726 | |
727 | @deffn {Scheme Procedure} addr-show [@var{device}] |
728 | Print the list of addresses for each device on standard output. Setting |
729 | @code{device} to a link name or link identifier will restrict the output |
730 | to addresses of that device. |
731 | @end deffn |
732 | |
733 | @node Route |
734 | @section Route |
735 | |
736 | The @code{(ip route)} module introduces procedures to access and modify the |
737 | network routes on your machine. They are equivalent to the @command{ip route} |
738 | family of commands, from @code{iproute2}. |
739 | |
740 | @deffn {Scheme Procedure} route-add @var{dest} [@var{#:ipv6?} #f] @ |
741 | [@var{#:device} #f] [@var{#:table} RT_TABLE_MAIN] [@var{#:protocol} #f] @ |
742 | [@var{#:scope} RT_SCOPE_LINK] [@var{#:type} RTN_UNICAST] @ |
743 | [@var{#:priority} #f] [@var{#:src} #f] [@var{#:via} #f] @ |
744 | [@var{onlink?} #f] |
745 | Add the route described by the argmuents. @var{dest} is the destination network, |
746 | in cidr notation (@code{addr/prefix}) or the string @code{"default"}. |
747 | |
748 | @var{#:device} is the name or index of a network link. @var{#:table} is the |
749 | index of a routing table, one of @code{RT_TABLE_COMPAT}, @code{RT_TABLE_DEFAULT}, |
750 | @code{RT_TABLE_MAIN} or @code{RT_TABLE_LOCAL}, as defined in |
751 | @code{(netlink constant)}. |
752 | |
753 | If it is set, @var{#:protocol} must be the routing protocol, @code{RTPROT_*}, |
754 | as defined in @code{(netlink constant)}. |
755 | |
756 | @var{#:scope} must be the scope of the route, one of @code{RT_SCOPE_*}, as |
757 | defined in @code{(netlink constant)}. |
758 | |
759 | @var{#:type} must be the type of route, one of @code{RTN_*}, as defined in |
760 | @code{(netlink constant)}. |
761 | |
762 | If set, @var{#:priority} is a number specifying the priority of the rule |
763 | when the kernel is looking for a matching rule. This is also known as the |
764 | metric of the route. |
765 | |
766 | If set, @var{#:src} is the source address in cidr notation, or as a single |
767 | address. |
768 | |
769 | If set, @var{#:via} is the gateway address. This is not in cidr notation, as |
770 | the gateway is a single address, not a network. |
771 | |
772 | If set, @var{#:onlink?} adds the RTNH_F_ONLINK flag, which allows using the rule |
773 | as if the next hop (specified by the @var{#:via} option) was present on the |
774 | interface, even if its address is not part of the interface's network. |
775 | |
776 | @example |
777 | (route-add "default" #:device "enp1s0" #:via "192.0.2.1") |
778 | (route-add "192.0.2.0/24" #:device "enp1s0" #:src "192.0.2.15") |
779 | @end example |
780 | |
781 | If you wish to add an IPv6 route instead, set @code{#:ipv6} to @code{#t}, |
782 | as in the following example. |
783 | |
784 | @example |
785 | (addr-add "2001:db8::/64" #:device "enp1s0" #:src "2001:db8::1a4c" #:ipv6? #t) |
786 | @end example |
787 | |
788 | Note that using the wrong ip type with the wrong value for the @code{#:ipv6?} |
789 | flag will result in a @code{Bad address} exception from inet-pton. |
790 | @end deffn |
791 | |
792 | @deffn {Scheme Procedure} route-del @var{dest} [@var{#:ipv6?} #f] @ |
793 | [@var{#:device} #f] [@var{#:table} RT_TABLE_MAIN] [@var{#:protocol} #f] @ |
794 | [@var{#:scope} #f] [@var{#:type} #f] [@var{#:priority} #f] @ |
795 | [@var{#:src} #f] [@var{#:via} #f] |
796 | Delete the route given in arguments. The arguments follow the same structure |
797 | as @code{route-add}. By specifying more arguments, you can narrow down the |
798 | search for the rule to delete further. Each call will only remove one route, |
799 | so being more precise ensures you target the rule you wish to delete. It |
800 | is not clear which route is deleted if multiple routes match your query. |
801 | @end deffn |
802 | |
803 | @deffn {Scheme Procedure} route-show [@var{#:table} RT_TABLE_MAIN] @ |
804 | [@var{#:family} AF_UNSPEC] |
805 | Print the list of routes on standard output. Note that, contrary to |
806 | @command{ip route show}, we show both IPv4 and IPv6 routes. To narrow down the |
807 | number of routes displayed, you can specify the family as in this example. |
808 | |
809 | @example |
810 | (route-show #:family AF_INET6) |
811 | @end example |
812 | @end deffn |
813 | |
814 | @c ********************************************************************* |
815 | @node Concept Index |
816 | @unnumbered Concept Index |
817 | @printindex cp |
818 | |
819 | @node Programming Index |
820 | @unnumbered Programming Index |
821 | @syncodeindex tp fn |
822 | @syncodeindex vr fn |
823 | @printindex fn |
824 | |
825 | @bye |
826 |