community.general.kea_command module – Submits generic command to ISC KEA server on target

Note

This module is part of the community.general collection (version 12.0.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.kea_command.

New in community.general 12.0.0

Synopsis

  • Submits a command to the JSON API of an ISC KEA server running on the target and obtains the result.

  • This module supports sending arbitrary commands and returns the server response unchecked; while it would be possible to write individual modules for specific KEA service commands, that approach would not scale, as the FOSS hooks alone provide dozens of commands.

  • Between sending the command and parsing the result status, changed will register as true if an error occurs, to err on the safe side.

Parameters

Parameter

Comments

arguments

dictionary

The arguments sent along with the command, if any.

Use {} to send an empty arguments dict/object instead of omitting it.

command

string / required

The name of the command to send, for example status-get.

rv_changed

list / elements=integer

A list of result codes to indicate success and changed system state.

Omit this for most acquisition commands.

Set it to [0] for command=lease4-del and similar which return changed system state that way.

Any result codes not listed in either rv_unchanged or rv_changed are interpreted as indicating an error result.

rv_unchanged has precedence over rv_changed if a result code is in both lists.

Default: []

rv_unchanged

list / elements=integer

A list of result codes to indicate success but unchanged system state.

Set this to [0] for most acquisition commands.

Use [3] for command=lease4-del and similar which have a separate code for this.

Any result codes not listed in either rv_unchanged or rv_changed are interpreted as indicating an error result.

rv_unchanged has precedence over rv_changed if a result code is in both lists.

Default: []

socket

path

The full pathname of the Unix Domain Socket to connect to.

The default value is suitable for kea-dhcp4-server on Debian trixie.

This module directly interfacees via UDS; the HTTP wrappers are not supported.

Default: "/run/kea/kea4-ctrl-socket"

Attributes

Attribute

Support

Description

check_mode

Support: none

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

platform

Platform: posix

Target OS/families that can be operated against.

Examples

vars:
  ipaddr: "192.168.123.45"
  hwaddr: "00:00:5E:00:53:00"
tasks:

  # an example for a request acquiring information
  - name: Get KEA DHCP6 status
    kea_command:
      command: status-get
      rv_unchanged: [0]
      socket: /run/kea/kea6-ctrl-socket
    register: kea6_status
  - name: Display registered status result
    ansible.builtin.debug:
      msg: KEA DHCP6 running on PID {{ kea6_status.response.arguments.pid }}

  # an example for requests modifying state
  - name: Remove existing leases for {{ ipaddr }}, if any
    kea_command:
      command: lease4-del
      arguments:
        ip-address: "{{ ipaddr }}"
      rv_changed: [0]
      rv_unchanged: [3]
  - name: Add DHCP lease for {{ ipaddr }}
    kea_command:
      command: lease4-add
      arguments:
        ip-address: "{{ ipaddr }}"
        hw-address: "{{ hwaddr }}"
      rv_changed: [0]

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

response

dictionary

The server JSON response.

Returned: when available

Authors

  • Thorsten Glaser (@mirabilos)