Installing Exchange Using DSC - Managing Exchange 2013 With DSC - Part 5

Managing Exchange 2013 With DSC

Part 1 - Introducing xExchange

Part 2 - The QuickStart Template

Part 3 - Automating Mount Point Setup and Maintenance for AutoReseed

Part 4 - Using a DSC Pull Server to Deploy the xExchange Module

Part 5 - Installing Exchange Using DSC

 

Installing Exchange Using DSC

Hey Everyone. Sorry for the lack of updates in this blog series lately. We've been busy working on a major update to the xExchange module, which includes the ability to install Exchange, as well as to automate Jetstress (separate blog post coming soon). As a reminder, you can download the latest version of xExchange from the PowerShell Gallery here.

For this post, I'll be talking about using Desired State Configuration to automate the installation of Exchange 2013 with the new xExchInstall resource. I'll cover how to use the resource, why the resource does what it does, and how to monitor and troubleshoot the resource.

 

The xExchInstall Resource

The xExchInstall resource is relatively simple to configure, as it only contains three parameters, all of which are required (see this article for help installing Exchange using unattended mode):

  • Path: This is the full path to setup.exe in the Exchange 2013 setup directory.

  • Arguments: These are the command line arguments to pass into setup.exe. They are used the same as if you were calling setup.exe from the Command Prompt.

  • Credential: These are the credentials used to perform the installation.

 

 Here's a simple example of how to use the resource:

 xExchInstall InstallExchange
{
    Path       = "C:\Binaries\E15CU7\Setup.exe"
    Arguments  = "/mode:Install /role:Mailbox,ClientAccess /Iacceptexchangeserverlicenseterms"
    Credential = $Creds
}

 

Using the resource like this would be equivalent to going in the Exchange setup directory with Command Prompt, and running:

setup /mode:Install /role:Mailbox,ClientAccess /Iacceptexchangeserverlicenseterms"

 

Using xExchInstall In A Script

For this example, I'm using a slightly modified version of the InstallExchange example which ships with xExchange (as of v1.0.3.6). This is located in the xExchange module folder underneath Examples\InstallExchange.

 Configuration InstallExchange
{
    param
    (
        [PSCredential]$Creds
    )

    Import-DscResource -Module xExchange
    Import-DscResource -Module xPendingReboot

    Node $AllNodes.NodeName
    {
        LocalConfigurationManager
        {
            CertificateId      = $Node.Thumbprint
        }

        xPendingReboot BeforeExchangeInstall
        {
            Name      = "BeforeExchangeInstall"
        }

        xExchInstall InstallExchange
        {
            Path       = "C:\Binaries\E15CU7\Setup.exe"
            Arguments  = "/mode:Install /role:Mailbox,ClientAccess /Iacceptexchangeserverlicenseterms"
            Credential = $Creds

            DependsOn  = '[xPendingReboot]BeforeExchangeInstall'
        }

        xPendingReboot AfterExchangeInstall
        {
            Name      = "AfterExchangeInstall"

            DependsOn = '[xExchInstall]InstallExchange'
        }
    }
}

The only thing to really note here is that I chose to use the xPendingReboot module/resource (download here) to see if reboots are pending both before and after the installation of Exchange. The one before the installation isn't necessarily required, but can help the Exchange installation process to run more smoothly. I definitely recommend using the xPendingReboot after the install, as a reboot is almost always required after applying an Exchange 2013 Cumulative Update. If you want to use the same xPendingReboot resources in your script, you will need to make sure to download xPendingReboot and put in in the C:\Program Files\WindowsPowerShell\Modules directory.

 

Script Execution Behavior

When the script is successfully executed, the xExchInstall resource will behave in one of two different ways. Either it will proceed all the way through, and won't require a reboot until after Exchange is installed (see Behavior 2), or it will want to reboot the server before Exchange setup has even begun (Behavior 1). These behaviors are independent from reboots that may be caused by the xPendingReboot resources.

 

Behavior 1

The first behavior I'll describe is the most common behavior I've seen so far. This is the behavior that people running Windows Management Framework 4 should see (WMF5 is NOT CURRENTLY SUPPORTED with Exchange 2013). When you execute the script in Verbose mode, you'll see Verbose output similar to the following:

[[xExchInstall]InstallExchange] Entering function 'Test-TargetResource'. Notable parameters: Arguments = '/mode:Install /role:Mailbox,ClientAccess /Iacceptexchangeserverlicenseterms', Path = 'C:\Binaries\E15CU7\Setup.exe'
[[xExchInstall]InstallExchange] Exchange is either not installed, or a previous install only partially completed.
[[xExchInstall]InstallExchange] in 1.7030 seconds.
[[xExchInstall]InstallExchange]
[[xExchInstall]InstallExchange] Entering function 'Set-TargetResource'. Notable parameters: Arguments = '/mode:Install /role:Mailbox,ClientAccess /Iacceptexchangeserverlicenseterms', Path = 'C:\Binaries\E15CU7\Setup.exe'
[[xExchInstall]InstallExchange] Value 'UpdatedConfig' missing from registry key HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\WSMAN. Running: winrm i restore winrm/config
[[xExchInstall]InstallExchange] Machine needs to be rebooted before Exchange setup can proceed
[[xExchInstall]InstallExchange] in 1.8030 seconds.

What's happening here is that xExchInstall has detected that certain WSMan registry keys are not present, has decided to configure WSMan using the command 'winrm i restore winrm/config', and is waiting for a reboot to occur before starting the install. Once the machine has been rebooted, the installation should begin automatically.

The reason this pre-configuration of WinRM occurs is to prevent an issue which can occur later in Exchange setup. During setup, Exchange checks for the presence of a few registry keys to determine if WinRM is configured correctly. If any of those keys are missing, setup runs 'winrm i restore winrm/config', then attempts to restart the WinRM service. Because a DSC configuration is actively running, the stop of the WinRM service fails, which then causes Exchange setup to fail. To pre-empt this condition, xExchInstall looks for these registry keys itself, and if they're missing or not configured, runs the above winrm command before Exchange setup has a chance to try.

Here's a full screenshot of this behavior:

 

Behavior 2

The less common behavior is for xExchInstall to go through the whole setup process, and not require a reboot at all (the xPendingReboot resource may still force a reboot after setup has completed). This would occur if you manually ran 'winrm i restore winrm/config' prior to the install, or possibly if you had WMF5 installed (again, WMF5 is NOT CURRENTLY SUPPORTED with Exchange 2013).

With this behavior, xExchInstall will launch Setup.exe (which then launches ExSetup.exe), and then will report to the screen every minute that setup is still running until it has completed:

 

Monitoring Install Progress

If you are installing Exchange using a DSC pull server, or if you experience Behavior 1 from above, it can be difficult to tell exactly what is happening with the xExchInstall resource. The following are different approaches you can use to determine if Exchange setup is running, and if it has encountered any issues.

 

Look for the ExSetup.exe Process

One way to determine if setup is running is to log on to the machine where Exchange is being installed, and look for the ExSetup.exe process in Task Manager:

 

You could also use the Get-Process cmdlet to inspect whether the ExSetup.exe process exists on a remote machine:

 

Look in the Exchange Setup Logs

As with troubleshooting any Exchange Setup issue, another place you can look is the C:\ExchangeSetupLogs folder. In ExchangeSetup.log, you can see the exact status of the install, and determine whether it is currently running, or whether it failed or succeeded.

 

Use the xDscDiagnostics Module

Another way to determine what xExchInstall is doing is to use the xDscDiagnostics module (download here). This blog does a great job explaining how to use the module.

After downloading and installing the module, the first thing you'll want to do is enable Analytic logging using the Update-xDscEventLogStatus cmdlet. This must be done prior to running the script to install Exchange:

 

After you've started the script containing xExchInstall, use Get-xDscOperation to find the appropriate SequenceId (for me it was always Id 1):

 

Once you've located the correct SequenceId, use Trace-xDscOperation to see all events:

 

You can use the .Message property of the Trace-xDscOperation output variable to make it easier to see the Verbose output that was logged:

 

After you're done troubleshooting, make sure to turn logging back off: