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
|
<!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>DHCP support — 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" />
</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="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="dhcp-support">
<h1>DHCP support<a class="headerlink" href="#dhcp-support" title="Permalink to this headline">¶</a></h1>
<p>DHCP support in <cite>pyroute2</cite> is in very initial state, so it is
in the «Development section» yet. DHCP protocol has nothing
to do with netlink, but <cite>pyroute2</cite> slowly moving from
netlink-only library to some more general networking
framework.</p>
<span class="target" id="module-pyroute2.dhcp"></span><div class="section" id="dhcp-protocol">
<h2>DHCP protocol<a class="headerlink" href="#dhcp-protocol" title="Permalink to this headline">¶</a></h2>
<p>The DHCP implementation here is far from complete, but
already provides some basic functionality. Later it will
be extended with IPv6 support and more DHCP options
will be added.</p>
<p>Right now it can be interesting mostly to developers,
but not users and/or system administrators. So, the
development hints first.</p>
<p>The packet structure description is intentionally
implemented as for netlink packets. Later these two
parsers, netlink and generic, can be merged, so the
syntax is more or less compatible.</p>
<div class="section" id="packet-fields">
<h3>Packet fields<a class="headerlink" href="#packet-fields" title="Permalink to this headline">¶</a></h3>
<p>There are two big groups of items within any DHCP packet.
First, there are BOOTP/DHCP packet fields, they’re defined
with the <cite>fields</cite> attribute:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">dhcp4msg</span><span class="p">(</span><span class="n">msg</span><span class="p">):</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">((</span><span class="n">name</span><span class="p">,</span> <span class="nb">format</span><span class="p">,</span> <span class="n">policy</span><span class="p">),</span>
<span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="nb">format</span><span class="p">,</span> <span class="n">policy</span><span class="p">),</span>
<span class="o">...</span>
<span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="nb">format</span><span class="p">,</span> <span class="n">policy</span><span class="p">))</span>
</pre></div>
</div>
<p>The <cite>name</cite> can be any literal. Format should be specified
as for the struct module, like <cite>B</cite> for <cite>uint8</cite>, or <cite>i</cite> for
<cite>int32</cite>, or <cite>>Q</cite> for big-endian uint64. There are also
aliases defined, so one can write <cite>uint8</cite> or <cite>be16</cite>, or
like that. Possible aliases can be seen in the
<cite>pyroute2.protocols</cite> module.</p>
<p>The <cite>policy</cite> is a bit complicated. It can be a number or
literal, and it will mean that it is a default value, that
should be encoded if no other value is given.</p>
<p>But when the <cite>policy</cite> is a dictionary, it can contain keys
as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="s1">'l2addr'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'format'</span><span class="p">:</span> <span class="s1">'6B'</span><span class="p">,</span>
<span class="s1">'decode'</span><span class="p">:</span> <span class="o">...</span><span class="p">,</span>
<span class="s1">'encode'</span><span class="p">:</span> <span class="o">...</span><span class="p">}</span>
</pre></div>
</div>
<p>Keys <cite>encode</cite> and <cite>decode</cite> should contain filters to be used
in decoding and encoding procedures. The encoding filter
should accept the value from user’s definition and should
return a value that can be packed using <cite>format</cite>. The decoding
filter should accept a value, decoded according to <cite>format</cite>,
and should return value that can be used by a user.</p>
<p>The <cite>struct</cite> module can not decode IP addresses etc, so they
should be decoded as <cite>4s</cite>, e.g. Further transformation from
4 bytes string to a string like ‘10.0.0.1’ performs the filter.</p>
</div>
<div class="section" id="dhcp-options">
<h3>DHCP options<a class="headerlink" href="#dhcp-options" title="Permalink to this headline">¶</a></h3>
<p>DHCP options are described in a similar way:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">options</span> <span class="o">=</span> <span class="p">((</span><span class="n">code</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="nb">format</span><span class="p">),</span>
<span class="p">(</span><span class="n">code</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="nb">format</span><span class="p">),</span>
<span class="o">...</span>
<span class="p">(</span><span class="n">code</span><span class="p">,</span> <span class="n">name</span><span class="p">,</span> <span class="nb">format</span><span class="p">))</span>
</pre></div>
</div>
<p>Code is a <cite>uint8</cite> value, name can be any string literal. Format
is a string, that must have a corresponding class, inherited from
<cite>pyroute2.dhcp.option</cite>. One can find these classes in
<cite>pyroute2.dhcp</cite> (more generic) or in <cite>pyroute2.dhcp.dhcp4msg</cite>
(IPv4-specific). The option class must reside within dhcp message
class.</p>
<p>Every option class can be decoded in two ways. If it has fixed
width fields, it can be decoded with ordinary <cite>msg</cite> routines, and
in this case it can look like that:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">client_id</span><span class="p">(</span><span class="n">option</span><span class="p">):</span>
<span class="n">fields</span> <span class="o">=</span> <span class="p">((</span><span class="s1">'type'</span><span class="p">,</span> <span class="s1">'uint8'</span><span class="p">),</span>
<span class="p">(</span><span class="s1">'key'</span><span class="p">,</span> <span class="s1">'l2addr'</span><span class="p">))</span>
</pre></div>
</div>
<p>If it must be decoded by some custom rules, one can define the
policy just like for the fields above:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">class</span> <span class="nc">array8</span><span class="p">(</span><span class="n">option</span><span class="p">):</span>
<span class="n">policy</span> <span class="o">=</span> <span class="p">{</span><span class="s1">'format'</span><span class="p">:</span> <span class="s1">'string'</span><span class="p">,</span>
<span class="s1">'encode'</span><span class="p">:</span> <span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">array</span><span class="p">(</span><span class="s1">'B'</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span><span class="o">.</span><span class="n">tobytes</span><span class="p">(),</span>
<span class="s1">'decode'</span><span class="p">:</span> <span class="k">lambda</span> <span class="n">x</span><span class="p">:</span> <span class="n">array</span><span class="p">(</span><span class="s1">'B'</span><span class="p">,</span> <span class="n">x</span><span class="p">)</span><span class="o">.</span><span class="n">tolist</span><span class="p">()}</span>
</pre></div>
</div>
<p>In the corresponding modules, like in <cite>pyroute2.dhcp.dhcp4msg</cite>,
one can define as many custom DHCP options, as one need. Just
be sure, that they are compatible with the DHCP server and all
fit into 1..254 (<cite>uint8</cite>) – the 0 code is used for padding and
the code 255 is the end of options code.</p>
<dl class="class">
<dt id="pyroute2.dhcp.array">
<em class="property">class </em><code class="descclassname">pyroute2.dhcp.</code><code class="descname">array</code><a class="headerlink" href="#pyroute2.dhcp.array" title="Permalink to this definition">¶</a></dt>
<dd><dl class="method">
<dt id="pyroute2.dhcp.array.tobytes">
<code class="descname">tobytes</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.array.tobytes" title="Permalink to this definition">¶</a></dt>
<dd><p>tostring() -> string</p>
<p>Convert the array to an array of machine values and return the string
representation.</p>
</dd></dl>
</dd></dl>
<dl class="class">
<dt id="pyroute2.dhcp.dhcpmsg">
<em class="property">class </em><code class="descclassname">pyroute2.dhcp.</code><code class="descname">dhcpmsg</code><span class="sig-paren">(</span><em>content=None</em>, <em>buf=''</em>, <em>offset=0</em>, <em>value=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcpmsg" title="Permalink to this definition">¶</a></dt>
<dd><dl class="class">
<dt id="pyroute2.dhcp.dhcpmsg.array8">
<em class="property">class </em><code class="descname">array8</code><span class="sig-paren">(</span><em>content=None</em>, <em>buf=''</em>, <em>offset=0</em>, <em>value=None</em>, <em>code=0</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcpmsg.array8" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="class">
<dt id="pyroute2.dhcp.dhcpmsg.be16">
<em class="property">class </em><code class="descname">be16</code><span class="sig-paren">(</span><em>content=None</em>, <em>buf=''</em>, <em>offset=0</em>, <em>value=None</em>, <em>code=0</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcpmsg.be16" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="class">
<dt id="pyroute2.dhcp.dhcpmsg.be32">
<em class="property">class </em><code class="descname">be32</code><span class="sig-paren">(</span><em>content=None</em>, <em>buf=''</em>, <em>offset=0</em>, <em>value=None</em>, <em>code=0</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcpmsg.be32" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="class">
<dt id="pyroute2.dhcp.dhcpmsg.client_id">
<em class="property">class </em><code class="descname">client_id</code><span class="sig-paren">(</span><em>content=None</em>, <em>buf=''</em>, <em>offset=0</em>, <em>value=None</em>, <em>code=0</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcpmsg.client_id" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="class">
<dt id="pyroute2.dhcp.dhcpmsg.none">
<em class="property">class </em><code class="descname">none</code><span class="sig-paren">(</span><em>content=None</em>, <em>buf=''</em>, <em>offset=0</em>, <em>value=None</em>, <em>code=0</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcpmsg.none" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="class">
<dt id="pyroute2.dhcp.dhcpmsg.string">
<em class="property">class </em><code class="descname">string</code><span class="sig-paren">(</span><em>content=None</em>, <em>buf=''</em>, <em>offset=0</em>, <em>value=None</em>, <em>code=0</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcpmsg.string" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
<dl class="class">
<dt id="pyroute2.dhcp.dhcpmsg.uint8">
<em class="property">class </em><code class="descname">uint8</code><span class="sig-paren">(</span><em>content=None</em>, <em>buf=''</em>, <em>offset=0</em>, <em>value=None</em>, <em>code=0</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcpmsg.uint8" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</dd></dl>
<dl class="class">
<dt id="pyroute2.dhcp.option">
<em class="property">class </em><code class="descclassname">pyroute2.dhcp.</code><code class="descname">option</code><span class="sig-paren">(</span><em>content=None</em>, <em>buf=''</em>, <em>offset=0</em>, <em>value=None</em>, <em>code=0</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.option" title="Permalink to this definition">¶</a></dt>
<dd></dd></dl>
</div>
</div>
<span class="target" id="module-pyroute2.dhcp.dhcp4socket"></span><div class="section" id="ipv4-dhcp-socket">
<h2>IPv4 DHCP socket<a class="headerlink" href="#ipv4-dhcp-socket" title="Permalink to this headline">¶</a></h2>
<dl class="class">
<dt id="pyroute2.dhcp.dhcp4socket.DHCP4Socket">
<em class="property">class </em><code class="descclassname">pyroute2.dhcp.dhcp4socket.</code><code class="descname">DHCP4Socket</code><span class="sig-paren">(</span><em>ifname</em>, <em>port=68</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcp4socket.DHCP4Socket" title="Permalink to this definition">¶</a></dt>
<dd><p>Parameters:</p>
<ul class="simple">
<li>ifname – interface name to work on</li>
</ul>
<p>This raw socket binds to an interface and installs BPF filter
to get only its UDP port. It can be used in poll/select and
provides also the context manager protocol, so can be used in
<cite>with</cite> statements.</p>
<p>It does not provide any DHCP state machine, and does not inspect
DHCP packets, it is totally up to you. No default values are
provided here, except <cite>xid</cite> – DHCP transaction ID. If <cite>xid</cite> is
not provided, DHCP4Socket generates it for outgoing messages.</p>
<dl class="method">
<dt id="pyroute2.dhcp.dhcp4socket.DHCP4Socket.get">
<code class="descname">get</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcp4socket.DHCP4Socket.get" title="Permalink to this definition">¶</a></dt>
<dd><p>Get the next incoming packet from the socket and try
to decode it as IPv4 DHCP. No analysis is done here,
only MAC/IPv4/UDP headers are stripped out, and the
rest is interpreted as DHCP.</p>
</dd></dl>
<dl class="method">
<dt id="pyroute2.dhcp.dhcp4socket.DHCP4Socket.put">
<code class="descname">put</code><span class="sig-paren">(</span><em>msg=None</em>, <em>dport=67</em><span class="sig-paren">)</span><a class="headerlink" href="#pyroute2.dhcp.dhcp4socket.DHCP4Socket.put" title="Permalink to this definition">¶</a></dt>
<dd><p>Put DHCP message. Parameters:</p>
<ul class="simple">
<li>msg – dhcp4msg instance</li>
<li>dport – DHCP server port</li>
</ul>
<p>If <cite>msg</cite> is not provided, it is constructed as default
BOOTREQUEST + DHCPDISCOVER.</p>
<p>Examples:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">sock</span><span class="o">.</span><span class="n">put</span><span class="p">(</span><span class="n">dhcp4msg</span><span class="p">({</span><span class="s1">'op'</span><span class="p">:</span> <span class="n">BOOTREQUEST</span><span class="p">,</span>
<span class="s1">'chaddr'</span><span class="p">:</span> <span class="s1">'ff:11:22:33:44:55'</span><span class="p">,</span>
<span class="s1">'options'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'message_type'</span><span class="p">:</span> <span class="n">DHCPREQUEST</span><span class="p">,</span>
<span class="s1">'parameter_list'</span><span class="p">:</span> <span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">3</span><span class="p">,</span> <span class="mi">6</span><span class="p">,</span> <span class="mi">12</span><span class="p">,</span> <span class="mi">15</span><span class="p">],</span>
<span class="s1">'requested_ip'</span><span class="p">:</span> <span class="s1">'172.16.101.2'</span><span class="p">,</span>
<span class="s1">'server_id'</span><span class="p">:</span> <span class="s1">'172.16.101.1'</span><span class="p">}}))</span>
</pre></div>
</div>
<p>The method returns dhcp4msg that was sent, so one can get from
there <cite>xid</cite> (transaction id) and other details.</p>
</dd></dl>
</dd></dl>
</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="#">DHCP support</a><ul>
<li><a class="reference internal" href="#dhcp-protocol">DHCP protocol</a><ul>
<li><a class="reference internal" href="#packet-fields">Packet fields</a></li>
<li><a class="reference internal" href="#dhcp-options">DHCP options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#ipv4-dhcp-socket">IPv4 DHCP socket</a></li>
</ul>
</li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/dhcp.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="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>
|
