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
|
<!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>Quickstart — 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="IPRoute module" href="iproute.html" />
<link rel="prev" title="Report a bug" href="report.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="iproute.html" title="IPRoute module"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="report.html" title="Report a bug"
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">
<div class="section" id="quickstart">
<h1>Quickstart<a class="headerlink" href="#quickstart" title="Permalink to this headline">¶</a></h1>
<p>Hello, world:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ sudo pip install pyroute2
$ cat example.py
from pyroute2 import IPRoute
with IPRoute() as ipr:
print([x.get_attr('IFLA_IFNAME') for x in ipr.get_links()])
$ python example.py
['lo', 'p6p1', 'wlan0', 'virbr0', 'virbr0-nic']
</pre></div>
</div>
<div class="section" id="sockets">
<h2>Sockets<a class="headerlink" href="#sockets" title="Permalink to this headline">¶</a></h2>
<p>In the runtime pyroute2 socket objects behave as normal
sockets. One can use them in the poll/select, one can
call <cite>recv()</cite> and <cite>sendmsg()</cite>:</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="c1"># create RTNL socket</span>
<span class="n">ipr</span> <span class="o">=</span> <span class="n">IPRoute</span><span class="p">()</span>
<span class="c1"># subscribe to broadcast messages</span>
<span class="n">ipr</span><span class="o">.</span><span class="n">bind</span><span class="p">()</span>
<span class="c1"># wait for data (do not parse it)</span>
<span class="n">data</span> <span class="o">=</span> <span class="n">ipr</span><span class="o">.</span><span class="n">recv</span><span class="p">(</span><span class="mi">65535</span><span class="p">)</span>
<span class="c1"># parse received data</span>
<span class="n">messages</span> <span class="o">=</span> <span class="n">ipr</span><span class="o">.</span><span class="n">marshal</span><span class="o">.</span><span class="n">parse</span><span class="p">(</span><span class="n">data</span><span class="p">)</span>
<span class="c1"># shortcut: recv() + parse()</span>
<span class="c1">#</span>
<span class="c1"># (under the hood is much more, but for</span>
<span class="c1"># simplicity it's enough to say so)</span>
<span class="c1">#</span>
<span class="n">messages</span> <span class="o">=</span> <span class="n">ipr</span><span class="o">.</span><span class="n">get</span><span class="p">()</span>
</pre></div>
</div>
<p>But pyroute2 objects have a lot of methods, written to
handle specific tasks:</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="c1"># RTNL interface</span>
<span class="k">with</span> <span class="n">IPRoute</span><span class="p">()</span> <span class="k">as</span> <span class="n">ipr</span><span class="p">:</span>
<span class="c1"># get devices list</span>
<span class="n">ipr</span><span class="o">.</span><span class="n">get_links</span><span class="p">()</span>
<span class="c1"># get addresses</span>
<span class="n">ipr</span><span class="o">.</span><span class="n">get_addr</span><span class="p">()</span>
</pre></div>
</div>
</div>
<div class="section" id="resource-release">
<h2>Resource release<a class="headerlink" href="#resource-release" title="Permalink to this headline">¶</a></h2>
<p>Do not forget to release resources and close sockets. Also
keep in mind, that the real fd will be closed only when the
Python GC will collect closed objects.</p>
</div>
<div class="section" id="imports">
<h2>Imports<a class="headerlink" href="#imports" title="Permalink to this headline">¶</a></h2>
<p>The public API is exported by <cite>pyroute2/__init__.py</cite>.</p>
<p>It is done so to provide a stable API that will not be affected
by changes in the package layout. There may be significant
layout changes between versions, but if a symbol is re-exported
via <cite>pyroute2/__init__.py</cite>, it will be available with the same
import signature.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">All other objects are also available for import, but they
may change signatures in the next versions.</p>
</div>
<p>E.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Import a pyroute2 class directly. In the next versions</span>
<span class="c1"># the import signature can be changed, e.g., NetNS from</span>
<span class="c1"># pyroute2.netns.nslink it can be moved somewhere else.</span>
<span class="c1">#</span>
<span class="kn">from</span> <span class="nn">pyroute2.netns.nslink</span> <span class="k">import</span> <span class="n">NetNS</span>
<span class="n">ns</span> <span class="o">=</span> <span class="n">NetNS</span><span class="p">(</span><span class="s1">'test'</span><span class="p">)</span>
<span class="c1"># Import the same class from root module. This signature</span>
<span class="c1"># will stay the same, any layout change is reflected in</span>
<span class="c1"># the root module.</span>
<span class="c1">#</span>
<span class="kn">from</span> <span class="nn">pyroute2</span> <span class="k">import</span> <span class="n">NetNS</span>
<span class="n">ns</span> <span class="o">=</span> <span class="n">NetNS</span><span class="p">(</span><span class="s1">'test'</span><span class="p">)</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="special-cases">
<h1>Special cases<a class="headerlink" href="#special-cases" title="Permalink to this headline">¶</a></h1>
<div class="section" id="eventlet">
<h2>eventlet<a class="headerlink" href="#eventlet" title="Permalink to this headline">¶</a></h2>
<p>The eventlet environment conflicts in some way with socket
objects, and pyroute2 provides some workaround for that:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># import symbols</span>
<span class="c1">#</span>
<span class="kn">import</span> <span class="nn">eventlet</span>
<span class="kn">from</span> <span class="nn">pyroute2</span> <span class="k">import</span> <span class="n">NetNS</span>
<span class="kn">from</span> <span class="nn">pyroute2.config.eventlet</span> <span class="k">import</span> <span class="n">eventlet_config</span>
<span class="c1"># setup the environment</span>
<span class="n">eventlet</span><span class="o">.</span><span class="n">monkey_patch</span><span class="p">()</span>
<span class="n">eventlet_config</span><span class="p">()</span>
<span class="c1"># run the code</span>
<span class="n">ns</span> <span class="o">=</span> <span class="n">NetNS</span><span class="p">(</span><span class="s1">'nsname'</span><span class="p">)</span>
<span class="n">ns</span><span class="o">.</span><span class="n">get_routes</span><span class="p">()</span>
<span class="o">...</span>
</pre></div>
</div>
<p>This may help, but not always. In general, the pyroute2 library
is not eventlet-friendly.</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="#">Quickstart</a><ul>
<li><a class="reference internal" href="#sockets">Sockets</a></li>
<li><a class="reference internal" href="#resource-release">Resource release</a></li>
<li><a class="reference internal" href="#imports">Imports</a></li>
</ul>
</li>
<li><a class="reference internal" href="#special-cases">Special cases</a><ul>
<li><a class="reference internal" href="#eventlet">eventlet</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="report.html"
title="previous chapter">Report a bug</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="iproute.html"
title="next chapter">IPRoute module</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/usage.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="iproute.html" title="IPRoute module"
>next</a> |</li>
<li class="right" >
<a href="report.html" title="Report a bug"
>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>
|
