xactivedirectory
Version information
This version is compatible with:
- Puppet Enterprise 2023.2.x, 2023.1.x, 2023.0.x, 2021.7.x, 2021.6.x, 2021.5.x, 2021.4.x, 2021.3.x, 2021.2.x, 2021.1.x, 2021.0.x, 2019.8.x, 2019.7.x, 2019.5.x, 2019.4.x, 2019.3.x, 2019.2.x, 2019.1.x, 2019.0.x
- Puppet >= 6.0.0 < 8.0.0
Start using this module
Add this module to your Puppetfile:
mod 'dsc-xactivedirectory', '2.13.0-0-1'
Learn more about managing modules with a PuppetfileDocumentation
Table of Contents
Description
This is an auto-generated module, using the Puppet DSC Builder to vendor and expose the PowerShell module's DSC resources as Puppet resources. The functionality of this module comes entirely from the vendored PowerShell resources, which are pinned at v2.13.0.0. The PowerShell module describes itself like this:
_The xActiveDirectory module is originally part of the Windows PowerShell Desired State Configuration (DSC) Resource Kit. This version has been modified for use in Azure. This module contains the xADDomain, xADDomainController, xADUser, and xWaitForDomain resources. These DSC Resources allow you to configure and manage Active Directory.
All of the resources in the DSC Resource Kit are provided AS IS, and are not supported through any Microsoft standard support program or service._
For information on troubleshooting to determine whether any encountered problems are with the Puppet wrapper or the DSC resource, see the troubleshooting section below.
Requirements
This module, like all auto-generated Puppetized DSC modules, relies on two important technologies in the Puppet stack: the Puppet Resource API and the puppetlabs/pwshlib Puppet module.
The Resource API provides a simplified option for writing types and providers and is responsible for how this module is structured. The Resource API ships inside of Puppet starting with version 6. While it is technically possible to add the Resource API functionality to Puppet 5.5.x, the DSC functionality has not been tested in this setup. For more information on the Resource API, review the documentation.
The module also depends on the pwshlib module. This Puppet module includes two important things: the ruby-pwsh library for running PowerShell code from ruby and the base provider for DSC resources, which this module leverages.
All of the actual work being done to call the DSC resources vendored with this module is in this file from the pwshlib module. This is important for troubleshooting and bug reporting, but doesn't impact your use of the module except that the end result will be that nothing works, as the dependency is not installed alongside this module!
Usage
You can specify any of the DSC resources from this module like a normal Puppet resource in your manifests. The examples below use DSC resources from from the PowerShellGet repository, regardless of what module you're looking at here; the syntax, not the specifics, is what's important.
For reference documentation about the DSC resources exposed in this module, see the Reference Forge tab, or the REFERENCE.md file.
# Include a meaningful title for your resource declaration
dsc_psrepository { 'Add team module repo':
dsc_name => 'foo',
dsc_ensure => present,
# This location is nonsense, can be any valid folder on your
# machine or in a share, any location the SourceLocation param
# for the DSC resource will accept.
dsc_sourcelocation => 'C:\Program Files',
# You must always pass an enum fully lower-cased;
# Puppet is case sensitive even when PowerShell isn't
dsc_installationpolicy => untrusted,
}
dsc_psrepository { 'Trust public gallery':
dsc_name => 'PSGallery',
dsc_ensure => present,
dsc_installationpolicy => trusted,
}
dsc_psmodule { 'Make Ruby manageable via uru':
dsc_name => 'RubyInstaller',
dsc_ensure => present,
}
For more information about using a built module, check out our narrative documentation.
Properties
Note that the only properties specified in a resource declaration which are passed to Invoke-Dsc are all prepended with dsc.
If a property does _not start with dsc_ it is used to control how Puppet interacts with DSC/other Puppet resources - for example,
specifying a unique name for the resource for Puppet to distinguish between declarations or Puppet metaparameters (notifies,
before, etc).
Troubleshooting
In general, there are three broad categories of problems:
- Problems with the way the underlying DSC resource works.
- Problems with the type definition, where you can't specify a valid set of properties for the DSC resource
- Problems with calling the underlying DSC resource - the parameters aren't being passed correctly or the resource can't be found
Unfortunately, problems with the way the underlying DSC resource works are something we can't help directly with. You'll need to file an issue with the upstream maintainers for the PowerShell module.
Problems with the type definition are when a value that should be valid according to the DSC resource's documentation and code is not accepted by the Puppet wrapper. If and when you run across one of these, please file an issue with the Puppet DSC Builder; this is where the conversion happens and once we know of a problem we can fix it and regenerate the Puppet modules. To help us identify the issue, please specify the DSC module, version, resource, property and values that are giving you issues. Once a fix is available we will regenerate and release updated versions of this Puppet wrapper.
Problems with calling the underlying DSC resource become apparent by comparing <value passed in in puppet>
with <value received by DSC>
.
In this case, please file an issue with the puppetlabs/pwshlib module, which is where the DSC base provider actually lives.
We'll investigate and prioritize a fix and update the puppetlabs/pwshlib module.
Updating to the pwshlib version with the fix will immediately take advantage of the improved functionality without waiting for this module to be reconverted and published.
For specific information on troubleshooting a generated module, check the troubleshooting guide for the puppet.dsc module.
Known Limitations
Currently, because of the way Puppet caches files on agents, use of the legacy puppetlabs-dsc
module is not compatible with this or any auto-generated DSC module.
Inclusion of both will lead to pluginsync conflicts.
Reference
Table of Contents
Resource types
dsc_xadcomputer
: The DSC xADComputer resource type. Automatically generated from version 2.13.0.0dsc_xaddomain
: The DSC xADDomain resource type. Automatically generated from version 2.13.0.0dsc_xaddomaincontroller
: The DSC xADDomainController resource type. Automatically generated from version 2.13.0.0dsc_xaddomaindefaultpasswordpolicy
: The DSC xADDomainDefaultPasswordPolicy resource type. Automatically generated from version 2.13.0.0dsc_xaddomaintrust
: The DSC xADDomainTrust resource type. Automatically generated from version 2.13.0.0dsc_xadgroup
: The DSC xADGroup resource type. Automatically generated from version 2.13.0.0dsc_xadorganizationalunit
: The DSC xADOrganizationalUnit resource type. Automatically generated from version 2.13.0.0dsc_xadrecyclebin
: The DSC xADRecycleBin resource type. Automatically generated from version 2.13.0.0dsc_xaduser
: The DSC xADUser resource type. Automatically generated from version 2.13.0.0dsc_xwaitforaddomain
: The DSC xWaitForADDomain resource type. Automatically generated from version 2.13.0.0
Resource types
dsc_xadcomputer
The DSC xADComputer resource type. Automatically generated from version 2.13.0.0
Properties
The following properties are available in the dsc_xadcomputer
type.
dsc_description
Data type: Optional[String]
Specifies a description of the computer object
dsc_displayname
Data type: Optional[String]
Specifies the display name of the computer
dsc_distinguishedname
Data type: Optional[String]
Returns the X.500 path of the computer object
dsc_dnshostname
Data type: Optional[String]
Specifies the fully qualified domain name (FQDN) of the computer
dsc_domaincontroller
Data type: Optional[String]
Specifies the Active Directory Domain Services instance to connect to perform the task
dsc_enabled
Data type: Optional[Boolean]
Specifies if the computer account is enabled
dsc_ensure
Data type: Optional[Enum['Present', 'Absent']]
dsc_location
Data type: Optional[String]
Specifies the location of the computer, such as an office number
dsc_manager
Data type: Optional[String]
Specifies the user or group Distinguished Name that manages the computer object
dsc_path
Data type: Optional[String]
Specifies the X.500 path of the Organizational Unit (OU) or container where the computer is located
dsc_requestfile
Data type: Optional[String]
Specifies the full path to the Offline Domain Join Request file to create.
dsc_serviceprincipalnames
Data type: Optional[Array[String]]
Specifies the service principal names for the computer account
dsc_sid
Data type: Optional[String]
Returns the security identifier of the computer object
dsc_userprincipalname
Data type: Optional[String]
Specifies the UPN assigned to the computer account
Parameters
The following parameters are available in the dsc_xadcomputer
type.
dsc_computername
namevar
Data type: String
Specifies the name of the computer
dsc_domainadministratorcredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Specifies the user account credentials to use to perform the task
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xaddomain
The DSC xADDomain resource type. Automatically generated from version 2.13.0.0
Properties
The following properties are available in the dsc_xaddomain
type.
dsc_databasepath
Data type: Optional[String]
Path to a directory that contains the domain database
dsc_domainnetbiosname
Data type: Optional[String]
NetBIOS name for the new domain
dsc_logpath
Data type: Optional[String]
Path to a directory for the log file that will be written
dsc_parentdomainname
Data type: Optional[String]
Fully qualified name of the parent domain
dsc_sysvolpath
Data type: Optional[String]
Path to a directory where the Sysvol file will be written
Parameters
The following parameters are available in the dsc_xaddomain
type.
dsc_dnsdelegationcredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Credential used for creating DNS delegation
dsc_domainadministratorcredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Credentials used to query for domain existence
dsc_domainname
namevar
Data type: String
Name of the domain to which the user will be added
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_safemodeadministratorpassword
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Password for the administrator account when the computer is started in Safe Mode
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xaddomaincontroller
The DSC xADDomainController resource type. Automatically generated from version 2.13.0.0
Properties
The following properties are available in the dsc_xaddomaincontroller
type.
dsc_databasepath
Data type: Optional[String]
dsc_logpath
Data type: Optional[String]
dsc_sysvolpath
Data type: Optional[String]
Parameters
The following parameters are available in the dsc_xaddomaincontroller
type.
dsc_domainadministratorcredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_domainname
namevar
Data type: String
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_safemodeadministratorpassword
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xaddomaindefaultpasswordpolicy
The DSC xADDomainDefaultPasswordPolicy resource type. Automatically generated from version 2.13.0.0
Properties
The following properties are available in the dsc_xaddomaindefaultpasswordpolicy
type.
dsc_complexityenabled
Data type: Optional[Boolean]
Whether password complexity is enabled for the default password policy
dsc_domaincontroller
Data type: Optional[String]
Active Directory domain controller to enact the change upon
dsc_lockoutduration
Data type: Optional[Integer[0, 4294967295]]
Length of time that an account is locked after the number of failed login attempts (minutes)
dsc_lockoutobservationwindow
Data type: Optional[Integer[0, 4294967295]]
Maximum time between two unsuccessful login attempts before the counter is reset to 0 (minutes)
dsc_lockoutthreshold
Data type: Optional[Integer[0, 4294967295]]
Number of unsuccessful login attempts that are permitted before an account is locked out
dsc_maxpasswordage
Data type: Optional[Integer[0, 4294967295]]
Maximum length of time that you can have the same password (minutes)
dsc_minpasswordage
Data type: Optional[Integer[0, 4294967295]]
Minimum length of time that you can have the same password (minutes)
dsc_minpasswordlength
Data type: Optional[Integer[0, 4294967295]]
Minimum number of characters that a password must contain
dsc_passwordhistorycount
Data type: Optional[Integer[0, 4294967295]]
Number of previous passwords to remember
dsc_reversibleencryptionenabled
Data type: Optional[Boolean]
Whether the directory must store passwords using reversible encryption
Parameters
The following parameters are available in the dsc_xaddomaindefaultpasswordpolicy
type.
dsc_credential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Credentials used to access the domain
dsc_domainname
namevar
Data type: String
Name of the domain to which the password policy will be applied
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xaddomaintrust
The DSC xADDomainTrust resource type. Automatically generated from version 2.13.0.0
Properties
The following properties are available in the dsc_xaddomaintrust
type.
dsc_ensure
Data type: Optional[Enum['Present', 'Absent']]
Should this resource be present or absent
dsc_trustdirection
Data type: Enum['Bidirectional', 'Inbound', 'Outbound']
Direction of trust
dsc_trusttype
Data type: Enum['External', 'Forest']
Type of trust
Parameters
The following parameters are available in the dsc_xaddomaintrust
type.
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_sourcedomainname
namevar
Data type: String
Name of the AD domain that is requesting the trust
dsc_targetdomainadministratorcredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Credentials to authenticate to the target domain
dsc_targetdomainname
namevar
Data type: String
Name of the AD domain that is being trusted
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xadgroup
The DSC xADGroup resource type. Automatically generated from version 2.13.0.0
Properties
The following properties are available in the dsc_xadgroup
type.
dsc_category
Data type: Optional[Enum['Security', 'Distribution']]
Active Directory group category
dsc_description
Data type: Optional[String]
Description of the Active Directory group
dsc_displayname
Data type: Optional[String]
Display name of the Active Directory group
dsc_domaincontroller
Data type: Optional[String]
Active Directory domain controller to enact the change upon
dsc_ensure
Data type: Optional[Enum['Present', 'Absent']]
Should this resource be present or absent
dsc_groupscope
Data type: Optional[Enum['DomainLocal', 'Global', 'Universal']]
Active Directory group scope
dsc_managedby
Data type: Optional[String]
Active Directory managed by attribute specified as a DistinguishedName
dsc_members
Data type: Optional[Array[String]]
Active Directory group membership should match membership exactly
dsc_membershipattribute
Data type: Optional[Enum['SamAccountName', 'DistinguishedName', 'ObjectGUID', 'SID']]
Active Directory attribute used to perform membership operations
dsc_memberstoexclude
Data type: Optional[Array[String]]
Active Directory group should NOT include these members
dsc_memberstoinclude
Data type: Optional[Array[String]]
Active Directory group should include these members
dsc_notes
Data type: Optional[String]
Active Directory group notes field
dsc_path
Data type: Optional[String]
Location of the group within Active Directory expressed as a Distinguished Name
Parameters
The following parameters are available in the dsc_xadgroup
type.
dsc_credential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Credentials used to enact the change upon
dsc_groupname
namevar
Data type: String
Name of the Active Directory group
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xadorganizationalunit
The DSC xADOrganizationalUnit resource type. Automatically generated from version 2.13.0.0
Properties
The following properties are available in the dsc_xadorganizationalunit
type.
dsc_description
Data type: Optional[String]
The description of the OU
dsc_ensure
Data type: Optional[Enum['Present', 'Absent']]
dsc_protectedfromaccidentaldeletion
Data type: Optional[Boolean]
Defaults to True
Parameters
The following parameters are available in the dsc_xadorganizationalunit
type.
dsc_credential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
The credential to be used to perform the operation on Active Directory
dsc_name
namevar
Data type: String
The name of OU
dsc_path
namevar
Data type: String
Specifies the X500 path of the OU or container where the new object is created
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xadrecyclebin
The DSC xADRecycleBin resource type. Automatically generated from version 2.13.0.0
Properties
The following properties are available in the dsc_xadrecyclebin
type.
dsc_forestmode
Data type: Optional[String]
dsc_recyclebinenabled
Data type: Optional[String]
Parameters
The following parameters are available in the dsc_xadrecyclebin
type.
dsc_enterpriseadministratorcredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_forestfqdn
namevar
Data type: String
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xaduser
The DSC xADUser resource type. Automatically generated from version 2.13.0.0
Properties
The following properties are available in the dsc_xaduser
type.
dsc_cannotchangepassword
Data type: Optional[Boolean]
Specifies whether the account password can be changed
dsc_city
Data type: Optional[String]
Specifies the user's town or city (ldapDisplayName 'l')
dsc_commonname
Data type: Optional[String]
Specifies the common nane assigned to the user account (ldapDisplayName 'cn')
dsc_company
Data type: Optional[String]
Specifies the user's company (ldapDisplayName 'company')
dsc_country
Data type: Optional[String]
Specifies the country or region code for the user's language of choice (ldapDisplayName 'c')
dsc_department
Data type: Optional[String]
Specifies the user's department (ldapDisplayName 'department')
dsc_description
Data type: Optional[String]
Specifies a description of the object (ldapDisplayName 'description')
dsc_displayname
Data type: Optional[String]
Specifies the display name of the object (ldapDisplayName 'displayName')
dsc_distinguishedname
Data type: Optional[String]
Returns the X.500 path of the object
dsc_division
Data type: Optional[String]
Specifies the user's division (ldapDisplayName 'division')
dsc_domaincontroller
Data type: Optional[String]
Specifies the Active Directory Domain Services instance to use to perform the task.
dsc_emailaddress
Data type: Optional[String]
Specifies the user's e-mail address (ldapDisplayName 'mail')
dsc_employeeid
Data type: Optional[String]
Specifies the user's employee ID (ldapDisplayName 'employeeID')
dsc_employeenumber
Data type: Optional[String]
Specifies the user's employee number (ldapDisplayName 'employeeNumber')
dsc_enabled
Data type: Optional[Boolean]
Specifies if the account is enabled (default True)
dsc_ensure
Data type: Optional[Enum['Present', 'Absent']]
Specifies whether the user account is created or deleted
dsc_fax
Data type: Optional[String]
Specifies the user's fax phone number (ldapDisplayName 'facsimileTelephoneNumber')
dsc_givenname
Data type: Optional[String]
Specifies the user's given name (ldapDisplayName 'givenName')
dsc_homedirectory
Data type: Optional[String]
Specifies a user's home directory path (ldapDisplayName 'homeDirectory')
dsc_homedrive
Data type: Optional[String]
Specifies a drive that is associated with the UNC path defined by the HomeDirectory property (ldapDisplayName 'homeDrive')
dsc_homepage
Data type: Optional[String]
Specifies the URL of the home page of the object (ldapDisplayName 'wWWHomePage')
dsc_homephone
Data type: Optional[String]
Specifies the user's home telephone number (ldapDisplayName 'homePhone')
dsc_initials
Data type: Optional[String]
Specifies the initials that represent part of a user's name (ldapDisplayName 'initials')
dsc_ipphone
Data type: Optional[String]
Specifies the user's IP telephony phone number (ldapDisplayName 'ipPhone')
dsc_jobtitle
Data type: Optional[String]
Specifies the user's title (ldapDisplayName 'title')
dsc_logonscript
Data type: Optional[String]
Specifies a path to the user's log on script (ldapDisplayName 'scriptPath')
dsc_manager
Data type: Optional[String]
Specifies the user's manager specified as a Distinguished Name (ldapDisplayName 'manager')
dsc_mobilephone
Data type: Optional[String]
Specifies the user's mobile phone number (ldapDisplayName 'mobile')
dsc_notes
Data type: Optional[String]
Specifies the notes attached to the user's accoutn (ldapDisplayName 'info')
dsc_office
Data type: Optional[String]
Specifies the location of the user's office or place of business (ldapDisplayName 'physicalDeliveryOfficeName')
dsc_officephone
Data type: Optional[String]
Specifies the user's office telephone number (ldapDisplayName 'telephoneNumber')
dsc_pager
Data type: Optional[String]
Specifies the user's pager number (ldapDisplayName 'pager')
dsc_passwordauthentication
Data type: Optional[Enum['Default', 'Negotiate']]
Specifies the authentication context type used when testing passwords
dsc_passwordneverexpires
Data type: Optional[Boolean]
Specifies whether the password of an account can expire
dsc_path
Data type: Optional[String]
Specifies the X.500 path of the Organizational Unit (OU) or container where the new object is created
dsc_pobox
Data type: Optional[String]
Specifies the user's post office box number (ldapDisplayName 'postOfficeBox')
dsc_postalcode
Data type: Optional[String]
Specifies the user's postal code or zip code (ldapDisplayName 'postalCode')
dsc_profilepath
Data type: Optional[String]
Specifies a path to the user's profile (ldapDisplayName 'profilePath')
dsc_state
Data type: Optional[String]
Specifies the user's or Organizational Unit's state or province (ldapDisplayName 'st')
dsc_streetaddress
Data type: Optional[String]
Specifies the user's street address (ldapDisplayName 'streetAddress')
dsc_surname
Data type: Optional[String]
Specifies the user's last name or surname (ldapDisplayName 'sn')
dsc_userprincipalname
Data type: Optional[String]
Specifies the UPN assigned to the user account (ldapDisplayName 'userPrincipalName')
Parameters
The following parameters are available in the dsc_xaduser
type.
dsc_domainadministratorcredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Specifies the user account credentials to use to perform this task
dsc_domainname
namevar
Data type: String
Name of the domain where the user account is located (only used if password is managed)
dsc_password
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
Specifies a new password value for the account
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_username
namevar
Data type: String
Specifies the Security Account Manager (SAM) account name of the user (ldapDisplayName 'sAMAccountName')
name
namevar
Data type: String
Description of the purpose for this resource declaration.
dsc_xwaitforaddomain
The DSC xWaitForADDomain resource type. Automatically generated from version 2.13.0.0
Properties
The following properties are available in the dsc_xwaitforaddomain
type.
dsc_rebootretrycount
Data type: Optional[Integer[0, 4294967295]]
dsc_retrycount
Data type: Optional[Integer[0, 4294967295]]
dsc_retryintervalsec
Data type: Optional[Integer[0, 18446744073709551615]]
Parameters
The following parameters are available in the dsc_xwaitforaddomain
type.
dsc_domainname
namevar
Data type: String
dsc_domainusercredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
dsc_psdscrunascredential
Data type: Optional[Struct[{ user => String[1], password => Sensitive[String[1]] }]]
name
namevar
Data type: String
Description of the purpose for this resource declaration.
- Converted AppVeyor.yml to pull Pester from PSGallery instead of Chocolatey
- xADUser: Adds "PasswordAuthentication" option when testing user passwords to support NTLM authentication with Active Directory Certificate Services deployments
- xADUser: Adds descriptions to user properties within the schema file.
- xADGroup: Fixes bug when updating groups when alternate Credentials are specified.
Dependencies
- puppetlabs/pwshlib (>= 0.7.0 < 2.0.0)