community.windows.win_domain_ou_module.rst

community.windows.win_domain_ou

Manage Active Directory Organizational Units

Version added: 1.8.0

• Synopsis
• Requirements
• Parameters
• Examples
• Return Values
• Status

Synopsis

• Manage Active Directory Organizational Units
• Adds, Removes and Modifies Active Directory Organizational Units
• Task should be delegated to a Windows Active Directory Domain Controller

Requirements

The below requirements are needed on the host that executes this module.

• This module requires Windows Server 2012 or Newer
• Powershell ActiveDirectory Module

Parameters

Parameter	Choices/Defaults	Comments
domain_password string		The password for the domain you are accessing
domain_server string		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.
domain_username string		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.
filter string	Default: "*"	filter for lookup of ou.
name string / required		The name of the Organizational Unit
path string		Specifies the X.500 path of the OU or container where the new object is created. defaults to adding ou at base of domain connected to.
properties dictionary		Free form dict of properties for the organizational unit. Follows LDAP property names, like StreetAddress or PostalCode.
protected boolean	Choices: no ← yes	Indicates whether to prevent the object from being deleted. When this protected=true, you cannot delete the corresponding object without changing the value of the property.
recursive boolean	Choices: no ← yes	Removes the OU and any child items it contains. You must specify this parameter to remove an OU that is not empty.
state string	Choices: present ← absent	Specifies the desired state of the OU. When state=present the module will attempt to create the specified OU if it does not already exist. When state=absent, the module will remove the specified OU. When state=absent and recursive=true, the module will remove all the OU and all child OU's.

Examples

---
- name: Ensure OU is present & protected
  community.windows.win_domain_ou:
    name: AnsibleFest
    state: present

- name: Ensure OU is present & protected
  community.windows.win_domain_ou:
    name: EUC Users
    path: "DC=euc,DC=vmware,DC=lan"
    state: present
    protected: true
  delegate_to: win-ad1.euc.vmware.lab

- name: Ensure OU is absent
  community.windows.win_domain_ou:
    name: EUC Users
    path: "DC=euc,DC=vmware,DC=lan"
    state: absent
  delegate_to: win-ad1.euc.vmware.lab

- name: Ensure OU is present with specific properties
  community.windows.win_domain_ou:
    name: WS1Users
    path: "CN=EUC Users,DC=euc,DC=vmware,DC=lan"
    protected: true
    properties:
      city: Sandy Springs
      state: Georgia
      StreetAddress: 1155 Perimeter Center West
      country: US
      description: EUC Business Unit
      PostalCode: 30189
  delegate_to: win-ad1.euc.vmware.lab

- name: Ensure OU updated with new properties
  community.windows.win_domain_ou:
    name: WS1Users
    path: DC=euc,DC=vmware,DC=lan
    protected: false
    properties:
      city: Atlanta
      state: Georgia
      managedBy: [email protected]
  delegate_to: win-ad1.euc.vmware.lab

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key	Returned	Description
ou dictionary	When state=present	New/Updated organizational unit parameters Sample: {'AddedProperties': [], 'City': 'Sandy Springs', 'Country': None, 'DistinguishedName': 'OU=VMW Atlanta,DC=ansible,DC=test', 'LinkedGroupPolicyObjects': [], 'ManagedBy': None, 'ModifiedProperties': [], 'Name': 'VMW Atlanta', 'ObjectClass': 'organizationalUnit', 'ObjectGUID': '3e987e30-93ad-4229-8cd0-cff6a91275e4', 'PostalCode': None, 'PropertyCount': 11, 'PropertyNames': 'City Country DistinguishedName LinkedGroupPolicyObjects ManagedBy Name ObjectClass ObjectGUID PostalCode State StreetAddress', 'RemovedProperties': [], 'State': 'Georgia', 'StreetAddress': '1155 Perimeter Center West'}
path string	always	Base ou path used by module either when provided path=DC=Ansible,DC=Test or derived by module. Sample: {'path': 'DC=ansible,DC=test'}

Status

Authors

• Joe Zollo (@joezollo)
• Larry Lane (@gamethis)