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.7.3).
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 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
|
|
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
|
|
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
|
|
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–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/ansible/windows/win_domain_controller_module.html