diff options
Diffstat (limited to 'doc/sphinx/arm/hooks-run-script.rst')
| -rw-r--r-- | doc/sphinx/arm/hooks-run-script.rst | 623 |
1 files changed, 623 insertions, 0 deletions
diff --git a/doc/sphinx/arm/hooks-run-script.rst b/doc/sphinx/arm/hooks-run-script.rst new file mode 100644 index 0000000000..ae7a87b4f6 --- /dev/null +++ b/doc/sphinx/arm/hooks-run-script.rst @@ -0,0 +1,623 @@ +.. _hooks-run-script: + +Run Script Support +================== + +This hooks library adds support for calling an external script with vendor information extensions + +The library is available since Kea 1.9.5 and can be loaded in a +similar way as other hook libraries by the ``kea-dhcp4`` and +``kea-dhcp6`` processes. + +:: + + "Dhcp4": { + "hook_libraries": [ + { "library": "/usr/local/lib/libdhcp_run_script.so", + "parameters": { + "name": "/path_to/script_name.sh", + "sync": false + } + }, + ... + ] + } + +:: + + "Dhcp6": { + "hook_libraries": [ + { "library": "/usr/local/lib/libdhcp_run_script.so", + "parameters": { + "name": "/path_to/script_name.sh", + "sync": false + } + }, + ... + ] + } + + +The parameters contain the 'name' which indicates the path and name of 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. + + +.. note:: + + Currently the functionality underneath 'sync' parameter is not implemented + and enabling synchronous calls to external script is not supported. + + +.. _hooks-run-script-hook-points: + +This library has several hook points functions implemented which will be +called at the specific packet processing stage. + +The dhcpv4 hook points: + +:: + + lease4_renew + lease4_expire + lease4_recover + leases4_committed + lease4_release + lease4_decline + + +The dhcpv6 hook points: + +:: + + lease6_renew + lease6_rebind + lease6_expire + lease6_recover + leases6_committed + lease6_release + lease6_decline + +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. + +:: + + #!/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 + + +.. _hooks-run-script-exported-environment-variables: + +Available parameters for each hook points are presented below. + +DHCPv4: + +lease4_renew + +:: + + 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 + 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 + +lease4_expire + +:: + + LEASE4_ADDRESS + LEASE4_CLTT + LEASE4_HOSTNAME + LEASE4_HWADDR + LEASE4_HWADDR_TYPE + LEASE4_STATE + LEASE4_SUBNET_ID + LEASE4_VALID_LIFETIME + LEASE4_CLIENT_ID + REMOVE_LEASE + +lease4_recover + +:: + + LEASE4_ADDRESS + LEASE4_CLTT + LEASE4_HOSTNAME + LEASE4_HWADDR + LEASE4_HWADDR_TYPE + LEASE4_STATE + LEASE4_SUBNET_ID + LEASE4_VALID_LIFETIME + LEASE4_CLIENT_ID + +leases4_committed + +:: + + 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 + LEASES4_SIZE + DELETED_LEASES4_SIZE + +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. + +:: + + 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 + +lease4_release + +:: + + 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 + LEASE4_ADDRESS + LEASE4_CLTT + LEASE4_HOSTNAME + LEASE4_HWADDR + LEASE4_HWADDR_TYPE + LEASE4_STATE + LEASE4_SUBNET_ID + LEASE4_VALID_LIFETIME + LEASE4_CLIENT_ID + +lease4_decline + +:: + + 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 + LEASE4_ADDRESS + LEASE4_CLTT + LEASE4_HOSTNAME + LEASE4_HWADDR + LEASE4_HWADDR_TYPE + LEASE4_STATE + LEASE4_SUBNET_ID + LEASE4_VALID_LIFETIME + LEASE4_CLIENT_ID + +DHCPv6: + +lease6_renew + +:: + + 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 + +lease6_rebind + +:: + + 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 + +lease6_expire + +:: + + 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 + +lease6_recover + +:: + + 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 + +leases6_committed + +:: + + 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 + +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. + +:: + + 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 + +lease6_release + +:: + + 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 + +lease6_decline + +:: + + 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 + + |