Skip to content
GitLab
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
ISC Open Source Projects
Kea
Commits
ceb084b6
Commit
ceb084b6
authored
Aug 01, 2013
by
Stephen Morris
Browse files
[2984] Modified the documentation of some of the hook points
parent
d165e1c0
Changes
1
Hide whitespace changes
Inline
Side-by-side
src/bin/dhcp6/dhcp6_hooks.dox
View file @
ceb084b6
...
...
@@ -54,41 +54,41 @@ packet processing. Hook points that are not specific to packet processing
- @b Arguments:
- name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
- @b Description:
t
his callout is executed when an incoming DHCPv6
packet is received a
s a raw
buffer. The sole argument -
query6 -
contains a pointer to an isc::dhcp::Pkt6 object that contains
raw
buffer
stored in data_ field. Basic information
like protocol,
source/destination addresses and ports are set, but
the buffer is
not parsed yet. That means that options_ field that will
eventually contain a list of objects
that represent received
options is empty, so
all methods that operate on it (e.g.,
getOption()) will
not
work
yet
. 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
raw bytes
data, it is
usually
better to install your callout on pkt6_receive hook point.
- @b Description:
T
his callout is executed when an incoming DHCPv6
packet is received a
nd the data stored in a
buffer. The sole argument -
query6 -
contains a pointer to an isc::dhcp::Pkt6 object that contains
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
the options_ field (that will
eventually contain a list of objects
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
usually
better to install your callout on
the
pkt6_receive hook point.
- <b>Skip flag action</b>: If any callout sets the skip flag, the
server will assume that the callout
did
parse the buffer and added
necessary option objects to the options_ field
. S
erver will not
attempt to do the parsing on its own. If the callout sets skip
flag, but does not parse
the buffer, the server will
likely drop
the
packet due to
absence of mandatory options. If you want t
he
packet to be dropped, se
e skip f
a
lg in pkt6_receive hook point.
server will assume that the callout parse
d
the buffer and added
then
necessary option objects to the options_ field
; the s
erver will not
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 t
o drop the packet,
see the description of th
e skip fl
a
g in
the
pkt6_receive hook point.
@subsection dhcpv6HooksPkt6Receive pkt6_receive
- @b Arguments:
- name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
- @b Description:
t
his callout is executed when an incoming DHCPv6
- @b Description:
T
his callout is executed when an incoming DHCPv6
packet is received and its content is parsed. The sole argument -
query6 - contains a pointer to an isc::dhcp::Pkt6 object that contains
all information regarding incoming packet, including its source and
destination addresses, interface over which it was received, a list
destination addresses,
the
interface over which it was received, a list
of all options present within and relay information. All fields of
the Pkt6 object can be modified at this time, except data_. (data_
contains the incoming packet as raw buffer. By the time this hook is
reached, that information has already parsed and is available though
reached, that information has already
been
parsed and is available though
other fields in the Pkt6 object. For this reason, it doesn't make
sense to modify it.)
...
...
@@ -103,7 +103,7 @@ packet processing. Hook points that are not specific to packet processing
- name: @b subnet6, type: isc::dhcp::Subnet6Ptr, direction: <b>in/out</b>
- name: @b subnet6collection, type: const isc::dhcp::Subnet6Collection *, direction: <b>in</b>
- @b Description:
t
his callout is executed when a subnet is being
- @b Description:
T
his callout is executed when a subnet is being
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
...
...
@@ -122,7 +122,7 @@ packet processing. Hook points that are not specific to packet processing
- name: @b fake_allocation, type: bool, direction: <b>in</b>
- name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>
- @b Description:
t
his callout is executed after the server engine
- @b Description:
T
his callout is executed after the server engine
has selected a lease for client's request but before the lease
has been inserted into the database. Any modifications made to the
isc::dhcp::Lease6 object will be stored in the lease's record in the
...
...
@@ -148,30 +148,30 @@ packet processing. Hook points that are not specific to packet processing
- 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>
- @b Description: this callout is executed after the server engine is
about to renew an existing lease. Client's request is provided as
the query6 argument. Existing lease with already modified values is
provided in lease6 parameter. The IA_NA option that will be sent
back to the client is provided as the ia_na argument. Callouts
installed on the lease6_renew may modify content of the
lease6. Care should be taken as that modified value will be then
applied to the database without any sanity checks. Although
envisaged usage assumes modification of T1, T2, preferred and valid
lifetimes only, other parameters may be modified as well. The only
exception is addr_ field, which must not be modified as it is used
by the database to select the existing lease to be updated. Care should
be taken to also modify ia_na option to match any changes in the lease6.
- @b Description: This callout is executed when the server engine is
about to renew an existing lease. The client's request is provided as
the query6 argument and the existing lease with the appropriate fields
already modified is given in the lease6 argument. The final argument,
ia_na, is the IA_NA option that will be sent back to the client.
Callouts installed on the lease6_renew may modify the content of
the lease6 object. Care should be taken however, as that modified
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
with the lease may be modified as well. The only exception is the addr_
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
modify the ia_na argument to match any changes in the lease6 argument.
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
when the update is valid, i.e.
unknown,
invalid address
, invalid iaid
renewal attempts will not trigger this hook point.
when the update is valid, i.e.
conditions such as an
invalid address
es
or invalid iaid
renewal attempts will not trigger this hook point.
- <b>Skip flag action</b>: If any callout installed on 'lease6_renew'
sets the skip flag, the server will not renew the lease. It will, however,
send back the IA_NA option that looks like if the server did renew
the lease. It is recommended to modify ia_na option to reflect the
fact that the lease was not updated. Otherwise the client will think
that the lease was renewed, but it fact it was not.
sets the skip flag, the server will not renew the lease. Under these
circumstances, the callout should modify the ia_na argument to reflect
this fact; otherwise the client will think the lease was renewed and continue
to operate under this assumption.
@subsection dhcpv6HooksLease6Release lease6_release
...
...
@@ -179,57 +179,60 @@ packet processing. Hook points that are not specific to packet processing
- 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:
t
his callout is executed
after
the server engine is
about to release an existing lease.
C
lient's request is provided
as
the query6 argument
. E
xisting lease
to be re
lease
d is
provided in lease6 parameter. It doesn't make much sense to modify
existing lease6 at this point
as it will be destroyed immediately
after the callouts conclude their
execution.
- @b Description:
T
his callout is executed
when
the server engine is
about to release an existing lease.
The c
lient's request is provided
as
the query6 argument
and the e
xisting lease
is given in the
lease
6
argument. Although the lease6 structure may be modified, it doesn't
make sense to do so
as it will be destroyed immediately
the callouts
finish
execution.
- <b>Skip flag action</b>: If any callout installed on 'lease6_release'
sets the skip flag, the server will not delete the lease. However,
it will send out the response back to the client as if it did.
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.
@subsection dhcpv6HooksPkt6Send pkt6_send
- @b Arguments:
- name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
- @b Description:
t
his callout is executed when server's response
- @b Description:
T
his callout is executed when server's response
is about to be send back to the client. The sole argument - response6 -
contains a pointer to an isc::dhcp::Pkt6 object that contains the
packet, with set source and destination addresses, interface over which
it will be send, list of all options and relay information. All fields
of the Pkt6 object can be modified at this time
, except bufferOut_.
(This is scratch space used for constructing the packet after all
pkt6_send callouts are complete, so any changes to that field will
be overwritten
.)
- <b>Skip flag action</b>:
i
f any callout sets the skip flag, the server
will assume that the callout did pack transaction-id, mesage type and
option objects into bufferOut_ field and will skip packing part.
Note that if the callout set skip flag, but did not prepare the
output buffer, the server will send zero sized message that will be
of the Pkt6 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
bufferOut_ field will be overwritten when the callout returns.
(bufferOut_ is scratch space used for constructing the packet
.)
- <b>Skip flag action</b>:
I
f any callout sets the skip flag, the server
will assume that the callout did pack
the
transaction-id, mes
s
age type and
option objects into
the
bufferOut_ field and will skip packing part.
Note that if the callout set
s
skip flag, but did not prepare the
output buffer, the server will send
a
zero sized message that will be
ignored by the client. If you want to drop the packet, please see
skip flag in buffer6_send hook point.
skip flag in
the
buffer6_send hook point.
@subsection dhcpv6HooksBuffer6Send buffer6_send
- @b Arguments:
- name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
- @b Description:
t
his callout is executed when server's response is
- @b Description:
T
his callout is executed when server's response is
assembled into binary form and is about to be send back to the
client. The sole argument - response6 - contains a pointer to an
isc::dhcp::Pkt6 object that contains the packet, with set source
and destination addresses, interface over which it will be send,
list of all options and relay information. All options are already
encoded in bufferOut_ field. It doesn't make sense to modify any
options at that time as their binary form was already prepared.
- <b>Skip flag action</b>: if any callout sets the skip flag, the server
isc::dhcp::Pkt6 object that contains the packet, with set source and
destination addresses, interface over which it will be sent, list of
all options and relay information. All options are already encoded
in bufferOut_ field. It doesn't make sense to modify anything but the
contents of bufferOut_ at this time (although if it is a requirement
to modify that data, it will probably be found easier to modify the
option objects in a callout attached to the pkt6_send hook).
- <b>Skip flag action</b>: If any callout sets the skip flag, the server
will drop this response packet. However, the original request packet
from a client
w
as processed, so server's state
w
as most likely changed
from a client
h
as
been
processed, so server's state
h
as most likely changed
(e.g. lease was allocated). Setting this flag merely stops the change
being communicated to the client.
...
...
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment