win_domain_group – Creates, modifies or removes domain groups
New in version 2.4.
Synopsis
- Creates, modifies or removes groups in Active Directory.
- For local groups, use the win_group module instead.
Parameters
Parameter | Choices/Defaults | Comments |
---|---|---|
attributes
dictionary
|
A dict of custom LDAP attributes to set on the group.
This can be used to set custom attributes that are not exposed as module parameters, e.g.
mail .
See the examples on how to format this parameter.
|
|
category
string
|
|
The category of the group, this is the value to assign to the LDAP
groupType attribute.
If a new group is created then
security will be used by default.
|
description
string
|
The value to be assigned to the LDAP
description attribute.
|
|
display_name
string
|
The value to assign to the LDAP
displayName attribute.
|
|
domain_password
string
|
The password for
username .
|
|
domain_server
string
added in 2.5
|
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.
|
|
ignore_protection
boolean
|
|
Will ignore the
ProtectedFromAccidentalDeletion flag when deleting or moving a group.
The module will fail if one of these actions need to occur and this value is set to
no .
|
managed_by
string
|
The value to be assigned to the LDAP
managedBy attribute.
This value can be in the forms
Distinguished Name ,
objectGUID ,
objectSid or
sAMAccountName , see examples for more details.
|
|
name
string /
required
|
The name of the group to create, modify or remove.
This value can be in the forms
Distinguished Name ,
objectGUID ,
objectSid or
sAMAccountName , see examples for more details.
|
|
organizational_unit
string
|
The full LDAP path to create or move the group to.
This should be the path to the parent object to create or move the group to.
See examples for details of how this path is formed.
aliases: ou, path |
|
protect
boolean
|
|
Will set the
ProtectedFromAccidentalDeletion flag based on this value.
This flag stops a user from deleting or moving a group to a different path.
|
scope
string
|
|
The scope of the group.
If
state=present and the group doesn't exist then this must be set.
|
state
string
|
|
If
state=present this module will ensure the group is created and is configured accordingly.
If
state=absent this module will delete the group if it exists
|
Notes
Note
- This must be run on a host that has the ActiveDirectory powershell module installed.
See Also
See also
- win_domain – Ensures the existence of a Windows domain
- The official documentation on the win_domain module.
- win_domain_controller – Manage domain controller/member server state for a Windows host
- The official documentation on the win_domain_controller module.
- win_domain_computer – Manage computers in Active Directory
- The official documentation on the win_domain_computer module.
- win_domain_membership – Manage domain/workgroup membership for a Windows host
- The official documentation on the win_domain_membership module.
- win_domain_user – Manages Windows Active Directory user accounts
- The official documentation on the win_domain_user module.
- win_group – Add and remove local groups
- The official documentation on the win_group module.
- win_group_membership – Manage Windows local group membership
- The official documentation on the win_group_membership module.
Examples
- name: Ensure the group Cow exists using sAMAccountName win_domain_group: name: Cow scope: global path: OU=groups,DC=ansible,DC=local - name: Ensure the group Cow doesn't exist using the Distinguished Name win_domain_group: name: CN=Cow,OU=groups,DC=ansible,DC=local state: absent - name: Delete group ignoring the protection flag win_domain_group: name: Cow state: absent ignore_protection: yes - name: Create group with delete protection enabled and custom attributes win_domain_group: name: Ansible Users scope: domainlocal category: security attributes: mail: [email protected] wWWHomePage: www.ansible.com ignore_protection: yes - name: Change the OU of a group using the SID and ignore the protection flag win_domain_group: name: S-1-5-21-2171456218-3732823212-122182344-1189 scope: global organizational_unit: OU=groups,DC=ansible,DC=local ignore_protection: yes - name: Add managed_by user win_domain_group: name: Group Name Here managed_by: Domain Admins - name: Add group and specify the AD domain services to use for the create win_domain_group: name: Test Group domain_username: [email protected] domain_password: Password01! domain_server: corp-DC12.corp.ansible.com scope: domainlocal
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key | Returned | Description |
---|---|---|
attributes
dictionary
|
group exists and attributes are set on the module invocation |
Custom attributes that were set by the module. This does not show all the custom attributes rather just the ones that were set by the module.
Sample:
{'mail': '[email protected]', 'wWWHomePage': 'www.ansible.com'}
|
canonical_name
string
|
group exists |
The canonical name of the group.
Sample:
ansible.local/groups/Cow
|
category
string
|
group exists |
The Group type value of the group, i.e. Security or Distribution.
Sample:
Security
|
created
boolean
|
always |
Whether a group was created
Sample:
True
|
description
string
|
group exists |
The Description of the group.
Sample:
Group Description
|
display_name
string
|
group exists |
The Display name of the group.
Sample:
Users who connect through RDP
|
distinguished_name
string
|
group exists |
The full Distinguished Name of the group.
Sample:
CN=Cow,OU=groups,DC=ansible,DC=local
|
group_scope
string
|
group exists |
The Group scope value of the group.
Sample:
Universal
|
guid
string
|
group exists |
The guid of the group.
Sample:
512a9adb-3fc0-4a26-9df0-e6ea1740cf45
|
managed_by
string
|
group exists |
The full Distinguished Name of the AD object that is set on the managedBy attribute.
Sample:
CN=Domain Admins,CN=Users,DC=ansible,DC=local
|
name
string
|
group exists |
The name of the group.
Sample:
Cow
|
protected_from_accidental_deletion
boolean
|
group exists |
Whether the group is protected from accidental deletion.
Sample:
True
|
sid
string
|
group exists |
The Security ID of the group.
Sample:
S-1-5-21-2171456218-3732823212-122182344-1189
|
Status
- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Community. [community]
Authors
- Jordan Borean (@jborean93)
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.9/modules/win_domain_group_module.html