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

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 win_reboot action if changes are made.

Parameters

Parameter Choices/Defaults Comments
database_path
path
added in 2.5
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.
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 in Ansible 2.14.
This does not relate to the -LogPath paramter of the install controller cmdlet.
read_only
boolean
added in 2.5
    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
added in 2.5
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
    Choices:
  • domain_controller
  • member_server
Whether the target host should be a domain controller or a member server.
sysvol_path
path
added in 2.5
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

win_domain – Ensures the existence of a Windows domain
The official documentation on the win_domain module.
win_domain_computer – Manage computers in Active Directory
The official documentation on the win_domain_computer module.
win_domain_group – Creates, modifies or removes domain groups
The official documentation on the win_domain_group module.
win_domain_membership – Manage domain/workgroup membership for a Windows host
The official documentation on the win_domain_membership module.
win_domain_user – Manages Windows Active Directory user accounts
The official documentation on the win_domain_user module.

Examples

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

# ensure a server is not a 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)
- 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
  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
  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
  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


Status

Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

Authors

  • Matt Davis (@nitzmahone)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.