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
|
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>Module architecture — pyroute2 0.5.14 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" type="text/css" href="_static/graphviz.css" />
<link rel="stylesheet" type="text/css" href="_static/custom.css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" 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>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Netlink" href="netlink.html" />
<link rel="prev" title="Project contribution guide" href="devcontribute.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="netlink.html" title="Netlink"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="devcontribute.html" title="Project contribution guide"
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.14 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="module-architecture">
<h1>Module architecture<a class="headerlink" href="#module-architecture" title="Permalink to this headline">¶</a></h1>
<div class="section" id="sockets">
<h2>Sockets<a class="headerlink" href="#sockets" title="Permalink to this headline">¶</a></h2>
<p>The idea behind the pyroute2 framework is pretty simple. The
library provides socket objects, that have:</p>
<ul class="simple">
<li><p>shortcuts to establish netlink connections</p></li>
<li><p>extra methods to run netlink queries</p></li>
<li><p>some magic to handle packet bursts</p></li>
<li><p>another magic to transparently mangle netlink messages</p></li>
</ul>
<p>In other sense any netlink socket is just an ordinary socket
with <cite>fileno()</cite>, <cite>recv()</cite>, <cite>sendto()</cite> etc. Of course, one
can use it in <cite>poll()</cite>.</p>
<p>There is an inheritance diagram of Linux netlink sockets, provided
by the library:</p>
<div class="graphviz"><img src="_images/inheritance-6035fd9e0ca43ffda970d708c97640efbf571808.png" alt="Inheritance diagram of pyroute2.iproute.linux.IPRoute, pyroute2.iproute.linux.IPBatch, pyroute2.iproute.linux.RawIPRoute, pyroute2.iproute.RemoteIPRoute, pyroute2.iwutil.IW, pyroute2.ipset.IPSet, pyroute2.netlink.uevent.UeventSocket, pyroute2.netlink.taskstats.TaskStats, pyroute2.netlink.generic.wireguard.WireGuard, pyroute2.netlink.generic.ethtool.NlEthtool, pyroute2.netlink.ipq.IPQSocket, pyroute2.netlink.nfnetlink.nfctsocket.NFCTSocket, pyroute2.netlink.nfnetlink.nftsocket.NFTSocket, pyroute2.netlink.event.EventSocket, pyroute2.netlink.event.acpi_event.AcpiEventSocket, pyroute2.netlink.event.dquot.DQuotSocket, pyroute2.netlink.event.thermal_event.ThermalEventSocket, pyroute2.netlink.devlink.DevlinkSocket, pyroute2.netlink.diag.DiagSocket, pyroute2.remote.RemoteSocket, pyroute2.remote.shell.ShellIPR, pyroute2.netns.nslink.NetNS" usemap="#inheritance2ee30167cf" class="inheritance graphviz" /></div>
<map id="inheritance2ee30167cf" name="inheritance2ee30167cf">
<area shape="rect" id="node3" href="nlsocket.html#pyroute2.netlink.nlsocket.BatchSocket" target="_top" title="BatchSocket" alt="" coords="156,131,243,152"/>
<area shape="rect" id="node4" href="nlsocket.html#pyroute2.netlink.nlsocket.NetlinkMixin" target="_top" title="Generic netlink socket" alt="" coords="5,131,94,152"/>
<area shape="rect" id="node9" href="nlsocket.html#pyroute2.netlink.nlsocket.NetlinkSocket" target="_top" title="NetlinkSocket" alt="" coords="152,362,247,383"/>
<area shape="rect" id="node17" href="ipset.html#pyroute2.ipset.IPSet" target="_top" title="NFNetlink socket (family=NETLINK_NETFILTER)." alt="" coords="344,383,405,405"/>
<area shape="rect" id="node10" href="iproute.html#pyroute2.iproute.linux.IPBatch" target="_top" title="Netlink requests compiler. Does not send any requests, but" alt="" coords="506,131,568,152"/>
<area shape="rect" id="node11" href="iproute.html#pyroute2.iproute.linux.RTNL_API" target="_top" title="`RTNL_API` should not be instantiated by itself. It is intended" alt="" coords="339,89,410,110"/>
<area shape="rect" id="node16" href="iproute.html#pyroute2.iproute.linux.IPRoute" target="_top" title="Regular ordinary utility class, see RTNL API for the list of methods." alt="" coords="506,173,568,195"/>
<area shape="rect" id="node22" href="netns.html#pyroute2.netns.nslink.NetNS" target="_top" title="NetNS is the IPRoute API with network namespace support." alt="" coords="506,5,568,26"/>
<area shape="rect" id="node27" href="iproute.html#pyroute2.iproute.linux.RawIPRoute" target="_top" title="The same as `IPRoute`, but does not use the netlink proxy." alt="" coords="494,215,580,237"/>
<area shape="rect" id="node18" href="devmodules.html#pyroute2.iwutil.IW" target="_top" title="IW" alt="" coords="666,468,728,489"/>
</map><div class="section" id="under-the-hood">
<h3>under the hood<a class="headerlink" href="#under-the-hood" title="Permalink to this headline">¶</a></h3>
<p>Let’s assume we use an <cite>IPRoute</cite> object to get the
interface list of the system:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">pyroute2</span> <span class="k">import</span> <span class="n">IPRoute</span>
<span class="n">ipr</span> <span class="o">=</span> <span class="n">IPRoute</span><span class="p">()</span>
<span class="n">ipr</span><span class="o">.</span><span class="n">get_links</span><span class="p">()</span>
<span class="n">ipr</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
<p>The <cite>get_links()</cite> method is provided by the <cite>IPRouteMixin</cite>
class. It chooses the message to send (<cite>ifinfmsg</cite>), prepares
required fields and passes it to the next layer:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">result</span><span class="o">.</span><span class="n">extend</span><span class="p">(</span><span class="bp">self</span><span class="o">.</span><span class="n">nlm_request</span><span class="p">(</span><span class="n">msg</span><span class="p">,</span> <span class="n">RTM_GETLINK</span><span class="p">,</span> <span class="n">msg_flags</span><span class="p">))</span>
</pre></div>
</div>
<p>The <cite>nlm_request()</cite> is a method of the <cite>NetlinkMixin</cite> class.
It wraps the pair request/response in one method. The request
is done via <cite>put()</cite>, response comes with <cite>get()</cite>. These
methods hide under the hood the asynchronous nature of the
netlink protocol, where the response can come whenever –
the time and packet order are not guaranteed. But one can
use the <cite>sequence_number</cite> field of a netlink message to
match responses, and the pair <cite>put()/get()</cite> does it.</p>
</div>
<div class="section" id="cache-thread">
<h3>cache thread<a class="headerlink" href="#cache-thread" title="Permalink to this headline">¶</a></h3>
<p>Sometimes it is preferrable to get incoming messages asap
and parse them only when there is time for that. For that
case the <cite>NetlinkMixin</cite> provides a possibility to start a
dedicated cache thread, that will collect and queue incoming
messages as they arrive. The thread doesn’t affect the
socket behaviour: it will behave exactly in the same way,
the only difference is that <cite>recv()</cite> will return already
cached in the userspace message. To start the thread,
one should call <cite>bind()</cite> with <cite>async_cache=True</cite>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ipr</span> <span class="o">=</span> <span class="n">IPRoute</span><span class="p">()</span>
<span class="n">ipr</span><span class="o">.</span><span class="n">bind</span><span class="p">(</span><span class="n">async_cache</span><span class="o">=</span><span class="kc">True</span><span class="p">)</span>
<span class="o">...</span> <span class="c1"># do some stuff</span>
<span class="n">ipr</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="message-mangling">
<h3>message mangling<a class="headerlink" href="#message-mangling" title="Permalink to this headline">¶</a></h3>
<p>An interesting feature of the <cite>IPRSocketMixin</cite> is a netlink
proxy code, that allows to register callbacks for different
message types. The callback API is simple. The callback
must accept the message as a binary data, and must return
a dictionary with two keys, <cite>verdict</cite> and <cite>data</cite>. The
verdict can be:</p>
<blockquote>
<div><ul class="simple">
<li><p>for <cite>sendto()</cite>: <cite>forward</cite>, <cite>return</cite> or <cite>error</cite></p></li>
<li><p>for <cite>recv()</cite>: <cite>forward</cite> or <cite>error</cite></p></li>
</ul>
</div></blockquote>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">msg</span> <span class="o">=</span> <span class="n">ifinfmsg</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="n">msg</span><span class="o">.</span><span class="n">decode</span><span class="p">()</span>
<span class="o">...</span> <span class="c1"># mangle msg</span>
<span class="n">msg</span><span class="o">.</span><span class="n">reset</span><span class="p">()</span>
<span class="n">msg</span><span class="o">.</span><span class="n">encode</span><span class="p">()</span>
<span class="k">return</span> <span class="p">{</span><span class="s1">'verdict'</span><span class="p">:</span> <span class="s1">'forward'</span><span class="p">,</span>
<span class="s1">'data'</span><span class="p">:</span> <span class="n">msg</span><span class="o">.</span><span class="n">buf</span><span class="o">.</span><span class="n">getvalue</span><span class="p">()}</span>
</pre></div>
</div>
<p>The <cite>error</cite> verdict raises an exception from <cite>data</cite>. The
<cite>forward</cite> verdict causes the <cite>data</cite> to be passed. The
<cite>return</cite> verdict is valid only in <cite>sendto()</cite> callbacks and
means that the <cite>data</cite> should not be passed to the kernel,
but instead it must be returned to the user.</p>
<p>This magic allows the library to transparently support
ovs, teamd, tuntap calls via netlink. The corresponding
callbacks transparently route the call to an external
utility or to <cite>ioctl()</cite> API.</p>
<p>How to register callbacks, see <cite>IPRSocketMixin</cite> init.
The <cite>_sproxy</cite> serves <cite>sendto()</cite> mangling, the <cite>_rproxy</cite>
serves the <cite>recv()</cite> mangling. Later this API can become
public.</p>
</div>
</div>
<div class="section" id="netlink-messages">
<h2>Netlink messages<a class="headerlink" href="#netlink-messages" title="Permalink to this headline">¶</a></h2>
<p>To handle the data going through the sockets, the library
uses different message classes. To create a custom message
type, one should inherit:</p>
<blockquote>
<div><ul class="simple">
<li><p><cite>nlmsg</cite> to create a netlink message class</p></li>
<li><p><cite>genlmsg</cite> to create generic netlink message class</p></li>
<li><p><cite>nla</cite> to create a NLA class</p></li>
</ul>
</div></blockquote>
<p>The messages hierarchy:</p>
<div class="graphviz"><img src="_images/inheritance-bde6ffba82b9ceab696201ccc375e591464595d0.png" alt="Inheritance diagram of pyroute2.netlink.rtnl.ndmsg.ndmsg, pyroute2.netlink.rtnl.ndtmsg.ndtmsg, pyroute2.netlink.rtnl.tcmsg.tcmsg, pyroute2.netlink.rtnl.rtmsg.nlflags, pyroute2.netlink.rtnl.rtmsg.rtmsg_base, pyroute2.netlink.rtnl.rtmsg.rtmsg, pyroute2.netlink.rtnl.rtmsg.nh, pyroute2.netlink.rtnl.fibmsg.fibmsg, pyroute2.netlink.rtnl.ifaddrmsg.ifaddrmsg, pyroute2.netlink.rtnl.ifstatsmsg.ifstatsmsg, pyroute2.netlink.rtnl.ifinfmsg.ifinfmsg, pyroute2.netlink.rtnl.ifinfmsg.ifinfveth, pyroute2.netlink.rtnl.iw_event.iw_event, pyroute2.netlink.rtnl.nsidmsg.nsidmsg, pyroute2.netlink.rtnl.nsinfmsg.nsinfmsg, pyroute2.netlink.rtnl.rtgenmsg.rtgenmsg, pyroute2.netlink.devlink.devlinkcmd, pyroute2.netlink.diag.inet_addr_codec, pyroute2.netlink.diag.inet_diag_req, pyroute2.netlink.diag.inet_diag_msg, pyroute2.netlink.diag.unix_diag_req, pyroute2.netlink.diag.unix_diag_msg, pyroute2.netlink.event.acpi_event.acpimsg, pyroute2.netlink.event.dquot.dquotmsg, pyroute2.netlink.event.thermal_event.thermal_msg, pyroute2.netlink.taskstats.taskstatsmsg, pyroute2.netlink.taskstats.tcmd, pyroute2.netlink.generic.ethtool.ethtool_strset_msg, pyroute2.netlink.generic.ethtool.ethtool_linkinfo_msg, pyroute2.netlink.generic.ethtool.ethtool_linkmode_msg, pyroute2.netlink.generic.ethtool.ethtool_linkstate_msg, pyroute2.netlink.generic.ethtool.ethtool_wol_msg, pyroute2.netlink.generic.wireguard.wgmsg, pyroute2.netlink.ctrlmsg, pyroute2.netlink.genlmsg, pyroute2.netlink.nl80211.nl80211cmd, pyroute2.netlink.nfnetlink.ipset.ipset_msg, pyroute2.netlink.nfnetlink.nfgen_msg, pyroute2.netlink.nfnetlink.nftsocket.nft_gen_msg, pyroute2.netlink.nfnetlink.nftsocket.nft_chain_msg, pyroute2.netlink.nfnetlink.nftsocket.nft_rule_msg, pyroute2.netlink.nfnetlink.nftsocket.nft_set_msg, pyroute2.netlink.nfnetlink.nftsocket.nft_table_msg, pyroute2.netlink.nfnetlink.nfctsocket.nfct_stats, pyroute2.netlink.nfnetlink.nfctsocket.nfct_stats_cpu, pyroute2.netlink.nfnetlink.nfctsocket.nfct_msg, pyroute2.netlink.ipq.ipq_mode_msg, pyroute2.netlink.ipq.ipq_packet_msg, pyroute2.netlink.ipq.ipq_verdict_msg, pyroute2.netlink.uevent.ueventmsg" class="inheritance graphviz" /></div>
</div>
<div class="section" id="pf-route-messages">
<h2>PF_ROUTE messages<a class="headerlink" href="#pf-route-messages" title="Permalink to this headline">¶</a></h2>
<p>PF_ROUTE socket is used to receive notifications from the BSD
kernel. The PF_ROUTE messages:</p>
<div class="graphviz"><img src="_images/inheritance-3f838403cee8909e49dd6d8f69421e420ada5b44.png" alt="Inheritance diagram of pyroute2.bsd.pf_route.freebsd.bsdmsg, pyroute2.bsd.pf_route.freebsd.if_msg, pyroute2.bsd.pf_route.freebsd.rt_msg_base, pyroute2.bsd.pf_route.freebsd.ifa_msg_base, pyroute2.bsd.pf_route.freebsd.ifma_msg_base, pyroute2.bsd.pf_route.freebsd.if_announcemsg, pyroute2.bsd.pf_route.rt_slot, pyroute2.bsd.pf_route.rt_msg, pyroute2.bsd.pf_route.ifa_msg, pyroute2.bsd.pf_route.ifma_msg" class="inheritance graphviz" /></div>
</div>
<div class="section" id="ipdb">
<h2>IPDB<a class="headerlink" href="#ipdb" title="Permalink to this headline">¶</a></h2>
<p>The <cite>IPDB</cite> module implements high-level logic to manage
some of the system network settings. It is completely
agnostic to the netlink object’s nature, the only requirement
is that the netlink transport must provide RTNL API.</p>
<p>So, using proper mixin classes one can create a custom
RTNL-compatible transport. E.g., this way <cite>IPDB</cite> can work
over <cite>NetNS</cite> objects, providing the network management
within some network namespace — while itself it runs in the
main namespace.</p>
<p>The <cite>IPDB</cite> architecture is not too complicated, but it
implements some useful transaction magic, see <cite>commit()</cite>
methods of the <cite>Transactional</cite> objects.</p>
<div class="graphviz"><img src="_images/inheritance-0c1b6bf9bf282e1cdae685cfce6a116f7a75a086.png" alt="Inheritance diagram of pyroute2.ipdb.main.IPDB, pyroute2.ipdb.interfaces.Interface, pyroute2.ipdb.linkedset.LinkedSet, pyroute2.ipdb.linkedset.IPaddrSet, pyroute2.ipdb.routes.NextHopSet, pyroute2.ipdb.routes.Via, pyroute2.ipdb.routes.Encap, pyroute2.ipdb.routes.Metrics, pyroute2.ipdb.routes.BaseRoute, pyroute2.ipdb.routes.Route, pyroute2.ipdb.routes.MPLSRoute, pyroute2.ipdb.routes.RoutingTable, pyroute2.ipdb.routes.MPLSTable, pyroute2.ipdb.routes.RoutingTableSet, pyroute2.ipdb.rules.Rule, pyroute2.ipdb.rules.RulesDict" usemap="#inheritancebd2219997f" class="inheritance graphviz" /></div>
<map id="inheritancebd2219997f" name="inheritancebd2219997f">
<area shape="rect" id="node5" href="ipdb.html#pyroute2.ipdb.main.IPDB" target="_top" title="The class that maintains information about network setup" alt="" coords="33,227,105,252"/>
</map></div>
<div class="section" id="internet-protocols">
<h2>Internet protocols<a class="headerlink" href="#internet-protocols" title="Permalink to this headline">¶</a></h2>
<p>Beside of the netlink protocols, the library implements a
limited set of supplementary internet protocol to play with.</p>
<div class="graphviz"><img src="_images/inheritance-ed0c595ce08d01c093a63434be8747972b9d1183.png" alt="Inheritance diagram of pyroute2.protocols.udpmsg, pyroute2.protocols.ip4msg, pyroute2.protocols.udp4_pseudo_header, pyroute2.protocols.ethmsg, pyroute2.dhcp.dhcp4msg.dhcp4msg" usemap="#inheritance15756ada77" class="inheritance graphviz" /></div>
<map id="inheritance15756ada77" name="inheritance15756ada77">
<area shape="rect" id="node2" href="dhcp.html#pyroute2.dhcp.dhcpmsg" target="_top" title="dhcpmsg" alt="" coords="165,5,246,31"/>
</map></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="#">Module architecture</a><ul>
<li><a class="reference internal" href="#sockets">Sockets</a><ul>
<li><a class="reference internal" href="#under-the-hood">under the hood</a></li>
<li><a class="reference internal" href="#cache-thread">cache thread</a></li>
<li><a class="reference internal" href="#message-mangling">message mangling</a></li>
</ul>
</li>
<li><a class="reference internal" href="#netlink-messages">Netlink messages</a></li>
<li><a class="reference internal" href="#pf-route-messages">PF_ROUTE messages</a></li>
<li><a class="reference internal" href="#ipdb">IPDB</a></li>
<li><a class="reference internal" href="#internet-protocols">Internet protocols</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="devcontribute.html"
title="previous chapter">Project contribution guide</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="netlink.html"
title="next chapter">Netlink</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/arch.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</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="netlink.html" title="Netlink"
>next</a> |</li>
<li class="right" >
<a href="devcontribute.html" title="Project contribution guide"
>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.14 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> 2.1.2.
</div>
</body>
</html>
|
