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

New in version 2.3.

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
(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
When state is domain_controller, the DNS name of the domain for which the targeted Windows host should be a DC.
domain_admin_password
required
Password for the specified domain_admin_user.
domain_admin_user
required
Username of a domain admin for the target domain (necessary to promote or demote a domain controller).
local_admin_password
Password to be assigned to the local Administrator user (required when state is member_server).
read_only
bool

(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
Safe mode password for the domain controller (required when state is domain_controller).
site_name
(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
    Choices:
  • domain_controller
  • member_server
Whether the target host should be a domain controller or a member server.
sysvol_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.

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
    log_path: C:\ansible_win_domain_controller.txt

# 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
    log_path: C:\ansible_win_domain_controller.txt

- 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

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

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as core which means that it is maintained by the Ansible Core Team. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Core Team, see here.

Support

For more information about Red Hat’s support of this module, please refer to this Knowledge Base article

Author

  • Matt Davis (@nitzmahone)

Hint

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

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