// 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 Kea Developer's Guide 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 "/lib" where 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. */