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
|
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>NDB module — 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="NDB objects" href="ndb_init.html" />
<link rel="prev" title="RemoteIPRoute" href="remote.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="ndb_init.html" title="NDB objects"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="remote.html" title="RemoteIPRoute"
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="ndb-module">
<span id="ndb"></span><h1>NDB module<a class="headerlink" href="#ndb-module" title="Permalink to this headline">¶</a></h1>
<p>NDB is a high level network management module. IT allows to manage interfaces,
routes, addresses etc. of connected systems, containers and network
namespaces.</p>
<p>In a nuthsell, NDB collects and aggregates netlink events in an SQL database,
provides Python objects to reflect the system state, and applies changes back
to the system. The database expects updates only from the sources, no manual
SQL updates are expected normally.</p>
<a class="reference internal image-reference" href="_images/aafig-80bc0b850cd3f4d027d8d72e97c7fc1b52fe5bca.svg"><img alt="_images/aafig-80bc0b850cd3f4d027d8d72e97c7fc1b52fe5bca.svg" height="566.0" src="_images/aafig-80bc0b850cd3f4d027d8d72e97c7fc1b52fe5bca.svg" width="790.0000000000001" /></a>
<p>NDB can work with remote systems via ssh, in that case
<a class="reference external" href="https://github.com/dw/mitogen">mitogen</a> module is required. It is
possible to connect also OpenBSD and FreeBSD systems, but in read-only
mode for now.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>See also the module choice guide: <a class="reference internal" href="choice.html#choice"><span class="std std-ref">IPRoute or NDB</span></a></p>
</div>
<span class="target" id="module-pyroute2.ndb.main"></span><div class="section" id="quick-start">
<h2>Quick start<a class="headerlink" href="#quick-start" title="Permalink to this headline">¶</a></h2>
<p>The goal of NDB is to provide an easy access to RTNL info and entities via
Python objects, like <cite>pyroute2.ndb.objects.interface</cite> (see also:
<a class="reference internal" href="ndb_interfaces.html#ndbinterfaces"><span class="std std-ref">Network interfaces</span></a>), <cite>pyroute2.ndb.objects.route</cite> (see also:
<a class="reference internal" href="ndb_routes.html#ndbroutes"><span class="std std-ref">Routes management</span></a>) etc. These objects do not
only reflect the system state for the time of their instantiation, but
continuously monitor the system for relevant updates. The monitoring is
done via netlink notifications, thus no polling. Also the objects allow
to apply changes back to the system and rollback the changes.</p>
<p>On the other hand it’s too expensive to create Python objects for all the
available RTNL entities, e.g. when there are hundreds of interfaces and
thousands of routes. Thus NDB creates objects only upon request, when
the user calls <cite>.create()</cite> to create new objects or runs
<cite>ndb.<view>[selector]</cite> (e.g. <cite>ndb.interfaces[‘eth0’]</cite>) to access an
existing object.</p>
<p>To list existing RTNL entities NDB uses objects of the class <cite>RecordSet</cite>
that <cite>yield</cite> individual <cite>Record</cite> objects for every entity (see also:
<a class="reference internal" href="ndb_reports.html#ndbreports"><span class="std std-ref">Record list filters</span></a>). An object of the <cite>Record</cite> class is immutable, doesn’t
monitor any updates, doesn’t contain any links to other objects and essentially
behaves like a simple named tuple.</p>
<a class="reference internal image-reference" href="_images/aafig-db02be09e1d33d12b493455bdfd27b7ad0692510.svg"><img alt="_images/aafig-db02be09e1d33d12b493455bdfd27b7ad0692510.svg" height="666.8000000000001" src="_images/aafig-db02be09e1d33d12b493455bdfd27b7ad0692510.svg" width="846.0000000000001" /></a>
<p>Here are some simple NDB usage examples. More info see in the reference
documentation below.</p>
<p>Print all the interface names on the system, assume we have an NDB
instance <cite>ndb</cite>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">interface</span> <span class="ow">in</span> <span class="n">ndb</span><span class="o">.</span><span class="n">interfaces</span><span class="o">.</span><span class="n">dump</span><span class="p">():</span>
<span class="nb">print</span><span class="p">(</span><span class="n">interface</span><span class="o">.</span><span class="n">ifname</span><span class="p">)</span>
</pre></div>
</div>
<p>Print the routing information in the CSV format:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">ndb</span><span class="o">.</span><span class="n">routes</span><span class="o">.</span><span class="n">summary</span><span class="p">()</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="s1">'csv'</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="n">record</span><span class="p">)</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>More on report filtering and formatting: <a class="reference internal" href="ndb_reports.html#ndbreports"><span class="std std-ref">Record list filters</span></a></p>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Since 0.5.11; versions 0.5.10 and earlier used
syntax <cite>summary(format=’csv’, match={…})</cite></p>
</div>
<p>Print IP addresses of interfaces in several network namespaces as:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">nslist</span> <span class="o">=</span> <span class="p">[</span><span class="s1">'netns01'</span><span class="p">,</span>
<span class="s1">'netns02'</span><span class="p">,</span>
<span class="s1">'netns03'</span><span class="p">]</span>
<span class="k">for</span> <span class="n">nsname</span> <span class="ow">in</span> <span class="n">nslist</span><span class="p">:</span>
<span class="n">ndb</span><span class="o">.</span><span class="n">sources</span><span class="o">.</span><span class="n">add</span><span class="p">(</span><span class="n">netns</span><span class="o">=</span><span class="n">nsname</span><span class="p">)</span>
<span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">ndb</span><span class="o">.</span><span class="n">addresses</span><span class="o">.</span><span class="n">summary</span><span class="p">()</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="s1">'json'</span><span class="p">):</span>
<span class="nb">print</span><span class="p">(</span><span class="n">line</span><span class="p">)</span>
</pre></div>
</div>
<p>Add an IP address on an interface:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">ndb</span>
<span class="o">.</span><span class="n">interfaces</span><span class="p">[</span><span class="s1">'eth0'</span><span class="p">]</span>
<span class="o">.</span><span class="n">add_ip</span><span class="p">(</span><span class="s1">'10.0.0.1/24'</span><span class="p">)</span>
<span class="o">.</span><span class="n">commit</span><span class="p">())</span>
<span class="c1"># ---> <--- NDB waits until the address actually</span>
</pre></div>
</div>
<p>Change an interface property:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="p">(</span><span class="n">ndb</span>
<span class="o">.</span><span class="n">interfaces</span><span class="p">[</span><span class="s1">'eth0'</span><span class="p">]</span>
<span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'state'</span><span class="p">,</span> <span class="s1">'up'</span><span class="p">)</span>
<span class="o">.</span><span class="n">set</span><span class="p">(</span><span class="s1">'address'</span><span class="p">,</span> <span class="s1">'00:11:22:33:44:55'</span><span class="p">)</span>
<span class="o">.</span><span class="n">commit</span><span class="p">()</span>
<span class="c1"># ---> <--- NDB waits here for the changes to be applied</span>
<span class="c1"># ... or with another syntax</span>
<span class="k">with</span> <span class="n">ndb</span><span class="o">.</span><span class="n">interfaces</span><span class="p">[</span><span class="s1">'eth0'</span><span class="p">]</span> <span class="k">as</span> <span class="n">i</span><span class="p">:</span>
<span class="n">i</span><span class="p">[</span><span class="s1">'state'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'up'</span>
<span class="n">i</span><span class="p">[</span><span class="s1">'address'</span><span class="p">]</span> <span class="o">=</span> <span class="s1">'00:11:22:33:44:55'</span>
<span class="c1"># ---> <--- the commit() is called authomatically by</span>
<span class="c1"># the context manager's __exit__()</span>
</pre></div>
</div>
</div>
<div class="section" id="reference">
<h2>Reference<a class="headerlink" href="#reference" title="Permalink to this headline">¶</a></h2>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="ndb_init.html">NDB objects</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ndb_init.html#start">Start</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_init.html#stop">Stop</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ndb_objects.html">Views and objects</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ndb_objects.html#structure">Structure</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_objects.html#accessing-objects">Accessing objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_objects.html#objects-cache">Objects cache</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_objects.html#api">API</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ndb_reports.html">Record list filters</a></li>
<li class="toctree-l1"><a class="reference internal" href="ndb_interfaces.html">Network interfaces</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ndb_interfaces.html#list-interfaces">List interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_interfaces.html#get-interface-objects">Get interface objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_interfaces.html#change-nic-properties">Change nic properties</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_interfaces.html#create-virtual-interfaces">Create virtual interfaces</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ndb_addresses.html">IP addresses management</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ndb_addresses.html#using-the-view">Using the view</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_addresses.html#using-interfaces">Using interfaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_addresses.html#accessing-one-address-details">Accessing one address details</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ndb_routes.html">Routes management</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ndb_routes.html#simple-routes">Simple routes</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_routes.html#multiple-routing-tables">Multiple routing tables</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_routes.html#route-metrics">Route metrics</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_routes.html#mpls-routes">MPLS routes</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ndb_schema.html">Database</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ndb_schema.html#backends">Backends</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_schema.html#sql-schema">SQL schema</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ndb_sources.html">RTNL sources</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ndb_sources.html#local-rtnl">Local RTNL</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_sources.html#network-namespaces">Network namespaces</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_sources.html#remote-systems">Remote systems</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ndb_debug.html">Debug and logging</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ndb_debug.html#logging">Logging</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_debug.html#fetching-db-data">Fetching DB data</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_debug.html#rtnl-events">RTNL events</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_debug.html#rtnl-objects">RTNL objects</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_debug.html#object-states">Object states</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_debug.html#object-snapshots">Object snapshots</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="ndb_auth.html">Authorization plugins</a><ul>
<li class="toctree-l2"><a class="reference internal" href="ndb_auth.html#aaa-concept">AAA concept</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_auth.html#authmanager">AuthManager</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_auth.html#usecase-openstack-keystone-auth">Usecase: OpenStack Keystone auth</a></li>
<li class="toctree-l2"><a class="reference internal" href="ndb_auth.html#usecase-radius-auth">Usecase: RADIUS auth</a></li>
</ul>
</li>
</ul>
</div>
<p><em>work in progress</em></p>
</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="#">NDB module</a><ul>
<li><a class="reference internal" href="#quick-start">Quick start</a></li>
<li><a class="reference internal" href="#reference">Reference</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="remote.html"
title="previous chapter">RemoteIPRoute</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="ndb_init.html"
title="next chapter">NDB objects</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/ndb.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="ndb_init.html" title="NDB objects"
>next</a> |</li>
<li class="right" >
<a href="remote.html" title="RemoteIPRoute"
>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>
|
