ansible.windows.win_domain – Ensures the existence of a Windows domain

Note

This plugin is part of the ansible.windows collection.

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

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

Synopsis

  • Ensure that the domain named by dns_domain_name exists and is reachable.

  • If the domain is not reachable, the domain is created in a new forest on the target Windows Server 2012R2+ host.

  • This module may require subsequent use of the ansible.windows.win_reboot action if changes are made.

Parameters

Parameter Choices/Defaults Comments
create_dns_delegation
boolean
    Choices:
  • no
  • yes
Whether to create a DNS delegation that references the new DNS server that you install along with the domain controller.
Valid for Active Directory-integrated DNS only.
The default is computed automatically based on the environment.
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 / required
The DNS name of the domain which should exist and be reachable or reside on the target Windows host.
domain_mode
string
    Choices:
  • Win2003
  • Win2008
  • Win2008R2
  • Win2012
  • Win2012R2
  • WinThreshold
Specifies the domain functional level of the first domain in the creation of a new forest.
The domain functional level cannot be lower than the forest functional level, but it can be higher.
The default is automatically computed and set.
domain_netbios_name
string
The NetBIOS name for the root domain in the new forest.
For NetBIOS names to be valid for use with this parameter they must be single label names of 15 characters or less, if not it will fail.
If this parameter is not set, then the default is automatically computed from the value of the domain_name parameter.
forest_mode
string
    Choices:
  • Win2003
  • Win2008
  • Win2008R2
  • Win2012
  • Win2012R2
  • WinThreshold
Specifies the forest functional level for the new forest.
The default forest functional level in Windows Server is typically the same as the version you are running.
install_dns
boolean
    Choices:
  • no
  • yes ←
Whether to install the DNS service when creating the domain controller.
log_path
path
Specifies the fully qualified, non-UNC path to a directory on a fixed disk of the local computer where the log file for this operation is written.
If not set then the default path is %SYSTEMROOT%\NTDS.
safe_mode_password
string / required
Safe mode password for the domain controller.
sysvol_path
path
The path to a directory on a fixed disk of the Windows host where the Sysvol file will be created.
If not set then the default path is %SYSTEMROOT%\SYSVOL.

See Also

See also

ansible.windows.win_domain_controller

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

community.windows.win_domain_computer

The official documentation on the community.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: Create new domain in a new forest on the target host
  ansible.windows.win_domain:
    dns_domain_name: ansible.vagrant
    safe_mode_password: password123!

- name: Create new Windows domain in a new forest with specific parameters
  ansible.windows.win_domain:
    create_dns_delegation: no
    database_path: C:\Windows\NTDS
    dns_domain_name: ansible.vagrant
    domain_mode: Win2012R2
    domain_netbios_name: ANSIBLE
    forest_mode: Win2012R2
    safe_mode_password: password123!
    sysvol_path: C:\Windows\SYSVOL
  register: domain_install

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)