1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Netlink — pyroute2 0.5.2 documentation</title>
<link rel="stylesheet" href="_static/classic.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/custom.css" type="text/css" />
<script type="text/javascript" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Base netlink socket and marshal" href="nlsocket.html" />
<link rel="prev" title="Module architecture" href="arch.html" />
</head><body>
<div class="related" role="navigation" aria-label="related navigation">
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="nlsocket.html" title="Base netlink socket and marshal"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="arch.html" title="Module architecture"
accesskey="P">previous</a> |</li>
<li class="nav-item"><a href="http://pyroute2.org">Project home</a> »</li>
<li class="nav-item nav-item-0"><a href="index.html">pyroute2 0.5.2 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<span class="target" id="module-pyroute2.netlink"></span><div class="section" id="netlink">
<h1>Netlink<a class="headerlink" href="#netlink" title="Permalink to this headline">¶</a></h1>
<div class="section" id="basics">
<h2>basics<a class="headerlink" href="#basics" title="Permalink to this headline">¶</a></h2>
<p>General netlink packet structure:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">nlmsg</span> <span class="n">packet</span><span class="p">:</span>
<span class="n">header</span>
<span class="n">data</span>
</pre></div>
</div>
<p>Generic netlink message header:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">nlmsg</span> <span class="n">header</span><span class="p">:</span>
<span class="n">uint32</span> <span class="n">length</span>
<span class="n">uint16</span> <span class="nb">type</span>
<span class="n">uint16</span> <span class="n">flags</span>
<span class="n">uint32</span> <span class="n">sequence</span> <span class="n">number</span>
<span class="n">uint32</span> <span class="n">pid</span>
</pre></div>
</div>
<p>The <cite>length</cite> field is the length of all the packet, including
data and header. The <cite>type</cite> field is used to distinguish different
message types, commands etc. Please note, that there is no
explicit protocol field – you choose a netlink protocol, when
you create a socket.</p>
<p>The <cite>sequence number</cite> is very important. Netlink is an asynchronous
protocol – it means, that the packet order doesn’t matter and is
not guaranteed. But responses to a request are always marked with
the same sequence number, so you can treat it as a cookie.</p>
<p>Please keep in mind, that a netlink request can initiate a
cascade of events, and netlink messages from these events can
carry sequence number == 0. E.g., it is so when you remove a
primary IP addr from an interface, when <cite>promote_secondaries</cite>
sysctl is set.</p>
<p>Beside of incapsulated headers and other protocol-specific data,
netlink messages can carry NLA (netlink attributes). NLA
structure is as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">NLA</span> <span class="n">header</span><span class="p">:</span>
<span class="n">uint16</span> <span class="n">length</span>
<span class="n">uint16</span> <span class="nb">type</span>
<span class="n">NLA</span> <span class="n">data</span><span class="p">:</span>
<span class="n">data</span><span class="o">-</span><span class="n">specific</span> <span class="n">struct</span>
<span class="c1"># optional:</span>
<span class="n">NLA</span>
<span class="n">NLA</span>
<span class="o">...</span>
</pre></div>
</div>
<p>So, NLA structures can be nested, forming a tree.</p>
<p>Complete structure of a netlink packet:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">nlmsg</span> <span class="n">header</span><span class="p">:</span>
<span class="n">uint32</span> <span class="n">length</span>
<span class="n">uint16</span> <span class="nb">type</span>
<span class="n">uint16</span> <span class="n">flags</span>
<span class="n">uint32</span> <span class="n">sequence</span> <span class="n">number</span>
<span class="n">uint32</span> <span class="n">pid</span>
<span class="p">[</span> <span class="n">optional</span> <span class="n">protocol</span><span class="o">-</span><span class="n">specific</span> <span class="n">data</span> <span class="p">]</span>
<span class="p">[</span> <span class="n">optional</span> <span class="n">NLA</span> <span class="n">tree</span> <span class="p">]</span>
</pre></div>
</div>
<p>More information about netlink protocol you can find in
the man pages.</p>
</div>
<div class="section" id="pyroute2-and-netlink">
<h2>pyroute2 and netlink<a class="headerlink" href="#pyroute2-and-netlink" title="Permalink to this headline">¶</a></h2>
<div class="section" id="packets">
<h3>packets<a class="headerlink" href="#packets" title="Permalink to this headline">¶</a></h3>
<p>To simplify the development, pyroute2 provides an easy way to
describe packet structure. As an example, you can take the
ifaddrmsg description – <cite>pyroute2/netlink/rtnl/ifaddrmsg.py</cite>.</p>
<p>To describe a packet, you need to inherit from <cite>nlmsg</cite> class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pyroute2.netlink</span> <span class="k">import</span> <span class="n">nlmsg</span>
<span class="k">class</span> <span class="nc">foo_msg</span><span class="p">(</span><span class="n">nlmsg</span><span class="p">):</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">(</span> <span class="o">...</span> <span class="p">)</span>
<span class="n">nla_map</span> <span class="o">=</span> <span class="p">(</span> <span class="o">...</span> <span class="p">)</span>
</pre></div>
</div>
<p>NLA are described in the same way, but the parent class should be
<cite>nla</cite>, instead of <cite>nlmsg</cite>. And yes, it is important to use the
proper parent class – it affects the header structure.</p>
</div>
<div class="section" id="fields-attribute">
<h3>fields attribute<a class="headerlink" href="#fields-attribute" title="Permalink to this headline">¶</a></h3>
<p>The <cite>fields</cite> attribute describes the structure of the
protocol-specific data. It is a tuple of tuples, where each
member contains a field name and its data format.</p>
<p>Field data format should be specified as for Python <cite>struct</cite>
module. E.g., ifaddrmsg structure:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">struct</span> <span class="n">ifaddrmsg</span> <span class="p">{</span>
<span class="n">__u8</span> <span class="n">ifa_family</span><span class="p">;</span>
<span class="n">__u8</span> <span class="n">ifa_prefixlen</span><span class="p">;</span>
<span class="n">__u8</span> <span class="n">ifa_flags</span><span class="p">;</span>
<span class="n">__u8</span> <span class="n">ifa_scope</span><span class="p">;</span>
<span class="n">__u32</span> <span class="n">ifa_index</span><span class="p">;</span>
<span class="p">};</span>
</pre></div>
</div>
<p>should be described as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ifaddrmsg</span><span class="p">(</span><span class="n">nlmsg</span><span class="p">):</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">((</span><span class="s1">'family'</span><span class="p">,</span> <span class="s1">'B'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'prefixlen'</span><span class="p">,</span> <span class="s1">'B'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'flags'</span><span class="p">,</span> <span class="s1">'B'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'scope'</span><span class="p">,</span> <span class="s1">'B'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'index'</span><span class="p">,</span> <span class="s1">'I'</span><span class="p">))</span>
</pre></div>
</div>
<p>Format strings are passed directly to the <cite>struct</cite> module,
so you can use all the notations like <cite>>I</cite>, <cite>16s</cite> etc. All
fields are parsed from the stream separately, so if you
want to explicitly fix alignemt, as if it were C struct,
use the <cite>pack</cite> attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">tstats</span><span class="p">(</span><span class="n">nla</span><span class="p">):</span>
<span class="n">pack</span> <span class="o">=</span> <span class="s1">'struct'</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">((</span><span class="s1">'version'</span><span class="p">,</span> <span class="s1">'H'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'ac_exitcode'</span><span class="p">,</span> <span class="s1">'I'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'ac_flag'</span><span class="p">,</span> <span class="s1">'B'</span><span class="p">),</span>
<span class="o">...</span><span class="p">)</span>
</pre></div>
</div>
<p>Explicit padding bytes also can be used, when struct
packing doesn’t work well:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ipq_mode_msg</span><span class="p">(</span><span class="n">nlmsg</span><span class="p">):</span>
<span class="n">pack</span> <span class="o">=</span> <span class="s1">'struct'</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">((</span><span class="s1">'value'</span><span class="p">,</span> <span class="s1">'B'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'__pad'</span><span class="p">,</span> <span class="s1">'7x'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'range'</span><span class="p">,</span> <span class="s1">'I'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'__pad'</span><span class="p">,</span> <span class="s1">'12x'</span><span class="p">))</span>
</pre></div>
</div>
</div>
<div class="section" id="nla-map-attribute">
<h3>nla_map attribute<a class="headerlink" href="#nla-map-attribute" title="Permalink to this headline">¶</a></h3>
<p>The <cite>nla_map</cite> attribute is a tuple of NLA descriptions. Each
description is also a tuple in two different forms: either
two fields, name and format, or three fields: type, name and
format.</p>
<p>Please notice, that the format field is a string name of
corresponding NLA class:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ifaddrmsg</span><span class="p">(</span><span class="n">nlmsg</span><span class="p">):</span>
<span class="o">...</span>
<span class="n">nla_map</span> <span class="o">=</span> <span class="p">((</span><span class="s1">'IFA_UNSPEC'</span><span class="p">,</span> <span class="s1">'hex'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'IFA_ADDRESS'</span><span class="p">,</span> <span class="s1">'ipaddr'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'IFA_LOCAL'</span><span class="p">,</span> <span class="s1">'ipaddr'</span><span class="p">),</span>
<span class="o">...</span><span class="p">)</span>
</pre></div>
</div>
<p>This code will create mapping, where IFA_ADDRESS NLA will be of
type 1 and IFA_LOCAL – of type 2, etc. Both NLA will be decoded
as IP addresses (class <cite>ipaddr</cite>). IFA_UNSPEC will be of type 0,
and if it will be in the NLA tree, it will be just dumped in hex.</p>
<p>NLA class names are should be specified as strings, since they
are resolved in runtime.</p>
<p>There are several pre-defined NLA types, that you will get with
<cite>nla</cite> class:</p>
<blockquote>
<div><ul class="simple">
<li><cite>none</cite> – ignore this NLA</li>
<li><cite>flag</cite> – boolean flag NLA (no payload; NLA exists = True)</li>
<li><cite>uint8</cite>, <cite>uint16</cite>, <cite>uint32</cite>, <cite>uint64</cite> – unsigned int</li>
<li><cite>be8</cite>, <cite>be16</cite>, <cite>be32</cite>, <cite>be64</cite> – big-endian unsigned int</li>
<li><cite>ipaddr</cite> – IP address, IPv4 or IPv6</li>
<li><cite>ip4addr</cite> – only IPv4 address type</li>
<li><cite>ip6addr</cite> – only IPv6 address type</li>
<li><cite>target</cite> – a univeral target (IPv4, IPv6, MPLS)</li>
<li><cite>l2addr</cite> – MAC address</li>
<li><cite>hex</cite> – hex dump as a string – useful for debugging</li>
<li><cite>cdata</cite> – a binary data</li>
<li><cite>string</cite> – UTF-8 string</li>
<li><cite>asciiz</cite> – zero-terminated ASCII string, no decoding</li>
<li><cite>array</cite> – array of simple types (uint8, uint16 etc.)</li>
</ul>
</div></blockquote>
<p>Please refer to <cite>pyroute2/netlink/__init__.py</cite> for details.</p>
<p>You can also make your own NLA descriptions:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">ifaddrmsg</span><span class="p">(</span><span class="n">nlmsg</span><span class="p">):</span>
<span class="o">...</span>
<span class="n">nla_map</span> <span class="o">=</span> <span class="p">(</span><span class="o">...</span>
<span class="p">(</span><span class="s1">'IFA_CACHEINFO'</span><span class="p">,</span> <span class="s1">'cacheinfo'</span><span class="p">),</span>
<span class="o">...</span><span class="p">)</span>
<span class="k">class</span> <span class="nc">cacheinfo</span><span class="p">(</span><span class="n">nla</span><span class="p">):</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">((</span><span class="s1">'ifa_preferred'</span><span class="p">,</span> <span class="s1">'I'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'ifa_valid'</span><span class="p">,</span> <span class="s1">'I'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'cstamp'</span><span class="p">,</span> <span class="s1">'I'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'tstamp'</span><span class="p">,</span> <span class="s1">'I'</span><span class="p">))</span>
</pre></div>
</div>
<p>Custom NLA descriptions should be defined in the same class,
where they are used.</p>
<p>Also, it is possible to use not autogenerated type numbers, as
for ifaddrmsg, but specify them explicitly:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">iw_event</span><span class="p">(</span><span class="n">nla</span><span class="p">):</span>
<span class="o">...</span>
<span class="n">nla_map</span> <span class="o">=</span> <span class="p">((</span><span class="mh">0x8B00</span><span class="p">,</span> <span class="s1">'SIOCSIWCOMMIT'</span><span class="p">,</span> <span class="s1">'hex'</span><span class="p">),</span>
<span class="p">(</span><span class="mh">0x8B01</span><span class="p">,</span> <span class="s1">'SIOCGIWNAME'</span><span class="p">,</span> <span class="s1">'hex'</span><span class="p">),</span>
<span class="p">(</span><span class="mh">0x8B02</span><span class="p">,</span> <span class="s1">'SIOCSIWNWID'</span><span class="p">,</span> <span class="s1">'hex'</span><span class="p">),</span>
<span class="p">(</span><span class="mh">0x8B03</span><span class="p">,</span> <span class="s1">'SIOCGIWNWID'</span><span class="p">,</span> <span class="s1">'hex'</span><span class="p">),</span>
<span class="o">...</span><span class="p">)</span>
</pre></div>
</div>
<p>Here you can see custom NLA type numbers – 0x8B00, 0x8B01 etc.
It is not permitted to mix these two forms in one class: you should
use ether autogenerated type numbers (two fields tuples), or
explicit numbers (three fields typles).</p>
</div>
<div class="section" id="array-types">
<h3>array types<a class="headerlink" href="#array-types" title="Permalink to this headline">¶</a></h3>
<p>There are different array-like NLA types in the kernel, and
some of them are covered by pyroute2. An array of simple type
elements:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># declaration</span>
<span class="n">nla_map</span> <span class="o">=</span> <span class="p">((</span><span class="s1">'NLA_TYPE'</span><span class="p">,</span> <span class="s1">'array(uint8)'</span><span class="p">),</span> <span class="o">...</span><span class="p">)</span>
<span class="c1"># data layout</span>
<span class="o">+======+======+----------------------------</span>
<span class="o">|</span> <span class="nb">len</span> <span class="o">|</span> <span class="nb">type</span> <span class="o">|</span> <span class="n">uint8</span> <span class="o">|</span> <span class="n">uint8</span> <span class="o">|</span> <span class="n">uint</span> <span class="mi">8</span> <span class="o">|</span> <span class="o">...</span>
<span class="o">+======+======+----------------------------</span>
<span class="c1"># decoded</span>
<span class="p">{</span><span class="s1">'attrs'</span><span class="p">:</span> <span class="p">[[</span><span class="s1">'NLA_TYPE'</span><span class="p">,</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">4</span><span class="p">,</span> <span class="mi">5</span><span class="p">,</span> <span class="o">...</span><span class="p">)],</span> <span class="o">...</span><span class="p">],</span> <span class="o">...</span><span class="p">}</span>
</pre></div>
</div>
<p>An array of NLAs:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># declaration</span>
<span class="n">nla_map</span> <span class="o">=</span> <span class="p">((</span><span class="s1">'NLA_TYPE'</span><span class="p">,</span> <span class="s1">'*type'</span><span class="p">),</span> <span class="o">...</span><span class="p">)</span>
<span class="c1"># data layout</span>
<span class="o">+=======+=======+-----------------------+-----------------------+--</span>
<span class="o">|</span> <span class="nb">len</span> <span class="o">|</span> <span class="nb">type</span><span class="o">*</span> <span class="o">|</span> <span class="nb">len</span> <span class="o">|</span> <span class="nb">type</span> <span class="o">|</span> <span class="n">payload</span> <span class="o">|</span> <span class="nb">len</span> <span class="o">|</span> <span class="nb">type</span> <span class="o">|</span> <span class="n">payload</span> <span class="o">|</span> <span class="o">...</span>
<span class="o">+=======+=======+-----------------------+-----------------------+--</span>
<span class="c1"># type* -- in that case the type is OR'ed with NLA_F_NESTED</span>
<span class="c1"># decoded</span>
<span class="p">{</span><span class="s1">'attrs'</span><span class="p">:</span> <span class="p">[[</span><span class="s1">'NLA_TYPE'</span><span class="p">,</span> <span class="p">[</span><span class="n">payload</span><span class="p">,</span> <span class="n">payload</span><span class="p">,</span> <span class="o">...</span><span class="p">]],</span> <span class="o">...</span><span class="p">],</span> <span class="o">...</span><span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="parsed-netlink-message">
<h3>parsed netlink message<a class="headerlink" href="#parsed-netlink-message" title="Permalink to this headline">¶</a></h3>
<p>Netlink messages are represented by pyroute2 as dictionaries
as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s1">'header'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'pid'</span><span class="p">:</span> <span class="o">...</span><span class="p">,</span>
<span class="s1">'length: ...,</span>
<span class="s1">'flags'</span><span class="p">:</span> <span class="o">...</span><span class="p">,</span>
<span class="s1">'error'</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span> <span class="c1"># if you are lucky</span>
<span class="s1">'type'</span><span class="p">:</span> <span class="o">...</span><span class="p">,</span>
<span class="s1">'sequence_number'</span><span class="p">:</span> <span class="o">...</span><span class="p">},</span>
<span class="c1"># fields attributes</span>
<span class="s1">'field_name1'</span><span class="p">:</span> <span class="n">value</span><span class="p">,</span>
<span class="o">...</span>
<span class="s1">'field_nameX'</span><span class="p">:</span> <span class="n">value</span><span class="p">,</span>
<span class="c1"># nla tree</span>
<span class="s1">'attrs'</span><span class="p">:</span> <span class="p">[[</span><span class="s1">'NLA_NAME1'</span><span class="p">,</span> <span class="n">value</span><span class="p">],</span>
<span class="o">...</span>
<span class="p">[</span><span class="s1">'NLA_NAMEX'</span><span class="p">,</span> <span class="n">value</span><span class="p">],</span>
<span class="p">[</span><span class="s1">'NLA_NAMEY'</span><span class="p">,</span> <span class="p">{</span><span class="s1">'field_name1'</span><span class="p">:</span> <span class="n">value</span><span class="p">,</span>
<span class="o">...</span>
<span class="s1">'field_nameX'</span><span class="p">:</span> <span class="n">value</span><span class="p">,</span>
<span class="s1">'attrs'</span><span class="p">:</span> <span class="p">[[</span><span class="s1">'NLA_NAME.... ]]}]]}</span>
</pre></div>
</div>
<p>As an example, a message from the wireless subsystem about new
scan event:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">{</span><span class="s1">'index'</span><span class="p">:</span> <span class="mi">4</span><span class="p">,</span>
<span class="s1">'family'</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="s1">'__align'</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="s1">'header'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'pid'</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="s1">'length'</span><span class="p">:</span> <span class="mi">64</span><span class="p">,</span>
<span class="s1">'flags'</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="s1">'error'</span><span class="p">:</span> <span class="kc">None</span><span class="p">,</span>
<span class="s1">'type'</span><span class="p">:</span> <span class="mi">16</span><span class="p">,</span>
<span class="s1">'sequence_number'</span><span class="p">:</span> <span class="mi">0</span><span class="p">},</span>
<span class="s1">'flags'</span><span class="p">:</span> <span class="mi">69699</span><span class="p">,</span>
<span class="s1">'ifi_type'</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span>
<span class="s1">'event'</span><span class="p">:</span> <span class="s1">'RTM_NEWLINK'</span><span class="p">,</span>
<span class="s1">'change'</span><span class="p">:</span> <span class="mi">0</span><span class="p">,</span>
<span class="s1">'attrs'</span><span class="p">:</span> <span class="p">[[</span><span class="s1">'IFLA_IFNAME'</span><span class="p">,</span> <span class="s1">'wlp3s0'</span><span class="p">],</span>
<span class="p">[</span><span class="s1">'IFLA_WIRELESS'</span><span class="p">,</span>
<span class="p">{</span><span class="s1">'attrs'</span><span class="p">:</span> <span class="p">[[</span><span class="s1">'SIOCGIWSCAN'</span><span class="p">,</span>
<span class="s1">'00:00:00:00:00:00:00:00:00:00:00:00'</span><span class="p">]]}]]}</span>
</pre></div>
</div>
<p>One important detail is that NLA chain is represented as a list of
elements <cite>[‘NLA_TYPE’, value]</cite>, not as a dictionary. The reason is that
though in the kernel <em>usually</em> NLA chain is a dictionary, the netlink
protocol by itself doesn’t require elements of each type to be unique.
In a message there may be several NLA of the same type.</p>
</div>
<div class="section" id="encoding-and-decoding-algo">
<h3>encoding and decoding algo<a class="headerlink" href="#encoding-and-decoding-algo" title="Permalink to this headline">¶</a></h3>
<p>The message encoding works as follows:</p>
<ol class="arabic simple">
<li>Reserve space for the message header (if there is)</li>
<li>Iterate defined <cite>fields</cite>, encoding values with <cite>struct.pack()</cite></li>
<li>Iterate NLA from the <cite>attrs</cite> field, looking up types in <cite>nla_map</cite></li>
<li>Encode the header</li>
</ol>
<p>Since every NLA is also an <cite>nlmsg</cite> object, there is a recursion.</p>
<p>The decoding process is a bit simpler:</p>
<ol class="arabic simple">
<li>Decode the header</li>
<li>Iterate <cite>fields</cite>, decoding values with <cite>struct.unpack()</cite></li>
<li>Iterate NLA until the message ends</li>
</ol>
<p>If the <cite>fields</cite> attribute is an empty list, the step 2 will be skipped.
The step 3 will be skipped in the case of the empty <cite>nla_map</cite>. If both
attributes are empty lists, only the header will be encoded/decoded.</p>
</div>
<div class="section" id="create-and-send-messages">
<h3>create and send messages<a class="headerlink" href="#create-and-send-messages" title="Permalink to this headline">¶</a></h3>
<p>Using high-level interfaces like <cite>IPRoute</cite> or <cite>IPDB</cite>, you will never
need to manually construct and send netlink messages. But in the case
you really need it, it is simple as well.</p>
<p>Having a description class, like <cite>ifaddrmsg</cite> from above, you need to:</p>
<blockquote>
<div><ul class="simple">
<li>instantiate it</li>
<li>fill the fields</li>
<li>encode the packet</li>
<li>send the encoded data</li>
</ul>
</div></blockquote>
<p>The code:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pyroute2.netlink</span> <span class="k">import</span> <span class="n">NLM_F_REQUEST</span>
<span class="kn">from</span> <span class="nn">pyroute2.netlink</span> <span class="k">import</span> <span class="n">NLM_F_ACK</span>
<span class="kn">from</span> <span class="nn">pyroute2.netlink</span> <span class="k">import</span> <span class="n">NLM_F_CREATE</span>
<span class="kn">from</span> <span class="nn">pyroute2.netlink</span> <span class="k">import</span> <span class="n">NLM_F_EXCL</span>
<span class="kn">from</span> <span class="nn">pyroute2.iproute</span> <span class="k">import</span> <span class="n">RTM_NEWADDR</span>
<span class="kn">from</span> <span class="nn">pyroute2.netlink.rtnl.ifaddrmsg</span> <span class="k">import</span> <span class="n">ifaddrmsg</span>
<span class="c1">##</span>
<span class="c1"># add an addr to an interface</span>
<span class="c1">#</span>
<span class="c1"># create the message</span>
<span class="n">msg</span> <span class="o">=</span> <span class="n">ifaddrmsg</span><span class="p">()</span>
<span class="c1"># fill the protocol-specific fields</span>
<span class="n">msg</span><span class="p">[</span><span class="s1">'index'</span><span class="p">]</span> <span class="o">=</span> <span class="n">index</span> <span class="c1"># index of the interface</span>
<span class="n">msg</span><span class="p">[</span><span class="s1">'family'</span><span class="p">]</span> <span class="o">=</span> <span class="n">AF_INET</span> <span class="c1"># address family</span>
<span class="n">msg</span><span class="p">[</span><span class="s1">'prefixlen'</span><span class="p">]</span> <span class="o">=</span> <span class="mi">24</span> <span class="c1"># the address mask</span>
<span class="n">msg</span><span class="p">[</span><span class="s1">'scope'</span><span class="p">]</span> <span class="o">=</span> <span class="n">scope</span> <span class="c1"># see /etc/iproute2/rt_scopes</span>
<span class="c1"># attach NLA -- it MUST be a list / mutable</span>
<span class="n">msg</span><span class="p">[</span><span class="s1">'attrs'</span><span class="p">]</span> <span class="o">=</span> <span class="p">[[</span><span class="s1">'IFA_LOCAL'</span><span class="p">,</span> <span class="s1">'192.168.0.1'</span><span class="p">],</span>
<span class="p">[</span><span class="s1">'IFA_ADDRESS'</span><span class="p">,</span> <span class="s1">'192.162.0.1'</span><span class="p">]]</span>
<span class="c1"># fill generic netlink fields</span>
<span class="n">msg</span><span class="p">[</span><span class="s1">'header'</span><span class="p">][</span><span class="s1">'sequence_number'</span><span class="p">]</span> <span class="o">=</span> <span class="n">nonce</span> <span class="c1"># an unique seq number</span>
<span class="n">msg</span><span class="p">[</span><span class="s1">'header'</span><span class="p">][</span><span class="s1">'pid'</span><span class="p">]</span> <span class="o">=</span> <span class="n">os</span><span class="o">.</span><span class="n">getpid</span><span class="p">()</span>
<span class="n">msg</span><span class="p">[</span><span class="s1">'header'</span><span class="p">][</span><span class="s1">'type'</span><span class="p">]</span> <span class="o">=</span> <span class="n">RTM_NEWADDR</span>
<span class="n">msg</span><span class="p">[</span><span class="s1">'header'</span><span class="p">][</span><span class="s1">'flags'</span><span class="p">]</span> <span class="o">=</span> <span class="n">NLM_F_REQUEST</span> <span class="o">|</span>\
<span class="n">NLM_F_ACK</span> <span class="o">|</span>\
<span class="n">NLM_F_CREATE</span> <span class="o">|</span>\
<span class="n">NLM_F_EXCL</span>
<span class="c1"># encode the packet</span>
<span class="n">msg</span><span class="o">.</span><span class="n">encode</span><span class="p">()</span>
<span class="c1"># send the buffer</span>
<span class="n">nlsock</span><span class="o">.</span><span class="n">sendto</span><span class="p">(</span><span class="n">msg</span><span class="o">.</span><span class="n">data</span><span class="p">,</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">))</span>
</pre></div>
</div>
<p>Please notice, that NLA list <em>MUST</em> be mutable.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Netlink</a><ul>
<li><a class="reference internal" href="#basics">basics</a></li>
<li><a class="reference internal" href="#pyroute2-and-netlink">pyroute2 and netlink</a><ul>
<li><a class="reference internal" href="#packets">packets</a></li>
<li><a class="reference internal" href="#fields-attribute">fields attribute</a></li>
<li><a class="reference internal" href="#nla-map-attribute">nla_map attribute</a></li>
<li><a class="reference internal" href="#array-types">array types</a></li>
<li><a class="reference internal" href="#parsed-netlink-message">parsed netlink message</a></li>
<li><a class="reference internal" href="#encoding-and-decoding-algo">encoding and decoding algo</a></li>
<li><a class="reference internal" href="#create-and-send-messages">create and send messages</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="arch.html"
title="previous chapter">Module architecture</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="nlsocket.html"
title="next chapter">Base netlink socket and marshal</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/netlink.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="nlsocket.html" title="Base netlink socket and marshal"
>next</a> |</li>
<li class="right" >
<a href="arch.html" title="Module architecture"
>previous</a> |</li>
<li class="nav-item"><a href="http://pyroute2.org">Project home</a> »</li>
<li class="nav-item nav-item-0"><a href="index.html">pyroute2 0.5.2 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2013, Peter V. Saveliev.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.7.2.
</div>
</body>
</html>
|
