guile-netlink/doc/guile-netlink.texi

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
Add the route described by the argmuents.  @var{dest} is the destination network,
745
in cidr notation (@code{addr/prefix}) or the string @code{"default"}.
746
747
@var{#:device} is the name or index of a network link. @var{#:table} is the
748
index of a routing table, one of @code{RT_TABLE_COMPAT}, @code{RT_TABLE_DEFAULT},
749
@code{RT_TABLE_MAIN} or @code{RT_TABLE_LOCAL}, as defined in
750
@code{(netlink constant)}.
751
752
If it is set, @var{#:protocol} must be the routing protocol, @code{RTPROT_*},
753
as defined in @code{(netlink constant)}.
754
755
@var{#:scope} must be the scope of the route, one of @code{RT_SCOPE_*}, as
756
defined in @code{(netlink constant)}.
757
758
@var{#:type} must be the type of route, one of @code{RTN_*}, as defined in
759
@code{(netlink constant)}.
760
761
If set, @var{#:priority} is a number specifying the priority of the rule
762
when the kernel is looking for a matching rule.  This is also known as the
763
metric of the route.
764
765
If set, @var{#:src} is the source address in cidr notation, or as a single
766
address.
767
768
If set, @var{#:via} is the gateway address.  This is not in cidr notation, as
769
the gateway is a single address, not a network.
770
771
@example
772
(route-add "default" #:device "enp1s0" #:via "192.0.2.1")
773
(route-add "192.0.2.0/24" #:device "enp1s0" #:src "192.0.2.15")
774
@end example
775
776
If you wish to add an IPv6 route instead, set @code{#:ipv6} to @code{#t},
777
as in the following example.
778
779
@example
780
(addr-add "2001:db8::/64" #:device "enp1s0" #:src "2001:db8::1a4c" #:ipv6? #t)
781
@end example
782
783
Note that using the wrong ip type with the wrong value for the @code{#:ipv6?}
784
flag will result in a @code{Bad address} exception from inet-pton.
785
@end deffn
786
787
@deffn {Scheme Procedure} route-del @var{dest} [@var{#:ipv6?} #f] @
788
    [@var{#:device} #f] [@var{#:table} RT_TABLE_MAIN] [@var{#:protocol} #f] @
789
    [@var{#:scope} #f] [@var{#:type} #f] [@var{#:priority} #f] @
790
    [@var{#:src} #f] [@var{#:via} #f]
791
Delete the route given in arguments.  The arguments follow the same structure
792
as @code{route-add}.  By specifying more arguments, you can narrow down the
793
search for the rule to delete further.  Each call will only remove one route,
794
so being more precise ensures you target the rule you wish to delete.  It
795
is not clear which route is deleted if multiple routes match your query.
796
@end deffn
797
798
@deffn {Scheme Procedure} route-show [@var{#:table} RT_TABLE_MAIN] @
799
    [@var{#:family} AF_UNSPEC]
800
Print the list of routes on standard output.  Note that, contrary to
801
@command{ip route show}, we show both IPv4 and IPv6 routes.  To narrow down the
802
number of routes displayed, you can specify the family as in this example.
803
804
@example
805
(route-show #:family AF_INET6)
806
@end example
807
@end deffn
808
809
@c *********************************************************************
810
@node Concept Index
811
@unnumbered Concept Index
812
@printindex cp
813
814
@node Programming Index
815
@unnumbered Programming Index
816
@syncodeindex tp fn
817
@syncodeindex vr fn
818
@printindex fn
819
820
@bye
821