DSCResources/MSFT_ADGroup/en-US/about_ADGroup.help.txt

.NAME
    ADGroup
 
.DESCRIPTION
    The ADGroup DSC resource will manage groups within Active Directory.
 
    ## Requirements
 
    * Target machine must be running Windows Server 2008 R2 or later.
    * The parameter RestoreFromRecycleBin requires that the feature Recycle
      Bin has been enabled prior to an object is deleted. If the feature
      Recycle Bin is disabled then the property msDS-LastKnownRDN is not
      added the deleted object.
 
.PARAMETER GroupName
    Key - String
    Name of the Active Directory group.
 
.PARAMETER GroupScope
    Write - String
    Allowed values: DomainLocal, Global, Universal
    Active Directory group scope. Default value is 'Global'.
 
.PARAMETER Category
    Write - String
    Allowed values: Security, Distribution
    Active Directory group category. Default value is 'Security'.
 
.PARAMETER Path
    Write - String
    Location of the group within Active Directory expressed as a Distinguished Name.
 
.PARAMETER Ensure
    Write - String
    Allowed values: Present, Absent
    Specifies if this Active Directory group should be present or absent. Default value is 'Present'.
 
.PARAMETER Description
    Write - String
    Description of the Active Directory group.
 
.PARAMETER DisplayName
    Write - String
    Display name of the Active Directory group.
 
.PARAMETER Credential
    Write - Instance
    The credential to be used to perform the operation on Active Directory.
 
.PARAMETER DomainController
    Write - String
    Active Directory domain controller to enact the change upon.
 
.PARAMETER Members
    Write - StringArray
    Active Directory group membership should match membership exactly.
 
.PARAMETER MembersToInclude
    Write - StringArray
    Active Directory group should include these members.
 
.PARAMETER MembersToExclude
    Write - StringArray
    Active Directory group should NOT include these members.
 
.PARAMETER MembershipAttribute
    Write - String
    Allowed values: SamAccountName, DistinguishedName, ObjectGUID, SID
    Active Directory attribute used to perform membership operations. Default value is 'SamAccountName'.
 
.PARAMETER ManagedBy
    Write - String
    Active Directory managed by attribute specified as a DistinguishedName.
 
.PARAMETER Notes
    Write - String
    Active Directory group notes field.
 
.PARAMETER RestoreFromRecycleBin
    Write - Boolean
    Try to restore the group from the recycle bin before creating a new one.
 
.PARAMETER DistinguishedName
    Read - String
    Returns the distinguished name of the Active Directory group.
 
.EXAMPLE 1
 
This configuration will create a new domain-local group
 
Configuration ADGroup_NewGroup_Config
{
    param
    (
        [parameter(Mandatory = $true)]
        [System.String]
        $GroupName,
 
        [ValidateSet('DomainLocal', 'Global', 'Universal')]
        [System.String]
        $Scope = 'Global',
 
        [ValidateSet('Security', 'Distribution')]
        [System.String]
        $Category = 'Security',
 
        [ValidateNotNullOrEmpty()]
        [System.String]
        $Description
    )
 
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        ADGroup 'ExampleGroup'
        {
            GroupName = $GroupName
            GroupScope = $Scope
            Category = $Category
            Description = $Description
            Ensure = 'Present'
        }
    }
}
 
.EXAMPLE 2
 
This configuration will create a new domain-local group with three members.
 
Configuration ADGroup_NewGroupWithMembers_Config
{
    Import-DscResource -ModuleName ActiveDirectoryDsc
 
    node localhost
    {
        ADGroup 'dl1'
        {
            GroupName = 'DL_APP_1'
            GroupScope = 'DomainLocal'
            Members = 'john', 'jim', 'sally'
        }
    }
}
 
.EXAMPLE 3
 
This configuration will create a new domain-local group in contoso with
three members in different domains.
 
Configuration ADGroup_NewGroupMultiDomainMembers_Config
{
    Import-DscResource -ModuleName ActiveDirectoryDsc
 
    node localhost
    {
        ADGroup 'dl1'
        {
            GroupName = 'DL_APP_1'
            GroupScope = 'DomainLocal'
            MembershipAttribute = 'DistinguishedName'
            Members = @(
                'CN=john,OU=Accounts,DC=contoso,DC=com'
                'CN=jim,OU=Accounts,DC=subdomain,DC=contoso,DC=com'
                'CN=sally,OU=Accounts,DC=anothersub,DC=contoso,DC=com'
            )
        }
    }
}
 
.EXAMPLE 4
 
This configuration will create a new domain-local group in contoso with
two members; one from the contoso domain and one from the fabrikam domain.
This qualified SamAccountName format is required if any of the users are in a
one-way trusted forest/external domain.
 
Configuration ADGroup_NewGroupOneWayTrust_Config
{
    Import-DscResource -ModuleName ActiveDirectoryDsc
 
    node localhost
    {
        ADGroup 'ExampleExternalTrustGroup'
        {
            GroupName = 'ExampleExternalTrustGroup'
            GroupScope = 'DomainLocal'
            MembershipAttribute = 'SamAccountName'
            Members = @(
                'contoso\john'
                'fabrikam\toby'
            )
        }
    }
}