ansible.windows.win_domain_controller – Manage domain controller/member server state for a Windows host

Note

This plugin is part of the ansible.windows collection (version 1.3.0).

To install it use: ansible-galaxy collection install ansible.windows.

To use it in a playbook, specify: ansible.windows.win_domain_controller.

Synopsis

  • Ensure that a Windows Server 2012+ host is configured as a domain controller or demoted to member server.
  • This module may require subsequent use of the ansible.windows.win_reboot action if changes are made.

Parameters

Parameter Choices/Defaults Comments
database_path
path
The path to a directory on a fixed disk of the Windows host where the domain database will be created..
If not set then the default path is %SYSTEMROOT%\NTDS.
dns_domain_name
string
When state is domain_controller, the DNS name of the domain for which the targeted Windows host should be a DC.
domain_admin_password
string / required
Password for the specified domain_admin_user.
domain_admin_user
string / required
Username of a domain admin for the target domain (necessary to promote or demote a domain controller).
domain_log_path
path
Specified the fully qualified, non-UNC path to a directory on a fixed disk of the local computer that will contain the domain log files.
install_dns
boolean
    Choices:
  • no
  • yes
Whether to install the DNS service when creating the domain controller.
If not specified then the -InstallDns option is not supplied to Install-ADDSDomainController command, see https://docs.microsoft.com/en-us/powershell/module/addsdeployment/install-addsdomaincontroller.
install_media_path
path
The path to a directory on a fixed disk of the Windows host where the Install From Media IFC data will be used.
See the Install using IFM guide for more information.
local_admin_password
string
Password to be assigned to the local Administrator user (required when state is member_server).
log_path
string
The path to log any debug information when running the module.
This option is deprecated and should not be used, it will be removed on the major release after 2022-07-01.
This does not relate to the -LogPath paramter of the install controller cmdlet.
read_only
boolean
    Choices:
  • no ←
  • yes
Whether to install the domain controller as a read only replica for an existing domain.
safe_mode_password
string
Safe mode password for the domain controller (required when state is domain_controller).
site_name
string
Specifies the name of an existing site where you can place the new domain controller.
This option is required when read_only is yes.
state
string / required
    Choices:
  • domain_controller
  • member_server
Whether the target host should be a domain controller or a member server.
sysvol_path
path
The path to a directory on a fixed disk of the Windows host where the Sysvol folder will be created.
If not set then the default path is %SYSTEMROOT%\SYSVOL.

See Also

See also

ansible.windows.win_domain

The official documentation on the ansible.windows.win_domain module.

ansible.windows.win_domain_computer

The official documentation on the ansible.windows.win_domain_computer module.

community.windows.win_domain_group

The official documentation on the community.windows.win_domain_group module.

ansible.windows.win_domain_membership

The official documentation on the ansible.windows.win_domain_membership module.

community.windows.win_domain_user

The official documentation on the community.windows.win_domain_user module.

Examples

- name: Ensure a server is a domain controller
  ansible.windows.win_domain_controller:
    dns_domain_name: ansible.vagrant
    domain_admin_user: [email protected]
    domain_admin_password: password123!
    safe_mode_password: password123!
    state: domain_controller

# note that without an action wrapper, in the case where a DC is demoted,
# the task will fail with a 401 Unauthorized, because the domain credential
# becomes invalid to fetch the final output over WinRM. This requires win_async
# with credential switching (or other clever credential-switching
# mechanism to get the output and trigger the required reboot)
- name: Ensure a server is not a domain controller
  ansible.windows.win_domain_controller:
    domain_admin_user: [email protected]
    domain_admin_password: password123!
    local_admin_password: password123!
    state: member_server

- name: Promote server as a read only domain controller
  ansible.windows.win_domain_controller:
    dns_domain_name: ansible.vagrant
    domain_admin_user: [email protected]
    domain_admin_password: password123!
    safe_mode_password: password123!
    state: domain_controller
    read_only: yes
    site_name: London

- name: Promote server with custom paths
  ansible.windows.win_domain_controller:
    dns_domain_name: ansible.vagrant
    domain_admin_user: [email protected]
    domain_admin_password: password123!
    safe_mode_password: password123!
    state: domain_controller
    sysvol_path: D:\SYSVOL
    database_path: D:\NTDS
    domain_log_path: D:\NTDS
  register: dc_promotion

- name: Reboot after promotion
  ansible.windows.win_reboot:
  when: dc_promotion.reboot_required

Return Values

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

Key Returned Description
reboot_required
boolean
always
True if changes were made that require a reboot.

Sample:
True


Authors

  • Matt Davis (@nitzmahone)

© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.10/collections/ansible/windows/win_domain_controller_module.html