ActiveDirectoryDsc

6.6.0

DSCResources/MSFT_WaitForADDomain/en-US/about_WaitForADDomain.help.txt

.NAME
    WaitForADDomain
 
.DESCRIPTION
    The WaitForADDomain resource is used to wait for Active Directory domain
    controller to become available in the domain, or available in
    a specific site in the domain.
 
    >Running the resource as NT AUTHORITY\SYSTEM, only work when
    >evaluating the domain on the current node, for example on a
    >node that should be a domain controller (which might require a
    >restart of the node once the node becomes a domain controller).
    >In all other scenarios use either the built-in parameter
    >PsDscRunAsCredential, or the parameter Credential.
 
    Using the parameter WaitForValidCredentials ignores authentication
    errors a let the resource wait until time timeout is reached. If the
    parameter WaitForValidCredentials is not specified and the resource
    throws an authentication error, then the resource will fail. But the
    Local Configuration Manger (LCM) will automatically run the configuration
    again to try to get the node in desired state. If and when the LCM retries
    depends on how the LCM is configured.
 
    ## Requirements
 
    * Target machine must be running Windows Server 2008 R2 or later.
 
.PARAMETER DomainName
    Key - String
    Specifies the fully qualified domain name to wait for.
 
.PARAMETER SiteName
    Write - String
    Specifies the site in the domain where to look for a domain controller.
 
.PARAMETER Credential
    Write - Instance
    Specifies the credentials that are used when accessing the domain, unless the built-in PsDscRunAsCredential is used.
 
.PARAMETER WaitTimeout
    Write - UInt64
    Specifies the timeout in seconds that the resource will wait for the domain to be accessible. Default value is 300 seconds.
 
.PARAMETER RestartCount
    Write - UInt32
    Specifies the number of times the node will be reboot in an effort to connect to the domain.
 
.PARAMETER WaitForValidCredentials
    Write - Boolean
    Specifies that the resource will not throw an error if authentication fails using the provided credentials and continue wait for the timeout. This can be used if the credentials are known to eventually exist but there are a potential timing issue before they are accessible.
 
.PARAMETER IsAvailable
    Read - Boolean
    Returns a value indicating if a domain controller was found.
 
.EXAMPLE 1
 
This configuration will wait for an Active Directory domain controller
to respond within 300 seconds (default) in the domain 'contoso.com'
before returning and allowing the configuration to continue to run.
If the timeout is reached an error will be thrown.
This will use the current user when determining if the domain is available,
if run though LCM this will use SYSTEM (which might not have access).
 
Configuration WaitForADDomain_WaitForDomainController_Config
{
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        WaitForADDomain 'contoso.com'
        {
            DomainName = 'contoso.com'
        }
    }
}
 
.EXAMPLE 2
 
This configuration will wait for an Active Directory domain controller
to respond within 300 seconds (default) in the domain 'contoso.com'
before returning and allowing the configuration to continue to run.
If the timeout is reached an error will be thrown.
This will use the user credential passed in the built-in PsDscRunAsCredential
parameter when determining if the domain is available.
 
Configuration WaitForADDomain_WaitForDomainControllerUsingBuiltInCredential_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        WaitForADDomain 'contoso.com'
        {
            DomainName = 'contoso.com'
 
            PsDscRunAsCredential = $Credential
        }
    }
}
 
.EXAMPLE 3
 
This configuration will wait for an Active Directory domain controller
to respond within 300 seconds (default) in the domain 'contoso.com'
before returning and allowing the configuration to continue to run.
If the timeout is reached an error will be thrown.
This will use the user credential passed in the parameter Credential
when determining if the domain is available.
 
Configuration WaitForADDomain_WaitForDomainControllerUsingCredential_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        WaitForADDomain 'contoso.com'
        {
            DomainName = 'contoso.com'
            Credential = $Credential
        }
    }
}
 
.EXAMPLE 4
 
This configuration will wait for an Active Directory domain controller
in the site 'Europe' to respond within 300 seconds (default) in the
domain 'contoso.com' before returning and allowing the configuration to
continue to run.
If the timeout is reached an error will be thrown.
This will use the user credential passed in the built-in PsDscRunAsCredential
parameter when determining if the domain is available.
 
Configuration WaitForADDomain_WaitForDomainControllerInSite_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        WaitForADDomain 'contoso.com'
        {
            DomainName = 'contoso.com'
            SiteName = 'Europe'
 
            PsDscRunAsCredential = $Credential
        }
    }
}
 
.EXAMPLE 5
 
This configuration will wait for an Active Directory domain controller
to respond within 300 seconds (default) in the domain 'contoso.com'
before returning and allowing the configuration to continue to run.
If the timeout is reached the node will be restarted up to two times
and again wait after each restart. If no domain controller is found
after the second restart an error will be thrown.
This will use the user credential passed in the built-in PsDscRunAsCredential
parameter when determining if the domain is available.
 
Configuration WaitForADDomain_WaitForDomainControllerWithReboot_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        WaitForADDomain 'contoso.com'
        {
            DomainName = 'contoso.com'
            RestartCount = 2
 
            PsDscRunAsCredential = $Credential
        }
    }
}
 
.EXAMPLE 6
 
This configuration will wait for an Active Directory domain controller
to respond within 600 seconds in the domain 'contoso.com' before
returning and allowing the configuration to continue to run. If the timeout
is reached an error will be thrown.
This will use the user credential passed in the built-in PsDscRunAsCredential
parameter when determining if the domain is available.
 
Configuration WaitForADDomain_WaitForDomainControllerWithLongerDelay_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        WaitForADDomain 'contoso.com'
        {
            DomainName = 'contoso.com'
            WaitTimeout = 600
 
            PsDscRunAsCredential = $Credential
        }
    }
}
 
.EXAMPLE 7
 
This configuration will wait for an Active Directory domain controller
to respond within the default period, and ignore any authentication
errors.
 
Configuration WaitForADDomain_WaitForDomainControllerIgnoringAuthenticationErrors_Config
{
    param
    (
        [Parameter(Mandatory = $true)]
        [ValidateNotNullOrEmpty()]
        [System.Management.Automation.PSCredential]
        $Credential
    )
 
    Import-DscResource -Module ActiveDirectoryDsc
 
    Node localhost
    {
        WaitForADDomain 'contoso.com'
        {
            DomainName = 'contoso.com'
            WaitForValidCredentials = $true
 
            PsDscRunAsCredential = $Credential
        }
    }
}