community.windows.win_dhcp_lease module – Manage Windows Server DHCP Leases
Note
This module is part of the community.windows collection (version 2.3.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.windows.
You need further requirements to be able to use this module,
see Requirements for details.
To use it in a playbook, specify: community.windows.win_dhcp_lease.
Synopsis
Manage Windows Server DHCP Leases (IPv4 Only)
Adds, Removes and Modifies DHCP Leases and Reservations
Task should be delegated to a Windows DHCP Server
Requirements
The below requirements are needed on the host that executes this module.
This module requires Windows Server 2012 or Newer
Parameters
Parameter |
Comments |
|---|---|
Specifies the description for reservation being created. Only applicable to l(type=reservation). |
|
Specifies the DNS hostname of the client for which the IP address lease is to be added. |
|
Indicates the type of DNS record to be registered by the DHCP. server service for this lease. l(a) results in an A record being registered. l(aptr) results in both A and PTR records to be registered. l(noreg) results in no DNS records being registered. Choices:
|
|
Specifies the duration of the DHCP lease in days. The duration value only applies to l(type=lease). Defaults to the duration specified by the DHCP server configuration. Only applicable to l(type=lease). |
|
The IPv4 address of the client server/computer. This is a required parameter, if l(mac) is not set. Can be used to identify an existing lease/reservation, instead of l(mac). |
|
Specifies the client identifier to be set on the IPv4 address. This is a required parameter, if l(ip) is not set. Windows clients use the MAC address as the client ID. Linux and other operating systems can use other types of identifiers. Can be used to identify an existing lease/reservation, instead of l(ip). |
|
Specifies the name of the reservation being created. Only applicable to l(type=reservation). |
|
Specifies the scope identifier as defined by the DHCP server. This is a required parameter, if l(state=present) and the reservation or lease doesn’t already exist. Not required if updating an existing lease or reservation. |
|
Specifies the desired state of the DHCP lease or reservation. Choices:
|
|
The type of DHCP address. Leases expire as defined by l(duration). When l(duration) is not specified, the server default is used. Reservations are permanent. Choices:
|
Examples
- name: Ensure DHCP reservation exists
community.windows.win_dhcp_lease:
type: reservation
ip: 192.168.100.205
scope_id: 192.168.100.0
mac: 00:B1:8A:D1:5A:1F
dns_hostname: "{{ ansible_inventory }}"
description: Testing Server
- name: Ensure DHCP lease or reservation does not exist
community.windows.win_dhcp_lease:
mac: 00:B1:8A:D1:5A:1F
state: absent
- name: Ensure DHCP lease or reservation does not exist
community.windows.win_dhcp_lease:
ip: 192.168.100.205
state: absent
- name: Convert DHCP lease to reservation & update description
community.windows.win_dhcp_lease:
type: reservation
ip: 192.168.100.205
description: Testing Server
- name: Convert DHCP reservation to lease
community.windows.win_dhcp_lease:
type: lease
ip: 192.168.100.205
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
|---|---|
New/Updated DHCP object parameters Returned: When l(state=present) Sample: |