dhcp6_hooks.dox 16.5 KB
Newer Older
Francis Dupont's avatar
Francis Dupont committed
1
// Copyright (C) 2013, 2015  Internet Systems Consortium, Inc. ("ISC")
2
3
4
5
6
7
8
9
10
11
12
13
14
15
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

/**
16
17
18
 @page dhcpv6Hooks The Hooks API for the DHCPv6 Server

 @section dhcpv6HooksIntroduction Introduction
19
20
 Kea features an API (the "Hooks" API) that allows user-written code to
 be integrated into Kea and called at specific points in its processing.
21
 An overview of the API and a tutorial for writing such code can be found in
22
 the @ref hooksdgDevelopersGuide.  Information for Kea maintainers can be
23
 found in the @ref hooksComponentDeveloperGuide.
24

Francis Dupont's avatar
Francis Dupont committed
25
 This manual is more specialized and is aimed at developers of hook
26
27
28
 code for the DHCPv6 server. It describes each hook point, what the callouts
 attached to the hook are able to do, and the arguments passed to the
 callouts.  Each entry in this manual has the following information:
29
30
31
32
33
34
35
36
37
38
39

 - Name of the hook point.
 - Arguments for the callout.  As well as the argument name and data type, the
   information includes the direction, which can be one of:
   - @b in - the server passes values to the callout but ignored any data
     returned.
   - @b out - the callout is expected to set this value.
   - <b>in/out</b> - the server passes a value to the callout and uses whatever
     value the callout sends back.  Note that the callout may choose not to
     do any modification, in which case the server will use whatever value
     it sent to the callout.
40
41
42
 - Description of the hook. This explains where in the processing the hook
   is located, the possible actions a callout attached to this hook could take,
   and a description of the data passed to the callouts.
43
44
45
46
 - Next step status: the action taken by the server when a callout chooses to set
    status to specified value. Actions not listed explicitly are not supported.
   If a callout sets status to unsupported value, this specific value will be
   ignored and treated as if the status was CONTINUE.
47
48
49

@section dhcpv6HooksHookPoints Hooks in the DHCPv6 Server

50
51
52
53
The following list is ordered by appearance of specific hook points during
packet processing. Hook points that are not specific to packet processing
(e.g. lease expiration) will be added to the end of this list.

54
55
56
57
58
 @subsection dhcpv6HooksBuffer6Receive buffer6_receive

 - @b Arguments:
   - name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>

59
 - @b Description: This callout is executed when an incoming DHCPv6
60
61
   packet is received and the data stored in a buffer. The sole argument
   "query6" contains a pointer to an @c isc::dhcp::Pkt6 object that contains
62
63
64
   the received information stored in the data_ field. Basic information
   like protocol, source/destination addresses and ports are set, but
   the contents of the buffer have not yet been parsed.  That means that
65
   the @c options_ field (that will eventually contain a list of objects
66
67
68
69
   representing the received options) is empty, so none of the methods
   that operate on it (e.g., getOption()) will work. The primary purpose
   of this early call is to offer the ability to modify incoming packets
   in their raw form. Unless you need to access to the raw data, it is
70
   usually better to install your callout on the "pkt6_receive" hook point.
71

72
 - <b>Next step status</b>: If any callout sets the status to SKIP, the
73
74
   server will assume that the callout parsed the buffer and added the
   necessary option objects to the @c options_ field; the server will not
75
76
77
   do any parsing. If the callout sets the skip flag but does not parse
   the buffer, the server will most probably drop the packet due to
   the absence of mandatory options. If you want to drop the packet,
78
   see the description of the skip flag in the "pkt6_receive" hook point.
79

80
81
82
 @subsection dhcpv6HooksPkt6Receive pkt6_receive

 - @b Arguments:
Tomek Mrugalski's avatar
Tomek Mrugalski committed
83
   - name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
84

85
 - @b Description: This callout is executed when an incoming DHCPv6
86
87
   packet is received and its content is parsed. The sole argument
   "query6" contains a pointer to an @c isc::dhcp::Pkt6 object that contains
88
   all information regarding incoming packet, including its source and
89
   destination addresses, the interface over which it was received, a list
90
   of all options present within and relay information.  All fields of
91
   the "query6" object can be modified at this time, except data_. (data_
92
   contains the incoming packet as raw buffer. By the time this hook is
93
   reached, that information has already been parsed and is available though
94
95
   other fields in the Pkt6 object.  For this reason, modification of the
   @c data_ field would have no effect.)
96

97
 - <b>Next step status</b>: If any callout sets the status to SKIP, the server will
98
99
   drop the packet and start processing the next one.  The reason for the drop
   will be logged if logging is set to the appropriate debug level.
100
101
102
103

@subsection dhcpv6HooksSubnet6Select subnet6_select

 - @b Arguments:
Tomek Mrugalski's avatar
Tomek Mrugalski committed
104
   - name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
105
   - name: @b subnet6, type: isc::dhcp::Subnet6Ptr, direction: <b>in/out</b>
106
   - name: @b subnet6collection, type: const isc::dhcp::Subnet6Collection *, direction: <b>in</b>
107

108
 - @b Description: This callout is executed when a subnet is being
109
110
111
   selected for the incoming packet. All parameters, addresses and
   prefixes will be assigned from that subnet. A callout can select a
   different subnet if it wishes so, the list of all subnets currently
112
   configured being provided as "subnet6collection". The list itself must
113
114
   not be modified.

115
116
 - <b>Next step status</b>: If any callout installed on "subnet6_select"
   sets the status to SKIP, the server will not select any subnet. Packet processing
117
   will continue, but will be severely limited.
118

119
@subsection dhcpv6HooksLease6Select lease6_select
120

121
122
123
124
 - @b Arguments:
   - name: @b subnet6, type: isc::dhcp::Subnet6Ptr, direction: <b>in</b>
   - name: @b fake_allocation, type: bool, direction: <b>in</b>
   - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>
125

126
 - @b Description: This callout is executed after the server engine
127
128
   has selected a lease for client's request but before the lease
   has been inserted into the database. Any modifications made to the
129
130
131
   "lease6" object will affect the lease's record in the database.
   The callout should make sure that any modifications are sanity
   checked as the server will use that data as is, with no further
132
   checking.\n\n The server processes lease requests for SOLICIT and
133
134
135
136
137
138
139
   REQUEST in a very similar way. The major difference is that
   for SOLICIT the lease is only selected; it is not inserted into
   the database.  The callouts can distinguish between the SOLICIT and
   REQUEST by checking the value of the "fake_allocation" flag: a value
   of true means that the lease won't be inserted into the database
   (SOLICIT case), a value of false means that it will (REQUEST).

140
141
 - <b>Next step status</b>: If any callout installed on "lease6_select"
   sets the status to SKIP, the server will not assign that particular lease.
142
143
   Packet processing will continue and the client may get other addresses
   or prefixes if it requested more than one address and/or prefix.
144

145
146
147
148
149
150
151
@subsection dhcpv6HooksLease6Renew lease6_renew

 - @b Arguments:
   - name: @b query6, type: isc::dhcp::PktPtr, direction: <b>in</b>
   - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>
   - name: @b ia_na, type: boost::shared_ptr<Option6IA>, direction: <b>in/out</b>

152
153
 - @b Description: This callout is executed when the server engine is
   about to renew an existing lease. The client's request is provided as
154
155
   the "query6" argument and the existing lease with the appropriate fields
   already modified is given in the "lease6" argument. The final argument,
156
   ia_na, is the IA_NA option that will be sent back to the client.
157
158
   Callouts installed on the "lease6_renew" may modify the content of
   the "lease6" object. Care should be taken however, as that modified
159
160
161
   information will be written to the database without any further
   checking. \n\n Although the envisaged usage assumes modification of T1,
   T2, preferred and valid lifetimes only, other parameters associated
162
   with the lease may be modified as well. The only exception is the @c addr_
163
164
   field, which must not be modified as it is used by the database to
   select the existing lease to be updated. Care should also be taken to
165
   modify the "ia_na" argument to match any changes in the "lease6" argument.
166
167
   If a client sends more than one IA_NA option, callouts will be called
   separately for each IA_NA instance. The callout will be called only
168
169
   when the update is valid, i.e. conditions such as an invalid addresses
   or invalid iaid renewal attempts will not trigger this hook point.
170

171
172
 - <b>Next step status</b>: If any callout installed on "lease6_renew"
   sets the status to SKIP, the server will not renew the lease. Under these
173
   circumstances, the callout should modify the "ia_na" argument to reflect
174
175
   this fact; otherwise the client will think the lease was renewed and continue
   to operate under this assumption.
176

177
178
179
180
181
182
183
@subsection dhcpv6HooksLease6Decline lease6_decline

 - @b Arguments:
   - name: @b query6, type: isc::dhcp::PktPtr, direction: <b>in</b>
   - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>

 - @b Description: This callout is executed when the server engine is
Tomek Mrugalski's avatar
Tomek Mrugalski committed
184
   about to decline an existing lease. The client's DECLINE is provided as
185
186
187
188
189
190
191
192
193
194
195
196
   the "query6" argument and the existing lease with the appropriate fields
   already modified is given in the "lease6" argument. The lease contains
   the lease before it is being declined.

 - <b>Next step status</b>: If any callout installed on "lease6_decline"
   sets the status to SKIP, the server will not decline the lease, but will
   continue processing the packet as if it did. It will send the response
   that the lease was declined, but the actual database will not be
   updated. If any callout installed sets the status to DROP, the packet
   processing will be aborted, the lease will not be declined and the
   server will not send a response.

197
198
199
200
201
202
@subsection dhcpv6HooksLease6Release lease6_release

 - @b Arguments:
   - name: @b query6, type: isc::dhcp::PktPtr, direction: <b>in</b>
   - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>

203
204
 - @b Description: This callout is executed when the server engine is
   about to release an existing lease. The client's request is provided
205
206
   as the "query6" argument and the existing lease is given in the "lease6"
   argument.  Although the "lease6" structure may be modified, it doesn't
207
208
   make sense to do so as it will be destroyed immediately the callouts
   finish execution.
209

210
211
 - <b>Next step status</b>: If any callout installed on "lease6_release"
   sets the status to SKIP, the server will not delete the lease, which will
212
213
   remain in the database until it expires. However, the server will send out
   the response back to the client as if it did.
214

215
@subsection dhcpv6HooksPkt6Send pkt6_send
216
217

 - @b Arguments:
Tomek Mrugalski's avatar
Tomek Mrugalski committed
218
   - name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
219

220
 - @b Description: This callout is executed when server's response
221
222
   is about to be send back to the client. The sole argument "response6"
   contains a pointer to an @c isc::dhcp::Pkt6 object that contains the
223
224
   packet, with set source and destination addresses, interface over which
   it will be send, list of all options and relay information.  All fields
225
226
227
228
   of the "response6" object can be modified at this time.  It should be
   noted that unless the callout sets the skip flag (see below), anything
   placed in the @c buffer_out_ field will be overwritten when the callout
   returns. (buffer_out_ is scratch space used for constructing the packet.)
229

230
 - <b>Next step status</b>: If any callout sets the status to SKIP, the server
231
232
   will assume that the callout did pack the "transaction-id", "message type"
   and option objects into the @c buffer_out_ field and will skip packing part.
233
234
   Note that if the callout sets skip flag, but did not prepare the
   output buffer, the server will send a zero sized message that will be
235
   ignored by the client. If you want to drop the packet, please see
236
   skip flag in the "buffer6_send" hook point.
237
238
239
240
241

@subsection dhcpv6HooksBuffer6Send buffer6_send

 - @b Arguments:
   - name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
242

243
 - @b Description: This callout is executed when server's response is
244
   assembled into binary form and is about to be send back to the
245
246
   client. The sole argument "response6" contains a pointer to an
   @c isc::dhcp::Pkt6 object that contains the packet, with set source and
247
248
   destination addresses, interface over which it will be sent, list of
   all options and relay information. All options are already encoded
249
250
   in @c buffer_out_ field. It doesn't make sense to modify anything but the
   contents of buffer_out_ at this time (although if it is a requirement
251
   to modify that data, it will probably be found easier to modify the
252
   option objects in a callout attached to the "pkt6_send" hook).
253

254
 - <b>Next step status</b>: If any callout sets the status to SKIP, the server
255
   will drop this response packet. However, the original request packet
256
   from a client has been processed, so server's state has most likely changed
257
258
   (e.g. lease was allocated). Setting this flag merely stops the change
   being communicated to the client.
259

260
261
262
263
264
265
266
267
268
269
270
271
272
273
@subsection dhcpv6HooksLease6Expire lease6_expire

- @b Arguments:
  - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>
  - name: @b remove_lease, type: bool, direction: <b>in</b>

- @b Description: this callout is executed for each expired lease when
  the server performs reclamation of the expired leases. During this
  process the server executes "lease6_expire" callout, removes the DNS
  records associated with this lease and finally removes the lease from
  the database or updates its status to "expired-reclaimed". The "lease6"
  argument contains the pointer to the lease being reclaimed. The second
  argument "remove_lease" indicates if the reclaimed leases should be
  removed from the lease database (if true), or their state should be
274
  set to "expired-reclaimed" in the lease database. This argument
275
  is only used by the callout if it takes responsibility for the lease
276
  reclamation, i.e. it sets the "skip" flag to "true".  The "remove_lease"
277
278
  argument is set to "true" if the "flush-reclaimed-timer-wait-time" is
  set to 0 in the server configuration file.
279

280
- <b>Next step status</b>: if the callout sets the status to SKIP, the server
281
282
283
284
285
286
287
288
289
290
  will assume that the callout has fully reclaimed the lease, i.e.
  performed the DNS update and updated the lease in the database. The
  server will not perform any further actions on the lease for which the
  skip flag has been set. It is important to note that if the callout
  sets this flag but fails to reclaim the lease in the database, the
  reclamation routine will repeatedly process this lease in subsequent
  runs. Therefore, the implementors of this callout must make sure that
  skip flag is only set when the lease has been actually reclaimed in the
  database by the callout.

291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
@subsection dhcpv6HooksLease4Recover lease6_recover

- @b Arguments:
  - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in</b>

- @b Description: this callout is executed for each declined lease that
  has expired and is being recovered. The lease has already been stripped
  from any client identifying information when it was put into declined
  state. In principle the callouts can modify the lease in this hook,
  but it makes little sense. There's no useful data in the lease, except
  the IPv4 address (which must not be modified).

- <b>Next step status</b>: if the callout sets the next step action to SKIP,
  the server will skip the lease recovery. In other words, it will keep
  the lease as is. This is not recommended in general, as the declined
  expired leases will remain in the database and their recovery will
  be attempted during the next reclaim cycle.

309
*/