community.windows.win_domain_computer module – Manage computers in Active Directory
Note
This module is part of the community.windows collection (version 1.11.1).
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 community.windows
.
To use it in a playbook, specify: community.windows.win_domain_computer
.
Synopsis
Create, read, update and delete computers in Active Directory using a windows bridge computer to launch New-ADComputer, Get-ADComputer, Set-ADComputer, Remove-ADComputer and Move-ADObject powershell commands.
Parameters
Parameter |
Comments |
---|---|
Specifies a description of the object. This parameter sets the value of the Description property for the object. The LDAP display name (ldapDisplayName) for this property is description. Default: |
|
Specifies the fully qualified domain name (FQDN) of the computer. This parameter sets the DNSHostName property for a computer object. The LDAP display name for this property is dNSHostName. Required when state=present. |
|
The password for username. |
|
Specifies the Active Directory Domain Services instance to connect to. Can be in the form of an FQDN or NetBIOS name. If not specified then the value is based on the domain of the computer running PowerShell. |
|
The username to use when interacting with AD. If this is not set then the user Ansible used to log in with will be used instead when using CredSSP or Kerberos with credential delegation. |
|
Specifies if an account is enabled. An enabled account requires a password. This parameter sets the Enabled property for an account object. This parameter also sets the ADS_UF_ACCOUNTDISABLE flag of the Active Directory User Account Control (UAC) attribute. Choices:
|
|
The value to be assigned to the LDAP This value can be in the forms |
|
Specifies the name of the object. This parameter sets the Name property of the Active Directory object. The LDAP display name (ldapDisplayName) of this property is name. |
|
The path to the file where the BLOB will be saved. If omitted, a temporary file will be used. If offline_domain_join=output the file will be deleted after its contents are returned. The parent directory for the BLOB file must exist; intermediate directories will not be created. |
|
Provisions a computer in the directory and provides a BLOB file that can be used on the target computer/image to join it to the domain while offline. The
If the computer already exists, no BLOB will be created/returned, and the module will operate as it would have without offline domain join. Choices:
|
|
Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created. Required when state=present. Special characters must be escaped, see Distinguished Names for details. |
|
Specifies the Security Account Manager (SAM) account name of the computer. It maximum is 256 characters, 15 is advised for older operating systems compatibility. The LDAP display name (ldapDisplayName) for this property is sAMAccountName. If ommitted the value is the same as Note that all computer SAMAccountNames need to end with a If |
|
Specified whether the computer should be Choices:
|
Notes
Note
For more information on Offline Domain Join see the step-by-step guide.
When using the ODJ BLOB to join a computer to the domain, it must be written out to a file.
The file must be UTF-16 encoded (in PowerShell this encoding is called
Unicode
), and it must end in a null character. See examples.The
djoin.exe
part of the offline domain join process will not use domain_server, domain_username, or domain_password.
See Also
See also
- ansible.windows.win_domain
Ensures the existence of a Windows domain.
- ansible.windows.win_domain_controller
Manage domain controller/member server state for a Windows host.
- community.windows.win_domain_group
Creates, modifies or removes domain groups.
- ansible.windows.win_domain_membership
Manage domain/workgroup membership for a Windows host.
- community.windows.win_domain_user
Manages Windows Active Directory user accounts.
Examples
- name: Add linux computer to Active Directory OU using a windows machine
community.windows.win_domain_computer:
name: one_linux_server
sam_account_name: linux_server$
dns_hostname: one_linux_server.my_org.local
ou: "OU=servers,DC=my_org,DC=local"
description: Example of linux server
enabled: yes
state: present
delegate_to: my_windows_bridge.my_org.local
- name: Remove linux computer from Active Directory using a windows machine
community.windows.win_domain_computer:
name: one_linux_server
state: absent
delegate_to: my_windows_bridge.my_org.local
- name: Provision a computer for offline domain join
community.windows.win_domain_computer:
name: newhost
dns_hostname: newhost.ansible.local
ou: 'OU=A great\, big organizational unit name,DC=ansible,DC=local'
state: present
offline_domain_join: yes
odj_return_blob: yes
register: computer_status
delegate_to: windc.ansible.local
- name: Join a workgroup computer to the domain
vars:
target_blob_file: 'C:\ODJ\blob.txt'
ansible.windows.win_shell: |
$blob = [Convert]::FromBase64String('{{ computer_status.odj_blob }}')
[IO.File]::WriteAllBytes('{{ target_blob_file }}', $blob)
& djoin.exe --% /RequestODJ /LoadFile '{{ target_blob_file }}' /LocalOS /WindowsPath "%SystemRoot%"
- name: Restart to complete domain join
ansible.windows.win_restart:
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
Information about the invocation of djoin.exe. Returned: when offline_domain_join is True and the computer didn’t exist |
|
The full command line used to call djoin.exe Returned: always Sample: |
|
The return code from djoin.exe Returned: when not check mode Sample: |
|
The stderr from djoin.exe Returned: when not check mode Sample: |
|
The stdout from djoin.exe Returned: when not check mode Sample: |
|
The offline domain join BLOB. This is an empty string when in check mode or when offline_domain_join is ‘path’. This field contains the base64 encoded raw bytes of the offline domain join BLOB file. Returned: when offline_domain_join is not ‘none’ and the computer didn’t exist Sample: |
|
The path to the offline domain join BLOB file on the target host. If odj_blob_path was specified, this will match that path. Returned: when offline_domain_join is ‘path’ and the computer didn’t exist Sample: |