microsoft.ad.site module – Manage Active Directory replication sites

Note

This module is part of the microsoft.ad collection (version 1.11.0).

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 microsoft.ad. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: microsoft.ad.site.

New in microsoft.ad 1.11.0

Synopsis

• Create, modify, or remove Active Directory replication sites.

• Sites are used to control replication traffic and help clients discover nearby network resources such as domain controllers.

Requirements

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

• ActiveDirectory PowerShell module

• When targeting PowerShell 7, Windows Server 2022/Windows 10 build 1903 or later is required.

Parameters

Parameter	Comments
attributes dictionary	The attributes to either add, remove, or set on the AD object. The value of each attribute option should be a dictionary where the key is the LDAP attribute, e.g. firstName, comment and the value is the value, or list of values, to set for that attribute. The attribute value(s) can either be the raw string, integer, or bool value to add, remove, or set on the attribute in question. The value can also be a dictionary with the type key set to bytes, date_time, security_descriptor, or raw and the value for this entry under the value key. The bytes type has a value that is a base64 encoded string of the raw bytes to set. The date_time type has a value that is the ISO 8601 DateTime string of the DateTime to set. The DateTime will be set as the Microsoft FILETIME integer value which is the number of 100 nanoseconds since 1601-01-01 in UTC. The security_descriptor type has a value that is the Security Descriptor SDDL string used for the nTSecurityDescriptor attribute. The raw type is the int, string, or boolean value to set. String attribute values are compared using a case sensitive match on the AD object being managed. See LDAP attributes help for more information. Default: {}
add dictionary	A dictionary of all the attributes and their value(s) to add to the AD object being managed if they are not already present. This is used for attributes that can contain multiple values, if the attribute only allows a single value, use set instead. Default: {}
remove dictionary	A dictionary of all the attributes and their value(s) to remove from the AD object being managed if they are present. This is used for attributes that can contain multiple values, if the attribute only allows a single value, use set instead. Default: {}
set dictionary	A dictionary of all attributes and their value(s) to set on the AD object being managed. This will replace any existing values if they do not match the ones being requested. The order of attribute values are not checked only, only that the values requested are the only values on the object attribute. Set this to null or an empty list to clear any values for the attribute. Default: {}
automatic_inter_site_topology_generation_enabled boolean	Whether the KCC inter-site topology generator (ISTG) creates connections for inter-site replication automatically. Set to false to manage inter-site connections manually while retaining automatic intra-site connections. Choices: false true
automatic_topology_generation_enabled boolean	Whether the KCC generates intra-site replication connections automatically. Set to false to manage intra-site connections manually. Choices: false true
description string	The description of the AD object to set. This is the value set on the description LDAP attribute.
display_name string	The display name of the AD object to set. This is the value of the displayName LDAP attribute.
domain_credentials list / elements=dictionary	Specifies the credentials that should be used when using the server specified by name. To specify credentials for the default domain server, use an entry without the name key or use the domain_username and domain_password option. This can be set under the play’s module defaults under the group/microsoft.ad.domain group. See AD authentication in modules for more information. Default: []
name string	The name of the server these credentials are for. This value should correspond to the value used in other options that specify a custom server to use, for example an option that references an AD identity located on a different AD server. This key can be omitted in one entry to specify the default credentials to use when a server is not specified instead of using domain_username and domain_password.
password string / required	The password to use when connecting to the server specified by name.
username string / required	The username to use when connecting to the server specified by name.
domain_password string	The password for domain_username. The domain_credentials sub entry without a name key can also be used to specify the credentials for the default domain authentication. This can be set under the play’s module defaults under the group/microsoft.ad.domain group.
domain_server string	Specified 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 default domain of the computer running PowerShell. Custom credentials can be specified under a domain_credentials entry without a name key or through domain_username and domain_password. This can be set under the play’s module defaults under the group/microsoft.ad.domain group.
domain_username string	The username to use when interacting with AD. If this is not set then the user that is used for authentication will be the connection user. Ansible will be unable to use the connection user unless auth is Kerberos with credential delegation or CredSSP, or become is used on the task. The domain_credentials sub entry without a name key can also be used to specify the credentials for the default domain authentication. This can be set under the play’s module defaults under the group/microsoft.ad.domain group.
identity string	The identity of the AD object used to find the AD object to manage. This must be specified if; name is not set, when trying to rename the object with a new name, or when trying to move the object into a different path. The identity can be in the form of a GUID representing the objectGUID value, the userPrincipalName, sAMAccountName, objectSid, or distinguishedName. If omitted, the AD object to manage is selected by the distinguishedName using the format CN={{ name }},{{ path }}. If path is not defined, the defaultNamingContext is used instead. When using the microsoft.ad.computer module, the identity will automatically append $ to the end of the sAMAccountName if the provided value did not result in a match and did not already have a $ at the end.
managed_by any	The user or group that manages the object. The value can be in the form of a distinguishedName, objectGUID, objectSid, sAMAccountName, or userPrincipalName string or a dictionary with the name and optional server key. This is the value set on the managedBy LDAP attribute. See DN Lookup Attributes for more information on how DN lookups work.
name string	The name of the AD object to manage, this is not the sAMAccountName of the object but the LDAP cn or name entry of the object in the path specified. Use identity to select an object to manage by its sAMAccountName. If identity is specified, and the name of the object found by that identity does not match this value, the object will be renamed. This must be specified if identity is not set.
path string	The path of the OU or the container where the new object should exist in. If creating a new object, the new object will be created at the path specified. If no path is specified then the defaultNamingContext of the domain will be used as the path for most object types. If managing an existing object found by identity, the path of the found object will be moved to the one specified by this option. If no path is specified, the object will not be moved. The modules microsoft.ad.computer, microsoft.ad.user, and microsoft.ad.group have their own default path that is configured on the Active Directory domain controller. This can be set to the literal value microsoft.ad.default_path which will equal the default value used when creating a new object.
protect_from_deletion boolean	Marks the object as protected from accidental deletion. This applies a deny access right from deleting the object normally and the protection needs to be removed before the object can be deleted through the GUI or any other tool outside Ansible. Using state=absent will still delete the AD object even if it is marked as protected from deletion. Choices: false true
state string	Set to present to ensure the AD object exists. Set to absent to remove the AD object if it exists. The option name must be set when state=present. Using absent will recursively remove the AD object and any child objects if it’s a container. It will also remove the AD object even if the object is marked as protected from accidental deletion. Choices: "absent" "present" ← (default)
universal_group_caching_enabled boolean	Whether Universal Group Membership Caching (UGMC) is enabled for the site. Useful in branch-office sites without a Global Catalog server to reduce authentication latency. Choices: false true

Attributes

Attribute	Support	Description
check_mode	Support: full	Can run in check_mode and return changed status prediction without modifying target, if not supported the action will be skipped.
diff_mode	Support: full	Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode
platform	Platform: windows	Target OS/families that can be operated against

Notes

Note

• The path option for sites defaults to the CN=Sites,CN=Configuration,... container. Sites cannot be moved to a different container.

• This module must be run on a Windows target host with the ActiveDirectory module installed.

• Some LDAP attributes can have only a single value set while others can have multiple. Some attributes are also read only and cannot be changed. It is recommended to look at the schema metadata for an attribute where System-Only are read only values and Is-Single-Value are attributes with only 1 value.

• Attempting to set multiple values to a Is-Single-Value attribute results in undefined behaviour.

• If running on a server that is not a Domain Controller, credential delegation through CredSSP or Kerberos with delegation must be used or the domain_username, domain_password must be set.

See Also

See also

microsoft.ad.object_info

Gather information an Active Directory object.

Examples

- name: Create a replication site for the London branch office
  microsoft.ad.site:
    name: London-Branch
    description: London branch office site
    state: present

- name: Create a site with deletion protection
  microsoft.ad.site:
    name: NYC-HQ
    description: New York City headquarters
    protect_from_deletion: true
    state: present

- name: Enable Universal Group Caching on a branch site
  microsoft.ad.site:
    name: London-Branch
    universal_group_caching_enabled: true
    state: present

- name: Disable automatic inter-site topology generation
  microsoft.ad.site:
    name: London-Branch
    automatic_inter_site_topology_generation_enabled: false
    state: present

- name: Set managedBy using an identity from another DC
  microsoft.ad.site:
    name: London-Branch
    managed_by:
      name: manager-user
      server: OtherDC

- name: Remove a replication site
  microsoft.ad.site:
    name: London-Branch
    state: absent

Return Values

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

Key	Description
distinguished_name string	The distinguishedName of the AD object that was created, removed, or edited. Returned: always Sample: "CN=London-Branch,CN=Sites,CN=Configuration,DC=contoso,DC=com"
object_guid string	The objectGUID of the AD object that was created, removed, or edited. If a new object was created in check mode, a GUID of 0s will be returned. Returned: always Sample: "d84a141f-2b99-4f08-9da0-ed2d26864ba1"

Authors

• Ron Gershburg (@rgershbu)

Collection links

• Issue Tracker
• Repository (Sources)
• Report an issue
• Communication