Share via

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

  • Article

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:

Comments

  • Anonymous
    January 01, 2003
    Thanks for getting this done!
  • Anonymous
    January 01, 2003
    Any thoughts into parsing the "Arguments" parameter and reading what roles are to be installed and verifying they are installed? Say they start out with only the Mailbox role then want to add the CAS role, the check never looks to see if the roles are different from whats on the server to what's in the arguments.
  • Anonymous
    January 01, 2003
    That definitely seems possible, I just haven't heard anyone request it yet. Also not sure how common of a scenario that is. It would help to know how often people change roles on installed servers. Function IsSetupPartiallyCompleted in MiscxExchangeCommon.psm1 already checks the keys that indicate whether the various roles have been fully installed or not, so it probably wouldn't be too difficult to parse the Arguments parameter and do some additional role based checks. A similar feature I think would be kind of neat would be if the resource could optionally look at the installed version so that it could be used for upgrades as well, rather than just initial installs. I think that would be applicable to lots of people.
  • Anonymous
    January 01, 2003
    For getting the version, I'd either use the Exchange Management Shell, or the registry. In the registry, you can check HKLMSOFTWAREMicrosoftExchangeServerV15Setup, and look at MsiBuildMajor and MsiBuildMinor. Alternately you can run Get-ExchangeServer and check AdminDisplayVersion. Either of these should be updated when you install a CU. You could compare those values to known versions (assuming you've installed that CU before and have checked what it uses), or possibly by looking at the version property of setup.exe. I don't think the Minor version always gets put on that file though, so that may not be completely reliable.
  • Anonymous
    May 23, 2015
    Hi Mike,
    first of all: Great stuff!
    I'm wondering how you manage upgrades of CU's? I'm currently working on a workflow to implement this. Maybe you have some hints? My first idea is to check registry for version and depending on the values initiate an installation with the mode 'upgrade'.
    Thanks!
    Ciao,
    Ingo
  • Anonymous
    May 29, 2015
    Thanks Mike,

    That was my idea, using the registry.

    Ciao,
    Ingo
  • Anonymous
    June 03, 2015
    Hi Mike,

    Thank you for your article! I'm unfortunately running into trouble during the installation. Exchange is successfully installed (no error in Exchange's logs) but the script stops with the following error :

    The PowerShell DSC resource MSFT_xExchInstall threw one or more non-terminating errors while running the Set-TargetResource functionality. These errors are
    logged to the ETW channel called Microsoft-Windows-DSC/Operational. Refer to this channel for more details.
    + CategoryInfo : InvalidOperation: (:) [], CimException
    + FullyQualifiedErrorId : NonTerminatingErrorFromProvider
    + PSComputerName : exchange3

    The SendConfigurationApply function did not succeed.
    + CategoryInfo : NotSpecified: (root/Microsoft/...gurationManager:String) [], CimException
    + FullyQualifiedErrorId : MI RESULT 1
    + PSComputerName : exchange3

    Any idea of what could cause this error? Thanks!

    John
  • Anonymous
    June 09, 2015
    Hi John, can you run with the -Verbose switch, and send all the output that precedes this error? That will give me some indication of how far the resource got before failing. Also, are you positive Exchange is successfully installed? If you try to run the setup GUI manually, does it report that a previous installation was detected?
  • Anonymous
    June 23, 2015
    Hi Mike,

    Thank you Mike for your support, The Exchange server wasn't properly installed, after fixing this issue, the script worked perfectly!
  • Anonymous
    August 17, 2015
    The comment has been removed
  • Anonymous
    August 17, 2015
    Hi Ken,
    I have not tried using the TargetDir parameter before. I'll see if I can reproduce this, and if so, add it as a known issue for xExchange so that we can fix it in the future.

    Also, just FYI, if you come across issues like this, you can also report them as an Issue directly on GitHub, which is the new home for development of this module:

    https://github.com/powershell/xexchange/issues

    Thanks.
  • Anonymous
    August 18, 2015
    Hi Mike,
    I've submitted this on GitHub. Thanks.
  • Anonymous
    August 23, 2015
    The comment has been removed
  • Anonymous
    August 27, 2015
    I am getting following error after execuing xExchinstall config....Any pointers on what could be the issue?
    he user name or password is incorrect.
    + CategoryInfo : AuthenticationError: (PS_ScheduledTask:) [], CimException
    + FullyQualifiedErrorId : HRESULT 0x8007052e,Set-ScheduledTask
    + PSComputerName : Server3

    VERBOSE: [Server3]: LCM: [ End Set ] [[xExchInstall]InstallExchange] in 2767.2180 seconds.
    The PowerShell provider MSFT_xExchInstall threw one or more non-terminating errors while running the
    Set-TargetResource functionality. These errors are logged to the ETW channel called Microsoft-Windows-DSC/Operational.
    Refer to this channel for more details.
    + CategoryInfo : InvalidOperation: (:) [], CimException
    + FullyQualifiedErrorId : NonTerminatingErrorFromProvider
    + PSComputerName : Server3

    VERBOSE: [Seerver3]: LCM: [ End Set ]
    The SendConfigurationApply function did not succeed.
    + CategoryInfo : NotSpecified: (root/Microsoft/...gurationManager:String) [], CimException
    + FullyQualifiedErrorId : MI RESULT 1
    + PSComputerName : Server3

    VERBOSE: Operation 'Invoke CimMethod' complete.
    VERBOSE: Time taken for configuration job to complete is 2867.623 seconds