1.. _hooks-run-script: 2 3Run Script Support 4================== 5 6This hooks library adds support for calling an external script for specific 7packet processing hook points. 8 9The library is available since Kea 1.9.5 and can be loaded in a 10similar way as other hook libraries by the ``kea-dhcp4`` and 11``kea-dhcp6`` processes. 12 13.. code-block:: json 14 15 { 16 "hooks-libraries": [ 17 { 18 "library": "/usr/local/lib/libdhcp_run_script.so", 19 "parameters": { 20 "name": "/full_path_to/script_name.sh", 21 "sync": false 22 } 23 } 24 ] 25 } 26 27The parameters contain the 'name' which indicates the full path to the external 28script to be called on each hookpoint, and also the 'sync' option to be able 29to wait synchronously for the script to finish execution. 30If the 'sync' parameter is false, then the script will be launched and Kea 31will not wait for the execution to finish, causing all the OUT parameters of 32the script (including next step) to be ignored. 33 34.. note:: 35 36 The script inherits all privileges from the server which calls it. 37 38.. note:: 39 40 Currently the functionality underneath 'sync' parameter is not implemented 41 and enabling synchronous calls to external scripts is not supported. 42 43.. _hooks-run-script-hook-points: 44 45This library has several hook points functions implemented which will be 46called at the specific packet processing stage. 47 48The dhcpv4 hook points: 49 50:: 51 52 lease4_renew 53 lease4_expire 54 lease4_recover 55 leases4_committed 56 lease4_release 57 lease4_decline 58 59 60The dhcpv6 hook points: 61 62:: 63 64 lease6_renew 65 lease6_rebind 66 lease6_expire 67 lease6_recover 68 leases6_committed 69 lease6_release 70 lease6_decline 71 72Each hook point extracts the Kea internal data and exports it as string 73environment variables. These parameters are shared with the target script 74using the child process environment. 75The only parameter passed to the call of the target script is the name of 76the hook point. 77 78An example of a script implementing all hook points is presented below. 79 80:: 81 82 #!/bin/bash 83 84 unknown_handle() { 85 echo "Unhandled function call ${*}" 86 exit 123 87 } 88 89 90 lease4_renew () { 91 ... 92 } 93 94 lease4_expire () { 95 ... 96 } 97 98 lease4_recover () { 99 ... 100 } 101 102 leases4_committed () { 103 ... 104 } 105 106 lease4_release () { 107 ... 108 } 109 110 lease4_decline () { 111 ... 112 } 113 114 lease6_renew () { 115 ... 116 } 117 118 lease6_rebind () { 119 ... 120 } 121 122 lease6_expire () { 123 ... 124 } 125 126 lease6_recover () { 127 ... 128 } 129 130 leases6_committed () { 131 ... 132 } 133 134 lease6_release () { 135 ... 136 } 137 138 lease6_decline () { 139 ... 140 } 141 142 case "$1" in 143 "lease4_renew") 144 lease4_renew 145 ;; 146 "lease4_expire") 147 lease4_expire 148 ;; 149 "lease4_recover") 150 lease4_recover 151 ;; 152 "leases4_committed") 153 leases4_committed 154 ;; 155 "lease4_release") 156 lease4_release 157 ;; 158 "lease4_decline") 159 lease4_decline 160 ;; 161 "lease6_renew") 162 lease6_renew 163 ;; 164 "lease6_rebind") 165 lease6_rebind 166 ;; 167 "lease6_expire") 168 lease6_expire 169 ;; 170 "lease6_recover") 171 lease6_recover 172 ;; 173 "leases6_committed") 174 leases6_committed 175 ;; 176 "lease6_release") 177 lease6_release 178 ;; 179 "lease6_decline") 180 lease6_decline 181 ;; 182 *) 183 unknown_handle "${@}" 184 ;; 185 esac 186 187 188.. _hooks-run-script-exported-environment-variables: 189 190Available parameters for each hook point are presented below. 191 192DHCPv4: 193 194lease4_renew 195 196:: 197 198 QUERY4_TYPE 199 QUERY4_TXID 200 QUERY4_LOCAL_ADDR 201 QUERY4_LOCAL_PORT 202 QUERY4_REMOTE_ADDR 203 QUERY4_REMOTE_PORT 204 QUERY4_IFACE_INDEX 205 QUERY4_IFACE_NAME 206 QUERY4_HOPS 207 QUERY4_SECS 208 QUERY4_FLAGS 209 QUERY4_CIADDR 210 QUERY4_SIADDR 211 QUERY4_YIADDR 212 QUERY4_GIADDR 213 QUERY4_RELAYED 214 QUERY4_HWADDR 215 QUERY4_HWADDR_TYPE 216 QUERY4_LOCAL_HWADDR 217 QUERY4_LOCAL_HWADDR_TYPE 218 QUERY4_REMOTE_HWADDR 219 QUERY4_REMOTE_HWADDR_TYPE 220 QUERY4_OPTION_82 221 QUERY4_OPTION_82_SUB_OPTION_1 222 QUERY4_OPTION_82_SUB_OPTION_2 223 SUBNET4_ID 224 SUBNET4_NAME 225 SUBNET4_PREFIX 226 SUBNET4_PREFIX_LEN 227 PKT4_CLIENT_ID 228 PKT4_HWADDR 229 PKT4_HWADDR_TYPE 230 LEASE4_ADDRESS 231 LEASE4_CLTT 232 LEASE4_HOSTNAME 233 LEASE4_HWADDR 234 LEASE4_HWADDR_TYPE 235 LEASE4_STATE 236 LEASE4_SUBNET_ID 237 LEASE4_VALID_LIFETIME 238 LEASE4_CLIENT_ID 239 240lease4_expire 241 242:: 243 244 LEASE4_ADDRESS 245 LEASE4_CLTT 246 LEASE4_HOSTNAME 247 LEASE4_HWADDR 248 LEASE4_HWADDR_TYPE 249 LEASE4_STATE 250 LEASE4_SUBNET_ID 251 LEASE4_VALID_LIFETIME 252 LEASE4_CLIENT_ID 253 REMOVE_LEASE 254 255lease4_recover 256 257:: 258 259 LEASE4_ADDRESS 260 LEASE4_CLTT 261 LEASE4_HOSTNAME 262 LEASE4_HWADDR 263 LEASE4_HWADDR_TYPE 264 LEASE4_STATE 265 LEASE4_SUBNET_ID 266 LEASE4_VALID_LIFETIME 267 LEASE4_CLIENT_ID 268 269leases4_committed 270 271:: 272 273 QUERY4_TYPE 274 QUERY4_TXID 275 QUERY4_LOCAL_ADDR 276 QUERY4_LOCAL_PORT 277 QUERY4_REMOTE_ADDR 278 QUERY4_REMOTE_PORT 279 QUERY4_IFACE_INDEX 280 QUERY4_IFACE_NAME 281 QUERY4_HOPS 282 QUERY4_SECS 283 QUERY4_FLAGS 284 QUERY4_CIADDR 285 QUERY4_SIADDR 286 QUERY4_YIADDR 287 QUERY4_GIADDR 288 QUERY4_RELAYED 289 QUERY4_HWADDR 290 QUERY4_HWADDR_TYPE 291 QUERY4_LOCAL_HWADDR 292 QUERY4_LOCAL_HWADDR_TYPE 293 QUERY4_REMOTE_HWADDR 294 QUERY4_REMOTE_HWADDR_TYPE 295 QUERY4_OPTION_82 296 QUERY4_OPTION_82_SUB_OPTION_1 297 QUERY4_OPTION_82_SUB_OPTION_2 298 LEASES4_SIZE 299 DELETED_LEASES4_SIZE 300 301If LEASES4_SIZE or DELETED_LEASES4_SIZE are non zero, then each lease 302will have its own unique identifier as shown below. First index starts 303at 0. 304 305:: 306 307 LEASES4_AT0_ADDRESS 308 LEASES4_AT0_CLTT 309 LEASES4_AT0_HOSTNAME 310 LEASES4_AT0_HWADDR 311 LEASES4_AT0_HWADDR_TYPE 312 LEASES4_AT0_STATE 313 LEASES4_AT0_SUBNET_ID 314 LEASES4_AT0_VALID_LIFETIME 315 LEASES4_AT0_CLIENT_ID 316 DELETED_LEASES4_AT0_ADDRESS 317 DELETED_LEASES4_AT0_CLTT 318 DELETED_LEASES4_AT0_HOSTNAME 319 DELETED_LEASES4_AT0_HWADDR 320 DELETED_LEASES4_AT0_HWADDR_TYPE 321 DELETED_LEASES4_AT0_STATE 322 DELETED_LEASES4_AT0_SUBNET_ID 323 DELETED_LEASES4_AT0_VALID_LIFETIME 324 DELETED_LEASES4_AT0_CLIENT_ID 325 326lease4_release 327 328:: 329 330 QUERY4_TYPE 331 QUERY4_TXID 332 QUERY4_LOCAL_ADDR 333 QUERY4_LOCAL_PORT 334 QUERY4_REMOTE_ADDR 335 QUERY4_REMOTE_PORT 336 QUERY4_IFACE_INDEX 337 QUERY4_IFACE_NAME 338 QUERY4_HOPS 339 QUERY4_SECS 340 QUERY4_FLAGS 341 QUERY4_CIADDR 342 QUERY4_SIADDR 343 QUERY4_YIADDR 344 QUERY4_GIADDR 345 QUERY4_RELAYED 346 QUERY4_HWADDR 347 QUERY4_HWADDR_TYPE 348 QUERY4_LOCAL_HWADDR 349 QUERY4_LOCAL_HWADDR_TYPE 350 QUERY4_REMOTE_HWADDR 351 QUERY4_REMOTE_HWADDR_TYPE 352 QUERY4_OPTION_82 353 QUERY4_OPTION_82_SUB_OPTION_1 354 QUERY4_OPTION_82_SUB_OPTION_2 355 LEASE4_ADDRESS 356 LEASE4_CLTT 357 LEASE4_HOSTNAME 358 LEASE4_HWADDR 359 LEASE4_HWADDR_TYPE 360 LEASE4_STATE 361 LEASE4_SUBNET_ID 362 LEASE4_VALID_LIFETIME 363 LEASE4_CLIENT_ID 364 365lease4_decline 366 367:: 368 369 QUERY4_TYPE 370 QUERY4_TXID 371 QUERY4_LOCAL_ADDR 372 QUERY4_LOCAL_PORT 373 QUERY4_REMOTE_ADDR 374 QUERY4_REMOTE_PORT 375 QUERY4_IFACE_INDEX 376 QUERY4_IFACE_NAME 377 QUERY4_HOPS 378 QUERY4_SECS 379 QUERY4_FLAGS 380 QUERY4_CIADDR 381 QUERY4_SIADDR 382 QUERY4_YIADDR 383 QUERY4_GIADDR 384 QUERY4_RELAYED 385 QUERY4_HWADDR 386 QUERY4_HWADDR_TYPE 387 QUERY4_LOCAL_HWADDR 388 QUERY4_LOCAL_HWADDR_TYPE 389 QUERY4_REMOTE_HWADDR 390 QUERY4_REMOTE_HWADDR_TYPE 391 QUERY4_OPTION_82 392 QUERY4_OPTION_82_SUB_OPTION_1 393 QUERY4_OPTION_82_SUB_OPTION_2 394 LEASE4_ADDRESS 395 LEASE4_CLTT 396 LEASE4_HOSTNAME 397 LEASE4_HWADDR 398 LEASE4_HWADDR_TYPE 399 LEASE4_STATE 400 LEASE4_SUBNET_ID 401 LEASE4_VALID_LIFETIME 402 LEASE4_CLIENT_ID 403 404DHCPv6: 405 406lease6_renew 407 408:: 409 410 QUERY6_TYPE 411 QUERY6_TXID 412 QUERY6_LOCAL_ADDR 413 QUERY6_LOCAL_PORT 414 QUERY6_REMOTE_ADDR 415 QUERY6_REMOTE_PORT 416 QUERY6_IFACE_INDEX 417 QUERY6_IFACE_NAME 418 QUERY6_REMOTE_HWADDR 419 QUERY6_REMOTE_HWADDR_TYPE 420 QUERY6_PROTO 421 QUERY6_CLIENT_ID 422 LEASE6_ADDRESS 423 LEASE6_CLTT 424 LEASE6_HOSTNAME 425 LEASE6_HWADDR 426 LEASE6_HWADDR_TYPE 427 LEASE6_STATE 428 LEASE6_SUBNET_ID 429 LEASE6_VALID_LIFETIME 430 LEASE6_DUID 431 LEASE6_IAID 432 LEASE6_PREFERRED_LIFETIME 433 LEASE6_PREFIX_LEN 434 LEASE6_TYPE 435 PKT6_IA_IAID 436 PKT6_IA_IA_TYPE 437 PKT6_IA_IA_T1 438 PKT6_IA_IA_T2 439 440lease6_rebind 441 442:: 443 444 QUERY6_TYPE 445 QUERY6_TXID 446 QUERY6_LOCAL_ADDR 447 QUERY6_LOCAL_PORT 448 QUERY6_REMOTE_ADDR 449 QUERY6_REMOTE_PORT 450 QUERY6_IFACE_INDEX 451 QUERY6_IFACE_NAME 452 QUERY6_REMOTE_HWADDR 453 QUERY6_REMOTE_HWADDR_TYPE 454 QUERY6_PROTO 455 QUERY6_CLIENT_ID 456 LEASE6_ADDRESS 457 LEASE6_CLTT 458 LEASE6_HOSTNAME 459 LEASE6_HWADDR 460 LEASE6_HWADDR_TYPE 461 LEASE6_STATE 462 LEASE6_SUBNET_ID 463 LEASE6_VALID_LIFETIME 464 LEASE6_DUID 465 LEASE6_IAID 466 LEASE6_PREFERRED_LIFETIME 467 LEASE6_PREFIX_LEN 468 LEASE6_TYPE 469 PKT6_IA_IAID 470 PKT6_IA_IA_TYPE 471 PKT6_IA_IA_T1 472 PKT6_IA_IA_T2 473 474lease6_expire 475 476:: 477 478 LEASE6_ADDRESS 479 LEASE6_CLTT 480 LEASE6_HOSTNAME 481 LEASE6_HWADDR 482 LEASE6_HWADDR_TYPE 483 LEASE6_STATE 484 LEASE6_SUBNET_ID 485 LEASE6_VALID_LIFETIME 486 LEASE6_DUID 487 LEASE6_IAID 488 LEASE6_PREFERRED_LIFETIME 489 LEASE6_PREFIX_LEN 490 LEASE6_TYPE 491 REMOVE_LEASE 492 493lease6_recover 494 495:: 496 497 LEASE6_ADDRESS 498 LEASE6_CLTT 499 LEASE6_HOSTNAME 500 LEASE6_HWADDR 501 LEASE6_HWADDR_TYPE 502 LEASE6_STATE 503 LEASE6_SUBNET_ID 504 LEASE6_VALID_LIFETIME 505 LEASE6_DUID 506 LEASE6_IAID 507 LEASE6_PREFERRED_LIFETIME 508 LEASE6_PREFIX_LEN 509 LEASE6_TYPE 510 511leases6_committed 512 513:: 514 515 QUERY6_TYPE 516 QUERY6_TXID 517 QUERY6_LOCAL_ADDR 518 QUERY6_LOCAL_PORT 519 QUERY6_REMOTE_ADDR 520 QUERY6_REMOTE_PORT 521 QUERY6_IFACE_INDEX 522 QUERY6_IFACE_NAME 523 QUERY6_REMOTE_HWADDR 524 QUERY6_REMOTE_HWADDR_TYPE 525 QUERY6_PROTO 526 QUERY6_CLIENT_ID 527 LEASES6_SIZE 528 DELETED_LEASES6_SIZE 529 530If LEASES6_SIZE or DELETED_LEASES6_SIZE are non zero, then each lease 531will have its own unique identifier as shown below. First index starts 532at 0. 533 534:: 535 536 LEASES6_AT0_ADDRESS 537 LEASES6_AT0_CLTT 538 LEASES6_AT0_HOSTNAME 539 LEASES6_AT0_HWADDR 540 LEASES6_AT0_HWADDR_TYPE 541 LEASES6_AT0_STATE 542 LEASES6_AT0_SUBNET_ID 543 LEASES6_AT0_VALID_LIFETIME 544 LEASES6_AT0_DUID 545 LEASES6_AT0_IAID 546 LEASES6_AT0_PREFERRED_LIFETIME 547 LEASES6_AT0_PREFIX_LEN 548 LEASES6_AT0_TYPE 549 DELETED_LEASES6_AT0_ADDRESS 550 DELETED_LEASES6_AT0_CLTT 551 DELETED_LEASES6_AT0_HOSTNAME 552 DELETED_LEASES6_AT0_HWADDR 553 DELETED_LEASES6_AT0_HWADDR_TYPE 554 DELETED_LEASES6_AT0_STATE 555 DELETED_LEASES6_AT0_SUBNET_ID 556 DELETED_LEASES6_AT0_VALID_LIFETIME 557 DELETED_LEASES6_AT0_DUID 558 DELETED_LEASES6_AT0_IAID 559 DELETED_LEASES6_AT0_PREFERRED_LIFETIME 560 DELETED_LEASES6_AT0_PREFIX_LEN 561 DELETED_LEASES6_AT0_TYPE 562 563lease6_release 564 565:: 566 567 QUERY6_TYPE 568 QUERY6_TXID 569 QUERY6_LOCAL_ADDR 570 QUERY6_LOCAL_PORT 571 QUERY6_REMOTE_ADDR 572 QUERY6_REMOTE_PORT 573 QUERY6_IFACE_INDEX 574 QUERY6_IFACE_NAME 575 QUERY6_REMOTE_HWADDR 576 QUERY6_REMOTE_HWADDR_TYPE 577 QUERY6_PROTO 578 QUERY6_CLIENT_ID 579 LEASE6_ADDRESS 580 LEASE6_CLTT 581 LEASE6_HOSTNAME 582 LEASE6_HWADDR 583 LEASE6_HWADDR_TYPE 584 LEASE6_STATE 585 LEASE6_SUBNET_ID 586 LEASE6_VALID_LIFETIME 587 LEASE6_DUID 588 LEASE6_IAID 589 LEASE6_PREFERRED_LIFETIME 590 LEASE6_PREFIX_LEN 591 LEASE6_TYPE 592 593lease6_decline 594 595:: 596 597 QUERY6_TYPE 598 QUERY6_TXID 599 QUERY6_LOCAL_ADDR 600 QUERY6_LOCAL_PORT 601 QUERY6_REMOTE_ADDR 602 QUERY6_REMOTE_PORT 603 QUERY6_IFACE_INDEX 604 QUERY6_IFACE_NAME 605 QUERY6_REMOTE_HWADDR 606 QUERY6_REMOTE_HWADDR_TYPE 607 QUERY6_PROTO 608 QUERY6_CLIENT_ID 609 LEASE6_ADDRESS 610 LEASE6_CLTT 611 LEASE6_HOSTNAME 612 LEASE6_HWADDR 613 LEASE6_HWADDR_TYPE 614 LEASE6_STATE 615 LEASE6_SUBNET_ID 616 LEASE6_VALID_LIFETIME 617 LEASE6_DUID 618 LEASE6_IAID 619 LEASE6_PREFERRED_LIFETIME 620 LEASE6_PREFIX_LEN 621 LEASE6_TYPE 622