mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-31 14:05:33 +00:00
[3484] Updated description of hooks for DHCPv4 and DHCPv6 server.
This commit is contained in:
Marcin Siodelski
@@ -1,4 +1,4 @@
|
||||
// Copyright (C) 2013 Internet Systems Consortium, Inc. ("ISC")
|
||||
// Copyright (C) 2013-2015 Internet Systems Consortium, Inc. ("ISC")
|
||||
//
|
||||
// Permission to use, copy, modify, and/or distribute this software for any
|
||||
// purpose with or without fee is hereby granted, provided that the above
|
||||
@@ -22,7 +22,7 @@
|
||||
the @ref hooksdgDevelopersGuide. Information for Kea maintainers can be
|
||||
found in the @ref hooksComponentDeveloperGuide.
|
||||
|
||||
This manual is more specialised and is aimed at developers of hook
|
||||
This manual is more specialized and is aimed at developers of hook
|
||||
code for the DHCPv4 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:
|
||||
@@ -54,23 +54,25 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- @b Arguments:
|
||||
- name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
|
||||
|
||||
- @b Description: this callout is executed when an incoming DHCPv4
|
||||
buffer is received, before its content is parsed. The sole argument
|
||||
- query4 - contains a pointer to an isc::dhcp::Pkt4 object that
|
||||
contains raw information regarding incoming packet, including its
|
||||
source and destination addresses, interface over which it was
|
||||
received, and a raw buffer stored in data_ field. None of the
|
||||
packet fields (op_, hlen_, chaddr_, etc.) are set yet. Callouts
|
||||
installed on this hook point can modify the incoming buffer. The
|
||||
server will parse the buffer afterwards.
|
||||
- @b Description: this callout is executed when the server has received a
|
||||
buffer containing a DHCPv4 message, but the message hasn't been parsed
|
||||
yet. The sole argument "query4" contains a pointer to the isc::dhcp::Pkt4
|
||||
object, which contains the source and destination address of the
|
||||
received packet, interface over which the packet has been received, and
|
||||
a raw buffer, stored in the data_ field, containing the DHCPv4 message
|
||||
in the wire format. None of the packet fields (op_, hlen_, chaddr_, etc.)
|
||||
are set yet. Callouts installed on this hook point can modify the data
|
||||
in the received buffer. The server will parse the buffer afterwards.
|
||||
|
||||
- <b>Skip flag action</b>: If any callout sets the skip flag, the server will
|
||||
skip the buffer parsing. In such case there is an expectation that
|
||||
the callout will parse the buffer and create option objects (see
|
||||
isc::dhcp::Pkt4::addOption()). Otherwise the server will find out
|
||||
that some mandatory options are missing (e.g. DHCP Message Type) and
|
||||
will drop the packet. If you want to have the capability to drop
|
||||
a message, it is better to use skip flag in pkt4_receive callout.
|
||||
the callout will parse options carried in the buffer, create
|
||||
@c isc::dhcp::Option objects (or derived) and add them to the "query4"
|
||||
object using the @c isc::dhcp::Pkt4::addOption.
|
||||
Otherwise the server will find out that some mandatory options are
|
||||
missing (e.g. DHCP Message Type) and will drop the message. If you
|
||||
want to have the capability to drop a message, it is better to use
|
||||
skip flag in "pkt4_receive" callout.
|
||||
|
||||
@subsection dhcpv4HooksPkt4Receive pkt4_receive
|
||||
|
||||
@@ -79,15 +81,14 @@ packet processing. Hook points that are not specific to packet processing
|
||||
|
||||
- @b Description: this callout is executed when an incoming DHCPv4
|
||||
packet is received and its content has been parsed. The sole
|
||||
argument - query4 - contains a pointer to an isc::dhcp::Pkt4 object
|
||||
argument "query4" contains a pointer to an isc::dhcp::Pkt4 object
|
||||
that contains all information regarding incoming packet, including
|
||||
its source and destination addresses, interface over which it was
|
||||
received, a list of all options present within and relay
|
||||
received, a list of all options present within and the relay
|
||||
information. All fields of the Pkt4 object can be modified at this
|
||||
time, except data_. (By the time this hook is reached, the contents
|
||||
of the data_ field has been already parsed and stored in other
|
||||
fields. Therefore, the modification in the data_ field has no
|
||||
effect.)
|
||||
time. By the time this hook is reached, the contents of the data_
|
||||
field has been already parsed and stored in other fields. Therefore,
|
||||
the modification in the data_ field has no effect.
|
||||
|
||||
- <b>Skip flag action</b>: If any callout sets the skip flag, the server will
|
||||
drop the packet and start processing the next one. The reason for the drop
|
||||
@@ -98,19 +99,19 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- @b Arguments:
|
||||
- name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
|
||||
- name: @b subnet4, type: isc::dhcp::Subnet4Ptr, direction: <b>in/out</b>
|
||||
- name: @b subnet4collection, type: const isc::dhcp::Subnet4Collection *, direction: <b>in</b>
|
||||
- name: @b subnet4collection, type: const isc::dhcp::Subnet4Collection *,
|
||||
direction: <b>in</b>
|
||||
|
||||
- @b Description: this callout is executed when a subnet is being
|
||||
selected for the incoming packet. All parameters and addresses
|
||||
will be assigned from that subnet. A callout can select a
|
||||
different subnet if it wishes so, the list of all subnets currently
|
||||
configured being provided as 'subnet4collection'. The list itself must
|
||||
different subnet if it wishes so. The list of all subnets currently
|
||||
configured are provided as "subnet4collection". The list itself must
|
||||
not be modified.
|
||||
|
||||
- <b>Skip flag action</b>: If any callout installed on 'subnet4_select'
|
||||
- <b>Skip flag action</b>: If any callout, installed on "subnet4_select",
|
||||
sets the skip flag, the server will not select any subnet. Packet processing
|
||||
will continue, but will be severely limited (i.e. only global options
|
||||
will be assigned).
|
||||
will continue, but will be severely limited.
|
||||
|
||||
@subsection dhcpv4HooksLeaseSelect lease4_select
|
||||
|
||||
@@ -120,22 +121,24 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in/out</b>
|
||||
|
||||
- @b Description: this callout is executed after the server engine
|
||||
has selected a lease for client's request but before the lease has
|
||||
has selected a lease for the client's request, but before the lease has
|
||||
been inserted into the database. Any modifications made to the
|
||||
isc::dhcp::Lease4 object will be stored in the lease's record in
|
||||
the database. The callout should sanity check all modifications as
|
||||
the server will use that data as is with no further checking.\n\n
|
||||
The server processes lease requests for DISCOVER and REQUEST in a
|
||||
very similar way. The only major difference is that for DISCOVER
|
||||
the lease is just selected, but not inserted into the database. It
|
||||
is possible to distinguish between DISCOVER and REQUEST by checking
|
||||
value of the fake_allocation flag: a value of true indicates that the
|
||||
lease won't be inserted into the database (DISCOVER), a value of
|
||||
false indicates that it will (REQUEST).
|
||||
"lease4" object will affect the lease's record in the database.
|
||||
The callout should sanity check all modifications as the server will
|
||||
use that data as is, with no further checking.\n\n
|
||||
The server processes lease requests for DHCPDISCOVER and DHCPREQUEST in a
|
||||
very similar way. The only major difference is that for DHCPDISCOVER
|
||||
the lease is only selected, but not inserted into the database. The callouts
|
||||
may distinguish between DHCPDISCOVER and DHCPREQUEST by checking the
|
||||
value of the "fake_allocation" flag: a value of true indicates that the
|
||||
lease won't be inserted into the database (DHCPDISCOVER case), a value of
|
||||
false indicates that it will (DHCPREQUEST case).
|
||||
|
||||
- <b>Skip flag action</b>: If any callout installed on 'lease4_select'
|
||||
sets the skip flag, the server will not assign any lease. Packet
|
||||
processing will continue, but client will not get an address.
|
||||
- <b>Skip flag action</b>: If any callout installed on "lease4_select"
|
||||
sets the skip flag, the server will not assign any lease and the callouts
|
||||
become responsible for the lease assignment. If the callouts fail to provide
|
||||
a lease, the packet processing will continue, but client will not get
|
||||
an address.
|
||||
|
||||
@subsection dhcpv4HooksLeaseRenew lease4_renew
|
||||
|
||||
@@ -146,15 +149,15 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in/out</b>
|
||||
|
||||
- @b Description: this callout is executed when the server engine
|
||||
is about to renew a lease, as a result of receiving REQUEST/Renewing
|
||||
packet. The lease4 argument points to Lease4 object that contains
|
||||
the updated values. Callout can modify those values. Care should be taken
|
||||
as the server will attempt to update the lease in the database without
|
||||
any additional checks.
|
||||
is about to renew a lease, as a result of receiving DHCPREQUEST/Renewing
|
||||
packet. The "lease4" argument points to @c isc::dhcp::Lease4 object that
|
||||
contains the updated values. Callout can modify those values. Care should
|
||||
be taken as the server will attempt to update the lease in the database
|
||||
without any additional checks.
|
||||
|
||||
- <b>Skip flag action</b>: If any callout installed on 'lease4_renew'
|
||||
sets the skip flag, the server will not update the lease and will
|
||||
use old values instead.
|
||||
- <b>Skip flag action</b>: If any callout installed on "lease4_renew"
|
||||
sets the skip flag, the server will not update the lease in the
|
||||
database and continue using old values instead.
|
||||
|
||||
@subsection dhcpv4HooksLeaseRelease lease4_release
|
||||
|
||||
@@ -163,11 +166,11 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in</b>
|
||||
|
||||
- @b Description: this callout is executed when the server engine
|
||||
is about to release a lease, as a result of receiving RELEASE packet.
|
||||
The lease4 argument points to Lease4 object that contains the lease to
|
||||
is about to release a lease, as a result of receiving DHCPRELEASE packet.
|
||||
The "lease4" argument points to @c Lease4 object that contains the lease to
|
||||
be released. It doesn't make sense to modify it at this time.
|
||||
|
||||
- <b>Skip flag action</b>: If any callout installed on 'lease4_release'
|
||||
- <b>Skip flag action</b>: If any callout installed on "lease4_release"
|
||||
sets the skip flag, the server will not delete the lease. It will be
|
||||
kept in the database and will go through the regular expiration/reuse
|
||||
process.
|
||||
@@ -178,17 +181,17 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- name: @b response4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
|
||||
|
||||
- @b Description: this callout is executed when server's response
|
||||
is about to be sent back to the client. The sole argument - response4 -
|
||||
contains a pointer to an isc::dhcp::Pkt4 object that contains the
|
||||
is about to be sent back to the client. The sole argument "response4"
|
||||
contains a pointer to an isc::dhcp::Pkt4 object carrying the
|
||||
packet, with source and destination addresses set, interface over which
|
||||
it will be sent, and a list of all options and relay information. All fields
|
||||
of the Pkt4 object can be modified at this time, except buffer_out_.
|
||||
of the @c Pkt4 object can be modified at this time, except @c buffer_out_.
|
||||
(This is scratch space used for constructing the packet after all
|
||||
pkt4_send callouts are complete, so any changes to that field will
|
||||
be overwritten.)
|
||||
|
||||
- <b>Skip flag action</b>: if any callout sets the skip flag, the server
|
||||
will not construct raw buffer. The expectation is that if the callout
|
||||
will not construct the raw buffer. The expectation is that if the callout
|
||||
set skip flag, it is responsible for constructing raw form on its own.
|
||||
Otherwise the output packet will be sent with zero length.
|
||||
|
||||
@@ -198,17 +201,19 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- name: @b response4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
|
||||
|
||||
- @b Description: this callout is executed when server's response
|
||||
is about to be sent back to the client. The sole argument - response4 -
|
||||
contains a pointer to an isc::dhcp::Pkt4 object that contains the
|
||||
is about to be sent back to the client. The sole argument "response4"
|
||||
contains a pointer to an @c isc::dhcp::Pkt4 object that contains the
|
||||
packet, with source and destination addresses set, interface over which
|
||||
it will be sent, and a list of all options and relay information. The raw
|
||||
on-wire form is already prepared in buffer_out_ (see isc::dhcp::Pkt4::getBuffer())
|
||||
It doesn't make any sense to modify packet fields or options content
|
||||
at this time, because they were already used to construct on-wire buffer.
|
||||
on-wire form is already prepared in @c buffer_out_ (see
|
||||
@c isc::dhcp::Pkt4::getBuffer())
|
||||
Callouts should not modify the packet fields or options contents at this
|
||||
time, because they were already used to construct on-wire buffer. Their
|
||||
modification would have no effect.
|
||||
|
||||
- <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 was processed, so server's state was most likely changed
|
||||
from a client was processed, so server's state most likely has changed
|
||||
(e.g. lease was allocated). Setting this flag merely stops the change
|
||||
being communicated to the client.
|
||||
|
||||
|
||||
@@ -55,25 +55,25 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
|
||||
|
||||
- @b Description: This callout is executed when an incoming DHCPv6
|
||||
packet is received and the data stored in a buffer. The sole argument -
|
||||
query6 - contains a pointer to an isc::dhcp::Pkt6 object that contains
|
||||
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
|
||||
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
|
||||
the @c 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.
|
||||
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 parsed the buffer and added then
|
||||
necessary option objects to the options_ field; the server will not
|
||||
server will assume that the callout parsed the buffer and added the
|
||||
necessary option objects to the @c options_ field; the server 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 to drop the packet,
|
||||
see the description of the skip flag in the pkt6_receive hook point.
|
||||
see the description of the skip flag in the "pkt6_receive" hook point.
|
||||
|
||||
@subsection dhcpv6HooksPkt6Receive pkt6_receive
|
||||
|
||||
@@ -81,16 +81,16 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
|
||||
|
||||
- @b Description: This 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
|
||||
packet is received and its content is parsed. The sole argument
|
||||
"query6" contains a pointer to an @c isc::dhcp::Pkt6 object that contains
|
||||
all information regarding incoming packet, including its source and
|
||||
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_
|
||||
the "query6" 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 been parsed and is available though
|
||||
other fields in the Pkt6 object. For this reason, it doesn't make
|
||||
sense to modify it.)
|
||||
other fields in the Pkt6 object. For this reason, modification of the
|
||||
@c data_ field would have no effect.)
|
||||
|
||||
- <b>Skip flag action</b>: If any callout sets the skip flag, the server will
|
||||
drop the packet and start processing the next one. The reason for the drop
|
||||
@@ -107,13 +107,12 @@ packet processing. Hook points that are not specific to packet processing
|
||||
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
|
||||
configured being provided as 'subnet6collection'. The list itself must
|
||||
configured being provided as "subnet6collection". The list itself must
|
||||
not be modified.
|
||||
|
||||
- <b>Skip flag action</b>: If any callout installed on 'subnet6_select'
|
||||
- <b>Skip flag action</b>: If any callout installed on "subnet6_select"
|
||||
sets the skip flag, the server will not select any subnet. Packet processing
|
||||
will continue, but will be severely limited (i.e. only global options
|
||||
will be assigned).
|
||||
will continue, but will be severely limited.
|
||||
|
||||
@subsection dhcpv6HooksLease6Select lease6_select
|
||||
|
||||
@@ -125,18 +124,18 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- @b Description: This 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
|
||||
database. The callout should make sure that any modifications are
|
||||
sanity checked as the server will use that data as is with no further
|
||||
"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
|
||||
checking.\n\n The server processes lease requests for SOLICIT and
|
||||
REQUEST in a very similar way. The only major difference is that
|
||||
for SOLICIT the lease is just selected; it is not inserted into
|
||||
the database. It is possible to distinguish between SOLICIT and
|
||||
REQUEST by checking value of the fake_allocation flag: a value of true
|
||||
means that the lease won't be inserted into the database (SOLICIT),
|
||||
a value of false means that it will (REQUEST).
|
||||
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'
|
||||
- <b>Skip flag action</b>: If any callout installed on "lease6_select"
|
||||
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.
|
||||
@@ -150,26 +149,26 @@ packet processing. Hook points that are not specific to packet processing
|
||||
|
||||
- @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,
|
||||
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
|
||||
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_
|
||||
with the lease may be modified as well. The only exception is the @c 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.
|
||||
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. conditions such as an invalid addresses
|
||||
or invalid iaid renewal attempts will not trigger this hook point.
|
||||
|
||||
- <b>Skip flag action</b>: If any callout installed on 'lease6_renew'
|
||||
- <b>Skip flag action</b>: If any callout installed on "lease6_renew"
|
||||
sets the skip flag, the server will not renew the lease. Under these
|
||||
circumstances, the callout should modify the ia_na argument to reflect
|
||||
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.
|
||||
|
||||
@@ -181,12 +180,12 @@ packet processing. Hook points that are not specific to packet processing
|
||||
|
||||
- @b Description: This callout is executed when the server engine is
|
||||
about to release an existing lease. The client's request is provided
|
||||
as the query6 argument and the existing lease is given in the lease6
|
||||
argument. Although the lease6 structure may be modified, it doesn't
|
||||
as the "query6" argument and the existing lease is given in the "lease6"
|
||||
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'
|
||||
- <b>Skip flag action</b>: If any callout installed on "lease6_release"
|
||||
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.
|
||||
@@ -197,22 +196,22 @@ packet processing. Hook points that are not specific to packet processing
|
||||
- name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
|
||||
|
||||
- @b Description: This 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
|
||||
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
|
||||
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. 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.)
|
||||
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.)
|
||||
|
||||
- <b>Skip flag action</b>: If any callout sets the skip flag, the server
|
||||
will assume that the callout did pack the transaction-id, message type and
|
||||
option objects into the bufferOut_ field and will skip packing part.
|
||||
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.
|
||||
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
|
||||
ignored by the client. If you want to drop the packet, please see
|
||||
skip flag in the buffer6_send hook point.
|
||||
skip flag in the "buffer6_send" hook point.
|
||||
|
||||
@subsection dhcpv6HooksBuffer6Send buffer6_send
|
||||
|
||||
@@ -221,14 +220,14 @@ packet processing. Hook points that are not specific to packet processing
|
||||
|
||||
- @b Description: This 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
|
||||
client. The sole argument "response6" contains a pointer to an
|
||||
@c 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
|
||||
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
|
||||
to modify that data, it will probably be found easier to modify the
|
||||
option objects in a callout attached to the pkt6_send hook).
|
||||
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
|
||||
|
||||
@@ -100,11 +100,11 @@ shared library and loaded by Kea into its address space.
|
||||
To illustrate how to write code that integrates with Kea, we will
|
||||
use the following (rather contrived) example:
|
||||
|
||||
The Kea DHCPv4 server is used to allocate IPv4 addresses to clients
|
||||
<i>The Kea DHCPv4 server is used to allocate IPv4 addresses to clients
|
||||
(as well as to pass them other information such as the address of DNS
|
||||
servers). We will suppose that we need to classify clients requesting
|
||||
IPv4 addresses according to their hardware address, and want to log both
|
||||
the hardware address and allocated IP address for the clients of interest.
|
||||
the hardware address and allocated IP address for the clients of interest.</i>
|
||||
|
||||
The following sections describe how to implement these requirements.
|
||||
The code presented here is not efficient and there are better ways of
|
||||
@@ -282,11 +282,11 @@ int callout(CalloutHandle& handle);
|
||||
@endcode
|
||||
|
||||
(As before, the callout is declared with "C" linkage.) Information is passed
|
||||
between Kea and the callout through name/value pairs in the CalloutHandle
|
||||
between Kea and the callout through name/value pairs in the @c CalloutHandle
|
||||
object. The object is also used to pass information between callouts on a
|
||||
per-request basis. (Both of these concepts are explained below.)
|
||||
|
||||
A callout returns an "int" as a status return. A value of 0 indicates
|
||||
A callout returns an @c int as a status return. A value of 0 indicates
|
||||
success, anything else signifies an error. The status return has no
|
||||
effect on server processing; the only difference between a success
|
||||
and error code is that if the latter is returned, the server will
|
||||
@@ -296,7 +296,7 @@ error information to the Kea logging system.
|
||||
|
||||
@subsubsection hooksdgArguments Callout Arguments
|
||||
|
||||
The CalloutHandle object provides two methods to get and set the
|
||||
The @c CalloutHandle object provides two methods to get and set the
|
||||
arguments passed to the callout. These methods are called (naturally
|
||||
enough) getArgument and SetArgument. Their usage is illustrated by the
|
||||
following code snippets.
|
||||
@@ -336,27 +336,27 @@ In the callout
|
||||
handle.setArgument("data_count", number);
|
||||
@endcode
|
||||
|
||||
As can be seen "getArgument" is used to retrieve data from the
|
||||
CalloutHandle, and setArgument used to put data into it. If a callout
|
||||
As can be seen @c getArgument is used to retrieve data from the
|
||||
@c CalloutHandle, and @c setArgument used to put data into it. If a callout
|
||||
wishes to alter data and pass it back to the server, it should retrieve
|
||||
the data with getArgument, modify it, and call setArgument to send
|
||||
the data with @c getArgument, modify it, and call @c setArgument to send
|
||||
it back.
|
||||
|
||||
There are several points to be aware of:
|
||||
|
||||
- the data type of the variable in the call to getArgument must match
|
||||
the data type of the variable passed to the corresponding setArgument
|
||||
- the data type of the variable in the call to @c getArgument must match
|
||||
the data type of the variable passed to the corresponding @c setArgument
|
||||
<B>exactly</B>: using what would normally be considered to be a
|
||||
"compatible" type is not enough. For example, if the server passed
|
||||
an argument as an "int" and the callout attempted to retrieve it as a
|
||||
"long", an exception would be thrown even though any value that can
|
||||
be stored in an "int" will fit into a "long". This restriction also
|
||||
an argument as an @c int and the callout attempted to retrieve it as a
|
||||
@c long, an exception would be thrown even though any value that can
|
||||
be stored in an @c int will fit into a @c long. This restriction also
|
||||
applies the "const" attribute but only as applied to data pointed to by
|
||||
pointers, e.g. if an argument is defined as a "char*", an exception will
|
||||
pointers, e.g. if an argument is defined as a @c char*, an exception will
|
||||
be thrown if an attempt is made to retrieve it into a variable of type
|
||||
"const char*". (However, if an argument is set as a "const int", it can
|
||||
be retrieved into an "int".) The documentation of each hook point will
|
||||
detail the data type of each argument.
|
||||
@c const @c char*. (However, if an argument is set as a @c const @c int,
|
||||
it can be retrieved into an @c int.) The documentation of each hook
|
||||
point will detail the data type of each argument.
|
||||
- Although all arguments can be modified, some altered values may not
|
||||
be read by the server. (These would be ones that the server considers
|
||||
"read-only".) Consult the documentation of each hook to see whether an
|
||||
@@ -371,8 +371,8 @@ parameters can be modified. As a general rule:
|
||||
|
||||
- Do not alter arguments unless you mean the change to be reflected in
|
||||
the server.
|
||||
- If you alter an argument, call CalloutHandle::setArgument to update the
|
||||
value in the CalloutHandle object.
|
||||
- If you alter an argument, call @c CalloutHandle::setArgument to update the
|
||||
value in the @c CalloutHandle object.
|
||||
|
||||
@subsubsection hooksdgSkipFlag The "Skip" Flag
|
||||
|
||||
@@ -391,7 +391,7 @@ is a server where a callout inspects the hardware address of the client
|
||||
sending the packet and compares it against a black list; if the address
|
||||
is on it, the callout notifies the server to drop the packet.
|
||||
|
||||
To handle these common cases, the CalloutHandle has a "skip" flag.
|
||||
To handle these common cases, the @c CalloutHandle has a "skip" flag.
|
||||
This is set by a callout when it wishes the server to skip normal
|
||||
processing. It is set false by the hooks framework before callouts on a
|
||||
hook are called. If the flag is set on return, the server will take the
|
||||
@@ -427,7 +427,7 @@ Future developments may have the server processing multiple packets
|
||||
simultaneously, or to suspend processing on a packet and resume it at
|
||||
a later time after other packets have been processed.
|
||||
|
||||
As well as argument information, the CalloutHandle object can be used by
|
||||
As well as argument information, the @c CalloutHandle object can be used by
|
||||
callouts to attach information to a packet being handled by the server.
|
||||
This information (known as "context") is not used by the server: its purpose
|
||||
is to allow callouts to pass information between one another on a
|
||||
@@ -441,9 +441,9 @@ simultaneously: callouts can effectively attach data to a packet that
|
||||
follows the packet around the system.
|
||||
|
||||
Context information is held as name/value pairs in the same way
|
||||
as arguments, being accessed by the pair of methods setContext and
|
||||
getContext. They have the same restrictions as the setArgument and
|
||||
getArgument methods - the type of data retrieved from context must
|
||||
as arguments, being accessed by the pair of methods @c setContext and
|
||||
@c getContext. They have the same restrictions as the @c setArgument and
|
||||
@c getArgument methods - the type of data retrieved from context must
|
||||
<B>exactly</B> match the type of the data set.
|
||||
|
||||
The example in the next section illustrates their use.
|
||||
@@ -457,8 +457,9 @@ do this in one callout, for this example we'll use two:
|
||||
|
||||
- pkt4_receive - a callout on this hook is invoked when a packet has been
|
||||
received and has been parsed. It is passed a single argument, "query4"
|
||||
which is an isc::dhcp::Pkt4 object (representing a DHCP v4 packet).
|
||||
We will do the classification here.
|
||||
which is an isc::dhcp::Pkt4Ptr object, holding a pointer to the
|
||||
isc::dhcp::Pkt4 object (representing a DHCPv4 packet). We will do the
|
||||
classification here.
|
||||
|
||||
- pkt4_send - called when a response is just about to be sent back to
|
||||
the client. It is passed a single argument "response4". This is the
|
||||
@@ -521,7 +522,7 @@ int pkt4_receive(CalloutHandle& handle) {
|
||||
}
|
||||
@endcode
|
||||
|
||||
The pkt4_receive callout placed the hardware address of an interesting client in
|
||||
The "pkt4_receive" callout placed the hardware address of an interesting client in
|
||||
the "hwaddr" context for the packet. Turning now to the callout that will
|
||||
write this information to the log file:
|
||||
|
||||
@@ -757,12 +758,12 @@ to initialize per-request context. The second is called after all
|
||||
server-defined hooks have been processed, and is to allow a library to
|
||||
tidy up.
|
||||
|
||||
As an example, the pkt4_send example above required that the code
|
||||
As an example, the "pkt4_send" example above required that the code
|
||||
check for an exception being thrown when accessing the "hwaddr" context
|
||||
item in case it was not set. An alternative strategy would have been to
|
||||
provide a callout for the "context_create" hook and set the context item
|
||||
"hwaddr" to an empty string. Instead of needing to handle an exception,
|
||||
pkt4_send would be guaranteed to get something when looking for
|
||||
"pkt4_send" would be guaranteed to get something when looking for
|
||||
the hwaddr item and so could write or not write the output depending on
|
||||
the value.
|
||||
|
||||
@@ -771,7 +772,7 @@ automatically deletes context. An example where it could be required
|
||||
is where memory has been allocated by a callout during the processing
|
||||
of a request and a raw pointer to it stored in the context object. On
|
||||
destruction of the context, that memory will not be automatically
|
||||
released. Freeing in the memory in the "context_destroy callout will solve
|
||||
released. Freeing in the memory in the "context_destroy" callout will solve
|
||||
that problem.
|
||||
|
||||
Actually, when the context is destroyed, the destructor
|
||||
@@ -786,8 +787,8 @@ Here it is assumed that the hooks library is performing some form of
|
||||
security checking on the packet and needs to maintain information in
|
||||
a user-specified "SecurityInformation" object. (The details of this
|
||||
fictitious object are of no concern here.) The object is created in
|
||||
the context_create callout and used in both the pkt4_receive and the
|
||||
pkt4_send callouts.
|
||||
the "context_create" callout and used in both the "pkt4_receive" and the
|
||||
"pkt4_send" callouts.
|
||||
|
||||
@code
|
||||
// Storing information in a "raw" pointer. Assume that the
|
||||
@@ -831,7 +832,7 @@ int pkt4_send(CalloutHandle& handle) {
|
||||
}
|
||||
|
||||
// Context destruction. We need to delete the pointed-to SecurityInformation
|
||||
// object because we will lose the pointer to it when the CalloutHandle is
|
||||
// object because we will lose the pointer to it when the @c CalloutHandle is
|
||||
// destroyed.
|
||||
int context_destroy(CalloutHandle& handle) {
|
||||
// Retrieve the pointer to the SecurityInformation object
|
||||
@@ -843,7 +844,7 @@ int context_destroy(CalloutHandle& handle) {
|
||||
}
|
||||
@endcode
|
||||
|
||||
The requirement for the context_destroy callout can be eliminated if
|
||||
The requirement for the "context_destroy" callout can be eliminated if
|
||||
a Boost shared ptr is used to point to the allocated memory:
|
||||
|
||||
@code
|
||||
@@ -865,7 +866,7 @@ int context_create(CalloutHandle& handle) {
|
||||
}
|
||||
|
||||
// Other than the data type, a shared pointer has similar semantics to a "raw"
|
||||
// pointer. Only the code from pkt4_receive is shown here.
|
||||
// pointer. Only the code from "pkt4_receive" is shown here.
|
||||
|
||||
int pkt4_receive(CalloutHandle& handle) {
|
||||
// Retrieve the pointer to the SecurityInformation object
|
||||
@@ -881,7 +882,7 @@ int pkt4_receive(CalloutHandle& handle) {
|
||||
}
|
||||
|
||||
// No context_destroy callout is needed to delete the allocated
|
||||
// SecurityInformation object. When the CalloutHandle is destroyed, the shared
|
||||
// SecurityInformation object. When the @c CalloutHandle is destroyed, the shared
|
||||
// pointer object will be destroyed. If that is the last shared pointer to the
|
||||
// allocated memory, then it too will be deleted.
|
||||
@endcode
|
||||
@@ -915,13 +916,13 @@ registration is through the LibraryHandle object. This was briefly
|
||||
introduced in the discussion of the framework functions, in that
|
||||
an object of this type is pass to the "load" function. A LibraryHandle
|
||||
can also be obtained from within a callout by calling the CalloutHandle's
|
||||
getLibraryHandle() method.
|
||||
@c getLibraryHandle() method.
|
||||
|
||||
The LibraryHandle provides three methods to manipulate callouts:
|
||||
|
||||
- registerCallout - register a callout on a hook.
|
||||
- deregisterCallout - deregister a callout from a hook.
|
||||
- deregisterAllCallouts - deregister all callouts on a hook.
|
||||
- @c registerCallout - register a callout on a hook.
|
||||
- @c deregisterCallout - deregister a callout from a hook.
|
||||
- @c deregisterAllCallouts - deregister all callouts on a hook.
|
||||
|
||||
The following sections cover some of the ways in which these can be used.
|
||||
|
||||
@@ -960,7 +961,7 @@ a hook point. Although it is likely to be rare for user code to need to
|
||||
do this, there may be instances where it make sense.
|
||||
|
||||
To register multiple callouts on a hook, just call
|
||||
LibraryHandle::registerCallout multiple times on the same hook, e.g.
|
||||
@c LibraryHandle::registerCallout multiple times on the same hook, e.g.
|
||||
|
||||
@code
|
||||
libhandle.registerCallout("pkt4_receive", classify);
|
||||
@@ -968,7 +969,7 @@ LibraryHandle::registerCallout multiple times on the same hook, e.g.
|
||||
@endcode
|
||||
|
||||
The hooks framework will call the callouts in the order they are
|
||||
registered. The same CalloutHandle is passed between them, so any
|
||||
registered. The same @c CalloutHandle is passed between them, so any
|
||||
change made to the CalloutHandle's arguments, "skip" flag, or per-request
|
||||
context by the first is visible to the second.
|
||||
|
||||
@@ -1036,7 +1037,7 @@ int write_data(CalloutHandle& handle) {
|
||||
flush(interesting);
|
||||
|
||||
// We've logged the data, so deregister ourself. This callout will not
|
||||
// be called again until it is registered by pkt4_receive.
|
||||
// be called again until it is registered by "pkt4_receive".
|
||||
|
||||
handle.getLibraryHandle().deregisterCallout("pkt4_send", write_data);
|
||||
|
||||
@@ -1093,7 +1094,7 @@ request.
|
||||
|
||||
The vertical blue lines represent callout context. Context is
|
||||
per-packet but also per-library. When the server calls "authorize",
|
||||
the CalloutHandle's getContext and setContext methods access a context
|
||||
the CalloutHandle's @c getContext and @c setContext methods access a context
|
||||
created purely for library 1. The next callout on the hook will access
|
||||
context created for library 2. These contexts are passed to the callouts
|
||||
associated with the next hook. So when "check" is called, it gets the
|
||||
@@ -1132,7 +1133,7 @@ as separate elements of the hooks-libraries configuration element, e.g.
|
||||
|
||||
In rare cases, it is possible that one library may want to pass
|
||||
data to another. This can be done in a limited way by means of the
|
||||
CalloutHandle's setArgument and getArgument calls. For example, in the
|
||||
CalloutHandle's @c setArgument and @c getArgument calls. For example, in the
|
||||
above diagram, the callout "add_option" can pass a value to "putopt"
|
||||
by setting a name.value pair in the hook's argument list. "putopt"
|
||||
would be able to read this, but would not be able to return information
|
||||
@@ -1185,7 +1186,7 @@ to add one.) For example:
|
||||
extern "C" {
|
||||
|
||||
int version() {
|
||||
return (BIND10_HOOKS_VERSION);
|
||||
return (KEA_HOOKS_VERSION);
|
||||
}
|
||||
|
||||
int load() {
|
||||
|
||||
Reference in New Issue
Block a user