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