dhcp6_hooks.dox 14.4 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
47
 - Skip flag action: the action taken by the server if a callout chooses to set
    the "skip" flag.

@section dhcpv6HooksHookPoints Hooks in the DHCPv6 Server

48
49
50
51
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.

52
53
54
55
56
 @subsection dhcpv6HooksBuffer6Receive buffer6_receive

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

57
 - @b Description: This callout is executed when an incoming DHCPv6
58
59
   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
60
61
62
   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
63
   the @c options_ field (that will eventually contain a list of objects
64
65
66
67
   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
68
   usually better to install your callout on the "pkt6_receive" hook point.
69
70

 - <b>Skip flag action</b>: If any callout sets the skip flag, the
71
72
   server will assume that the callout parsed the buffer and added the
   necessary option objects to the @c options_ field; the server will not
73
74
75
   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,
76
   see the description of the skip flag in the "pkt6_receive" hook point.
77

78
79
80
 @subsection dhcpv6HooksPkt6Receive pkt6_receive

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

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

 - <b>Skip flag action</b>: If any callout sets the skip flag, the server will
96
97
   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.
98
99
100
101

@subsection dhcpv6HooksSubnet6Select subnet6_select

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

106
 - @b Description: This callout is executed when a subnet is being
107
108
109
   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
110
   configured being provided as "subnet6collection". The list itself must
111
112
   not be modified.

113
 - <b>Skip flag action</b>: If any callout installed on "subnet6_select"
114
   sets the skip flag, the server will not select any subnet. Packet processing
115
   will continue, but will be severely limited.
116

117
@subsection dhcpv6HooksLease6Select lease6_select
118

119
120
121
122
 - @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>
123

124
 - @b Description: This callout is executed after the server engine
125
126
   has selected a lease for client's request but before the lease
   has been inserted into the database. Any modifications made to the
127
128
129
   "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
130
   checking.\n\n The server processes lease requests for SOLICIT and
131
132
133
134
135
136
137
138
   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).

 - <b>Skip flag action</b>: If any callout installed on "lease6_select"
139
140
141
   sets the skip flag, the server will not assign that particular lease.
   Packet processing will continue and the client may get other addresses
   or prefixes if it requested more than one address and/or prefix.
142

143
144
145
146
147
148
149
@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>

150
151
 - @b Description: This callout is executed when the server engine is
   about to renew an existing lease. The client's request is provided as
152
153
   the "query6" argument and the existing lease with the appropriate fields
   already modified is given in the "lease6" argument. The final argument,
154
   ia_na, is the IA_NA option that will be sent back to the client.
155
156
   Callouts installed on the "lease6_renew" may modify the content of
   the "lease6" object. Care should be taken however, as that modified
157
158
159
   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
160
   with the lease may be modified as well. The only exception is the @c addr_
161
162
   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
163
   modify the "ia_na" argument to match any changes in the "lease6" argument.
164
165
   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
166
167
   when the update is valid, i.e. conditions such as an invalid addresses
   or invalid iaid renewal attempts will not trigger this hook point.
168

169
 - <b>Skip flag action</b>: If any callout installed on "lease6_renew"
170
   sets the skip flag, the server will not renew the lease. Under these
171
   circumstances, the callout should modify the "ia_na" argument to reflect
172
173
   this fact; otherwise the client will think the lease was renewed and continue
   to operate under this assumption.
174
175
176
177
178
179
180

@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>

181
182
 - @b Description: This callout is executed when the server engine is
   about to release an existing lease. The client's request is provided
183
184
   as the "query6" argument and the existing lease is given in the "lease6"
   argument.  Although the "lease6" structure may be modified, it doesn't
185
186
   make sense to do so as it will be destroyed immediately the callouts
   finish execution.
187

188
 - <b>Skip flag action</b>: If any callout installed on "lease6_release"
189
190
191
   sets the skip flag, the server will not delete the lease, which will
   remain in the database until it expires. However, the server will send out
   the response back to the client as if it did.
192

193
@subsection dhcpv6HooksPkt6Send pkt6_send
194
195

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

198
 - @b Description: This callout is executed when server's response
199
200
   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
201
202
   packet, with set source and destination addresses, interface over which
   it will be send, list of all options and relay information.  All fields
203
204
205
206
   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.)
207
208

 - <b>Skip flag action</b>: If any callout sets the skip flag, the server
209
210
   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.
211
212
   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
213
   ignored by the client. If you want to drop the packet, please see
214
   skip flag in the "buffer6_send" hook point.
215
216
217
218
219

@subsection dhcpv6HooksBuffer6Send buffer6_send

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

221
 - @b Description: This callout is executed when server's response is
222
   assembled into binary form and is about to be send back to the
223
224
   client. The sole argument "response6" contains a pointer to an
   @c isc::dhcp::Pkt6 object that contains the packet, with set source and
225
226
   destination addresses, interface over which it will be sent, list of
   all options and relay information. All options are already encoded
227
228
   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
229
   to modify that data, it will probably be found easier to modify the
230
   option objects in a callout attached to the "pkt6_send" hook).
231
232

 - <b>Skip flag action</b>: If any callout sets the skip flag, the server
233
   will drop this response packet. However, the original request packet
234
   from a client has been processed, so server's state has most likely changed
235
236
   (e.g. lease was allocated). Setting this flag merely stops the change
   being communicated to the client.
237

238
239
240
241
242
243
244
245
246
247
248
249
250
251
@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
252
  set to "expired-reclaimed" in the lease database. This argument
253
  is only used by the callout if it takes responsibility for the lease
254
255
256
  reclamation, i.e. it sets the "skip" flag to "true".  The "remove_lease"
  argument is set to "true" if the "recycle-timer-wait-time" is set
  to 0 in the server configuration file.
257
258
259
260
261
262
263
264
265
266
267
268

- <b>Skip flag action</b>: if the callout sets the skip flag, the server
  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.

269
*/