diff options
Diffstat (limited to 'src/hooks/dhcp/run_script/run_script.dox')
| -rw-r--r-- | src/hooks/dhcp/run_script/run_script.dox | 673 |
1 files changed, 673 insertions, 0 deletions
diff --git a/src/hooks/dhcp/run_script/run_script.dox b/src/hooks/dhcp/run_script/run_script.dox new file mode 100644 index 0000000..3fbcd12 --- /dev/null +++ b/src/hooks/dhcp/run_script/run_script.dox @@ -0,0 +1,673 @@ +// Copyright (C) 2021 Internet Systems Consortium, Inc. ("ISC") +// +// This Source Code Form is subject to the terms of the Mozilla Public +// License, v. 2.0. If a copy of the MPL was not distributed with this +// file, You can obtain one at http://mozilla.org/MPL/2.0/. + +/** + +@page libdhcp_run_script Kea Run Script Hooks Library + +@section libdhcp_run_scriptIntro Introduction + +Welcome to Kea Run Script Hooks Library. This documentation is addressed to +developers who are interested in the internal operation of the Run Script +library. This file provides information needed to understand and +perhaps extend this library. + +This documentation is stand-alone: you should have read and understood +the <a href="https://reports.kea.isc.org/dev_guide/">Kea +Developer's Guide</a> and in particular its section about hooks. + +@section libdhcp_run_scriptUser Now To Use libdhcp_run_script +## Introduction +libdhcp_run_script is a hooks library which allows an external script to +be run on specific hook points. + +## Configuring the DHCPv4 and DHCPv6 Modules + +It must be configured as a hook library for the desired DHCP server +modules. Note that the Run Script library is installed alongside the +Kea libraries in "<install-dir>/lib" where <install-dir> is determined +by the --prefix option of the configure script. It defaults to +"/usr/local". + +Configuring kea-dhcp4 to load the Run Script library could be done with +the following Kea4 configuration: + +@code +"Dhcp4": { + "hooks-libraries": [ + { "library": "/usr/local/lib/libdhcp_run_script.so", + "parameters": { + "name": "/full_path_to/script_name.sh", + "sync": false + } + }, + ... + ] +} +@endcode + +Configuring kea-dhcp6 to load the Run Script library could be done with +the following Kea6 configuration: + +@code +"Dhcp6": { + "hooks-libraries": [ + { "library": "/usr/local/lib/libdhcp_run_script.so", + "parameters": { + "name": "/full_path_to/script_name.sh", + "sync": false + } + }, + ... + ] +} +@endcode + +The parameters contain the 'name' which indicates the full path to the external +script to be called on each hookpoint, and also the 'sync' option to be able +to wait synchronously for the script to finish execution. +If the 'sync' parameter is false, then the script will be launched and Kea +will not wait for the execution to finish, causing all the OUT parameters of +the script (including next step) to be ignored. + +The script inherits all privileges from the server which calls it. + +Currently the functionality underneath 'sync' parameter is not implemented +and enabling synchronous calls to external script is not supported. + +## Internal operation + +The first function called in @ref load() located in the +run_script_callouts.cc. It checks if the necessary parameter is passed and +decodes the option configurations. @ref unload() free the configuration. + +Kea engine checks if the library has functions that match known hook +point names. This library has several such functions: @ref lease4_renew, +@ref lease4_expire, @ref lease4_recover, @ref leases4_committed, +@ref lease4_release, @ref lease4_decline, @ref lease6_renew, +@ref lease6_rebind, @ref lease6_expire, @ref lease6_recover, +@ref leases6_committed, @ref lease6_release, @ref lease6_decline located +in run_script_callouts.cc. + +Each hook point extracts the Kea internal data and exports it as string +environment variables. These parameters are shared with the target script +using the child process environment. +The only parameter passed to the call of the target script is the name of +the hook point. + +An example of a script implementing all hook points is presented below. + +@code +#!/bin/bash + +unknown_handle() { + echo "Unhandled function call ${*}" + exit 123 +} + +lease4_renew () { + ... +} + +lease4_expire () { + ... +} + +lease4_recover () { + ... +} + +leases4_committed () { + ... +} + +lease4_release () { + ... +} + +lease4_decline () { + ... +} + +lease6_renew () { + ... +} + +lease6_rebind () { + ... +} + +lease6_expire () { + ... +} + +lease6_recover () { + ... +} + +leases6_committed () { + ... +} + +lease6_release () { + ... +} + +lease6_decline () { + ... +} + +case "$1" in + "lease4_renew") + lease4_renew + ;; + "lease4_expire") + lease4_expire + ;; + "lease4_recover") + lease4_recover + ;; + "leases4_committed") + leases4_committed + ;; + "lease4_release") + lease4_release + ;; + "lease4_decline") + lease4_decline + ;; + "lease6_renew") + lease6_renew + ;; + "lease6_rebind") + lease6_rebind + ;; + "lease6_expire") + lease6_expire + ;; + "lease6_recover") + lease6_recover + ;; + "leases6_committed") + leases6_committed + ;; + "lease6_release") + lease6_release + ;; + "lease6_decline") + lease6_decline + ;; + *) + unknown_handle "${@}" + ;; +esac + +@endcode + +Available parameters for each hook points are presented below. + +lease4_renew + +@code + +QUERY4_TYPE +QUERY4_TXID +QUERY4_LOCAL_ADDR +QUERY4_LOCAL_PORT +QUERY4_REMOTE_ADDR +QUERY4_REMOTE_PORT +QUERY4_IFACE_INDEX +QUERY4_IFACE_NAME +QUERY4_HOPS +QUERY4_SECS +QUERY4_FLAGS +QUERY4_CIADDR +QUERY4_SIADDR +QUERY4_YIADDR +QUERY4_GIADDR +QUERY4_RELAYED +QUERY4_HWADDR +QUERY4_HWADDR_TYPE +QUERY4_LOCAL_HWADDR +QUERY4_LOCAL_HWADDR_TYPE +QUERY4_REMOTE_HWADDR +QUERY4_REMOTE_HWADDR_TYPE +QUERY4_OPTION_82 +QUERY4_OPTION_82_SUB_OPTION_1 +QUERY4_OPTION_82_SUB_OPTION_2 +SUBNET4_ID +SUBNET4_NAME +SUBNET4_PREFIX +SUBNET4_PREFIX_LEN +PKT4_CLIENT_ID +PKT4_HWADDR +PKT4_HWADDR_TYPE +LEASE4_ADDRESS +LEASE4_CLTT +LEASE4_HOSTNAME +LEASE4_HWADDR +LEASE4_HWADDR_TYPE +LEASE4_STATE +LEASE4_SUBNET_ID +LEASE4_VALID_LIFETIME +LEASE4_CLIENT_ID + +@endcode + +lease4_expire + +@code + +LEASE4_ADDRESS +LEASE4_CLTT +LEASE4_HOSTNAME +LEASE4_HWADDR +LEASE4_HWADDR_TYPE +LEASE4_STATE +LEASE4_SUBNET_ID +LEASE4_VALID_LIFETIME +LEASE4_CLIENT_ID +REMOVE_LEASE + +@endcode + +lease4_recover + +@code + +LEASE4_ADDRESS +LEASE4_CLTT +LEASE4_HOSTNAME +LEASE4_HWADDR +LEASE4_HWADDR_TYPE +LEASE4_STATE +LEASE4_SUBNET_ID +LEASE4_VALID_LIFETIME +LEASE4_CLIENT_ID + +@endcode + +leases4_committed + +@code + +QUERY4_TYPE +QUERY4_TXID +QUERY4_LOCAL_ADDR +QUERY4_LOCAL_PORT +QUERY4_REMOTE_ADDR +QUERY4_REMOTE_PORT +QUERY4_IFACE_INDEX +QUERY4_IFACE_NAME +QUERY4_HOPS +QUERY4_SECS +QUERY4_FLAGS +QUERY4_CIADDR +QUERY4_SIADDR +QUERY4_YIADDR +QUERY4_GIADDR +QUERY4_RELAYED +QUERY4_HWADDR +QUERY4_HWADDR_TYPE +QUERY4_LOCAL_HWADDR +QUERY4_LOCAL_HWADDR_TYPE +QUERY4_REMOTE_HWADDR +QUERY4_REMOTE_HWADDR_TYPE +QUERY4_OPTION_82 +QUERY4_OPTION_82_SUB_OPTION_1 +QUERY4_OPTION_82_SUB_OPTION_2 +LEASES4_SIZE +DELETED_LEASES4_SIZE + +@endcode + +If LEASES4_SIZE or DELETED_LEASES4_SIZE are non zero, then each lease +will have it's own unique identifier as shown below. First index starts +at 0. + +@code + +LEASES4_AT0_ADDRESS +LEASES4_AT0_CLTT +LEASES4_AT0_HOSTNAME +LEASES4_AT0_HWADDR +LEASES4_AT0_HWADDR_TYPE +LEASES4_AT0_STATE +LEASES4_AT0_SUBNET_ID +LEASES4_AT0_VALID_LIFETIME +LEASES4_AT0_CLIENT_ID +DELETED_LEASES4_AT0_ADDRESS +DELETED_LEASES4_AT0_CLTT +DELETED_LEASES4_AT0_HOSTNAME +DELETED_LEASES4_AT0_HWADDR +DELETED_LEASES4_AT0_HWADDR_TYPE +DELETED_LEASES4_AT0_STATE +DELETED_LEASES4_AT0_SUBNET_ID +DELETED_LEASES4_AT0_VALID_LIFETIME +DELETED_LEASES4_AT0_CLIENT_ID + +@endcode + +lease4_release + +@code + +QUERY4_TYPE +QUERY4_TXID +QUERY4_LOCAL_ADDR +QUERY4_LOCAL_PORT +QUERY4_REMOTE_ADDR +QUERY4_REMOTE_PORT +QUERY4_IFACE_INDEX +QUERY4_IFACE_NAME +QUERY4_HOPS +QUERY4_SECS +QUERY4_FLAGS +QUERY4_CIADDR +QUERY4_SIADDR +QUERY4_YIADDR +QUERY4_GIADDR +QUERY4_RELAYED +QUERY4_HWADDR +QUERY4_HWADDR_TYPE +QUERY4_LOCAL_HWADDR +QUERY4_LOCAL_HWADDR_TYPE +QUERY4_REMOTE_HWADDR +QUERY4_REMOTE_HWADDR_TYPE +QUERY4_OPTION_82 +QUERY4_OPTION_82_SUB_OPTION_1 +QUERY4_OPTION_82_SUB_OPTION_2 +LEASE4_ADDRESS +LEASE4_CLTT +LEASE4_HOSTNAME +LEASE4_HWADDR +LEASE4_HWADDR_TYPE +LEASE4_STATE +LEASE4_SUBNET_ID +LEASE4_VALID_LIFETIME +LEASE4_CLIENT_ID + +@endcode + +lease4_decline + +@code + +QUERY4_TYPE +QUERY4_TXID +QUERY4_LOCAL_ADDR +QUERY4_LOCAL_PORT +QUERY4_REMOTE_ADDR +QUERY4_REMOTE_PORT +QUERY4_IFACE_INDEX +QUERY4_IFACE_NAME +QUERY4_HOPS +QUERY4_SECS +QUERY4_FLAGS +QUERY4_CIADDR +QUERY4_SIADDR +QUERY4_YIADDR +QUERY4_GIADDR +QUERY4_RELAYED +QUERY4_HWADDR +QUERY4_HWADDR_TYPE +QUERY4_LOCAL_HWADDR +QUERY4_LOCAL_HWADDR_TYPE +QUERY4_REMOTE_HWADDR +QUERY4_REMOTE_HWADDR_TYPE +QUERY4_OPTION_82 +QUERY4_OPTION_82_SUB_OPTION_1 +QUERY4_OPTION_82_SUB_OPTION_2 +LEASE4_ADDRESS +LEASE4_CLTT +LEASE4_HOSTNAME +LEASE4_HWADDR +LEASE4_HWADDR_TYPE +LEASE4_STATE +LEASE4_SUBNET_ID +LEASE4_VALID_LIFETIME +LEASE4_CLIENT_ID + +@endcode + +lease6_renew + +@code + +QUERY6_TYPE +QUERY6_TXID +QUERY6_LOCAL_ADDR +QUERY6_LOCAL_PORT +QUERY6_REMOTE_ADDR +QUERY6_REMOTE_PORT +QUERY6_IFACE_INDEX +QUERY6_IFACE_NAME +QUERY6_REMOTE_HWADDR +QUERY6_REMOTE_HWADDR_TYPE +QUERY6_PROTO +QUERY6_CLIENT_ID +LEASE6_ADDRESS +LEASE6_CLTT +LEASE6_HOSTNAME +LEASE6_HWADDR +LEASE6_HWADDR_TYPE +LEASE6_STATE +LEASE6_SUBNET_ID +LEASE6_VALID_LIFETIME +LEASE6_DUID +LEASE6_IAID +LEASE6_PREFERRED_LIFETIME +LEASE6_PREFIX_LEN +LEASE6_TYPE +PKT6_IA_IAID +PKT6_IA_IA_TYPE +PKT6_IA_IA_T1 +PKT6_IA_IA_T2 + +@endcode + +lease6_rebind + +@code + +QUERY6_TYPE +QUERY6_TXID +QUERY6_LOCAL_ADDR +QUERY6_LOCAL_PORT +QUERY6_REMOTE_ADDR +QUERY6_REMOTE_PORT +QUERY6_IFACE_INDEX +QUERY6_IFACE_NAME +QUERY6_REMOTE_HWADDR +QUERY6_REMOTE_HWADDR_TYPE +QUERY6_PROTO +QUERY6_CLIENT_ID +LEASE6_ADDRESS +LEASE6_CLTT +LEASE6_HOSTNAME +LEASE6_HWADDR +LEASE6_HWADDR_TYPE +LEASE6_STATE +LEASE6_SUBNET_ID +LEASE6_VALID_LIFETIME +LEASE6_DUID +LEASE6_IAID +LEASE6_PREFERRED_LIFETIME +LEASE6_PREFIX_LEN +LEASE6_TYPE +PKT6_IA_IAID +PKT6_IA_IA_TYPE +PKT6_IA_IA_T1 +PKT6_IA_IA_T2 + +@endcode + +lease6_expire + +@code + +LEASE6_ADDRESS +LEASE6_CLTT +LEASE6_HOSTNAME +LEASE6_HWADDR +LEASE6_HWADDR_TYPE +LEASE6_STATE +LEASE6_SUBNET_ID +LEASE6_VALID_LIFETIME +LEASE6_DUID +LEASE6_IAID +LEASE6_PREFERRED_LIFETIME +LEASE6_PREFIX_LEN +LEASE6_TYPE +REMOVE_LEASE + +@endcode + +lease6_recover + +@code + +LEASE6_ADDRESS +LEASE6_CLTT +LEASE6_HOSTNAME +LEASE6_HWADDR +LEASE6_HWADDR_TYPE +LEASE6_STATE +LEASE6_SUBNET_ID +LEASE6_VALID_LIFETIME +LEASE6_DUID +LEASE6_IAID +LEASE6_PREFERRED_LIFETIME +LEASE6_PREFIX_LEN +LEASE6_TYPE + +@endcode + +leases6_committed + +@code + +QUERY6_TYPE +QUERY6_TXID +QUERY6_LOCAL_ADDR +QUERY6_LOCAL_PORT +QUERY6_REMOTE_ADDR +QUERY6_REMOTE_PORT +QUERY6_IFACE_INDEX +QUERY6_IFACE_NAME +QUERY6_REMOTE_HWADDR +QUERY6_REMOTE_HWADDR_TYPE +QUERY6_PROTO +QUERY6_CLIENT_ID +LEASES6_SIZE +DELETED_LEASES6_SIZE + +@endcode + +If LEASES6_SIZE or DELETED_LEASES6_SIZE are non zero, then each lease +will have it's own unique identifier as shown below. First index starts +at 0. + +@code + +LEASES6_AT0_ADDRESS +LEASES6_AT0_CLTT +LEASES6_AT0_HOSTNAME +LEASES6_AT0_HWADDR +LEASES6_AT0_HWADDR_TYPE +LEASES6_AT0_STATE +LEASES6_AT0_SUBNET_ID +LEASES6_AT0_VALID_LIFETIME +LEASES6_AT0_DUID +LEASES6_AT0_IAID +LEASES6_AT0_PREFERRED_LIFETIME +LEASES6_AT0_PREFIX_LEN +LEASES6_AT0_TYPE +DELETED_LEASES6_AT0_ADDRESS +DELETED_LEASES6_AT0_CLTT +DELETED_LEASES6_AT0_HOSTNAME +DELETED_LEASES6_AT0_HWADDR +DELETED_LEASES6_AT0_HWADDR_TYPE +DELETED_LEASES6_AT0_STATE +DELETED_LEASES6_AT0_SUBNET_ID +DELETED_LEASES6_AT0_VALID_LIFETIME +DELETED_LEASES6_AT0_DUID +DELETED_LEASES6_AT0_IAID +DELETED_LEASES6_AT0_PREFERRED_LIFETIME +DELETED_LEASES6_AT0_PREFIX_LEN +DELETED_LEASES6_AT0_TYPE + +@endcode + +lease6_release + +@code + +QUERY6_TYPE +QUERY6_TXID +QUERY6_LOCAL_ADDR +QUERY6_LOCAL_PORT +QUERY6_REMOTE_ADDR +QUERY6_REMOTE_PORT +QUERY6_IFACE_INDEX +QUERY6_IFACE_NAME +QUERY6_REMOTE_HWADDR +QUERY6_REMOTE_HWADDR_TYPE +QUERY6_PROTO +QUERY6_CLIENT_ID +LEASE6_ADDRESS +LEASE6_CLTT +LEASE6_HOSTNAME +LEASE6_HWADDR +LEASE6_HWADDR_TYPE +LEASE6_STATE +LEASE6_SUBNET_ID +LEASE6_VALID_LIFETIME +LEASE6_DUID +LEASE6_IAID +LEASE6_PREFERRED_LIFETIME +LEASE6_PREFIX_LEN +LEASE6_TYPE + +@endcode + +lease6_decline + +@code + +QUERY6_TYPE +QUERY6_TXID +QUERY6_LOCAL_ADDR +QUERY6_LOCAL_PORT +QUERY6_REMOTE_ADDR +QUERY6_REMOTE_PORT +QUERY6_IFACE_INDEX +QUERY6_IFACE_NAME +QUERY6_REMOTE_HWADDR +QUERY6_REMOTE_HWADDR_TYPE +QUERY6_PROTO +QUERY6_CLIENT_ID +LEASE6_ADDRESS +LEASE6_CLTT +LEASE6_HOSTNAME +LEASE6_HWADDR +LEASE6_HWADDR_TYPE +LEASE6_STATE +LEASE6_SUBNET_ID +LEASE6_VALID_LIFETIME +LEASE6_DUID +LEASE6_IAID +LEASE6_PREFERRED_LIFETIME +LEASE6_PREFIX_LEN +LEASE6_TYPE + +@endcode + +@section libdhcp_run_scriptMTCompatibility Multi-Threading Compatibility + +The Run Script hooks library is compatible with multi-threading. + +*/ |