Introducing xExchange - Managing Exchange 2013 With DSC - Part 1

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

 

Introducing the xExchange Module for Powershell Desired State Configuration

Welcome to the first in a series of blog posts which will be covering the xExchange module for Powershell Desired State Configuration. The xExchange module is a DSC module designed for configuring Exchange 2013 servers, and can be downloaded from the PowerShell Gallery here. With help from Jason Walker, creating Exchange DSC resources (as well as Bitlocker resources) has been one of my main projects for the past few months.

It is my goal in this blog series to gradually introduce the various components that are required to utilize xExchange resources within a DSC configuration script. I realize the module is large, and is probably pretty daunting for someone that hasn’t worked with DSC before (and maybe even for those that have). That being the case, I plan on introducing concepts in separate posts in a way that each post builds on the ones before them.

 

Why DSC?

The main driver for wanting to create DSC resources for Exchange was to help improve the configuration management story for one of the customers who I work with. My customer runs a very complex Exchange environment, which is extensively customized to meet business requirements. A number of the configuration changes they make, especially ones which are stored in IIS, are prone to being reverted when Service Packs and Cumulative Updates are applied. With previous versions of Exchange, they had to maintain multiple sets of configuration scripts. One set of scripts would actually apply the configuration. The other set of scripts would verify all the settings that were set by the configuration scripts. If any updates were applied, or if they were troubleshooting issues, they could run the verification scripts to see if anything changed, and then re-run the configuration scripts to fix any issues.

While the set of configuration and verification scripts worked, it required a lot of work to keep the two in sync, and also required a lot of work running the scripts semi periodically in a large scale environment. Once DSC was released, I realized that it would be a great opportunity to consolidate the handful of scripts that my customer had, and group the configuration and verification for each Exchange resource type into more logical units. It also was a good opportunity to better automate their configuration story. Once the DSC configuration is applied in pull mode, they can leave the configuration alone, and any divergences in configuration will be automatically corrected.

 

Requirements

The xExchange module has the following requirements for the machines that will be managed:

  • Exchange Server 2013 (only tested on Exchange 2013 CU5 and CU6 as of 10/10/2014)

  • Windows Management Framework 4.0

  • Windows Server 2012 or Windows Server 2012 R2 (earlier versions are not blocked, but they are untested)

 

Resources

The xExchange module contains 24 DSC resources (as of 10/6/2014). A majority of the resources (21) correspond to existing Exchange Powershell cmdlets, and are as follows:

Resource Associated Exchange Cmdlet(s) Category
MSFT_xExchActiveSyncVirtualDirectory Set-ActiveSyncVirtualDirectory Client Access Server
MSFT_xExchAutodiscoverVirtualDirectory Set-AutodiscoverVirtualDirectory Client Access Server
MSFT_xExchClientAccessServer Set-ClientAccessServer Client Access Server
MSFT_xExchDatabaseAvailabilityGroup New/Set-DatabaseAvailabilityGroup Database Availability Group
MSFT_xExchDatabaseAvailabilityGroupMember Add-DatabaseAvailabilityGroupServer Database Availability Group
MSFT_xExchDatabaseAvailabilityGroupNetwork New/Remove/Set-DatabaseAvailabilityGroupNetwork Database Availability Group
MSFT_xExchEcpVirtualDirectory Set-EcpVirtualDirectory Client Access Server
MSFT_xExchExchangeCertificate Enable/Import/Remove-ExchangeCertificate Exchange Server
MSFT_xExchExchangeServer Set-ExchangeServer Exchange Server
MSFT_xExchImapSettings Set-ImapSettings Client Access Server
MSFT_xExchMailboxDatabase New/Set-MailboxDatabase Mailbox Server/Database
MSFT_xExchMailboxDatabaseCopy Add/Set-MailboxDatabaseCopy Mailbox Server/Database
MSFT_xExchMapiVirtualDirectory Set-MapiVirtualDirectory Client Access Server
MSFT_xExchOabVirtualDirectory Set-OabVirtualDirectory Client Access Server
MSFT_xExchOutlookAnywhere Set-OutlookAnywhere Client Access Server
MSFT_xExchOwaVirtualDirectory Set-OwaVirtualDirectory Client Access Server
MSFT_xExchPopSettings Set-PopSettings Client Access Server
MSFT_xExchPowershellVirtualDirectory Set-PowershellVirtualDirectory Client Access Server
MSFT_xExchReceiveConnector New/Remove/Set-ReceiveConnector Transport Server
MSFT_xExchUMService Set-UMService Unified Messaging Server
MSFT_xExchWebServicesVirtualDirectory Set-WebServicesVirtualDirectory Client Access Server

 

The first resource that does not correspond to any existing Exchange cmdlet is the xExchAutoMountPoint resource. This will be covered in detail in a separate blog post:

Resource Category
MSFT_xExchAutoMountPoint Mailbox Server/Database

 

The last two resources that are available are used for synchronization purposes. The first is used while creating Database Availability Groups, and the second is used when creating Mailbox Database copies. Both of these will be covered in a separate blog post as well:

Resource Category
MSFT_xExchWaitForDAG Database Availability Group
MSFT_xExchWaitForMailboxDatabase Mailbox Server/Database

 

Exploring the xExchange Module

After downloading the xExchange module, copy the extracted xExchange folder to ‘%SYSTEMDRIVE%\Program Files\WindowsPowerShell\Modules’. The folder structure should look like:

PS C:\> Get-ChildItem 'C:\Program Files\WindowsPowerShell\Modules\xExchange'

    Directory: C:\Program Files\WindowsPowerShell\Modules\xExchange

Mode LastWriteTime Length Name
---- ------------- ------ ----
d---- 10/10/2014 12:02 PM DSCResources
d---- 10/10/2014 12:02 PM Examples
d---- 10/10/2014 12:02 PM Misc
d---- 10/10/2014 12:02 PM Test
-a--- 10/10/2014 11:38 AM 5652 xExchange.psd1
-a--- 10/10/2014 7:55 AM 59652 xExchange_Documentation.html

 

To confirm that the xExchange module has been correctly detected, run Get-DscResource. You should see all 24 resources listed:

PS C:\> Get-DscResource | where {$_.Module -like "xExchange"} | ft Name, Module

Name Module
---- ------
xExchActiveSyncVirtualDirectory xExchange
xExchAutodiscoverVirtualDirectory xExchange
xExchAutoMountPoint xExchange
xExchClientAccessServer xExchange
xExchDatabaseAvailabilityGroup xExchange
xExchDatabaseAvailabilityGroupMember xExchange
xExchDatabaseAvailabilityGroupNetwork xExchange
xExchEcpVirtualDirectory xExchange
xExchExchangeCertificate xExchange
xExchExchangeServer xExchange
xExchImapSettings xExchange
xExchMailboxDatabase xExchange
xExchMailboxDatabaseCopy xExchange
xExchMapiVirtualDirectory xExchange
xExchOabVirtualDirectory xExchange
xExchOutlookAnywhere xExchange
xExchOwaVirtualDirectory xExchange
xExchPopSettings xExchange
xExchPowerShellVirtualDirectory xExchange
xExchReceiveConnector xExchange
xExchUMService xExchange
xExchWaitForDAG xExchange
xExchWaitForMailboxDatabase xExchange
xExchWebServicesVirtualDirectory xExchange

 

If you look in the DSCResources folder, you will see all the same xExchange resources that were listed in the Get-DscResource output:

PS C:\> Get-ChildItem 'C:\Program Files\WindowsPowerShell\Modules\xExchange\DSCResources'

    Directory: C:\Program Files\WindowsPowerShell\Modules\xExchange\DSCResources

Mode LastWriteTime Length Name
---- ------------- ------ ----
d---- 10/3/2014 10:18 AM MSFT_xExchActiveSyncVirtualDirectory
d---- 10/3/2014 10:18 AM MSFT_xExchAutodiscoverVirtualDirectory
d---- 10/3/2014 10:18 AM MSFT_xExchAutoMountPoint
d---- 10/3/2014 10:18 AM MSFT_xExchClientAccessServer
d---- 10/3/2014 10:18 AM MSFT_xExchDatabaseAvailabilityGroup
d---- 10/3/2014 10:18 AM MSFT_xExchDatabaseAvailabilityGroupMember
d---- 10/3/2014 10:18 AM MSFT_xExchDatabaseAvailabilityGroupNetwork
d---- 10/3/2014 10:18 AM MSFT_xExchEcpVirtualDirectory
d---- 10/3/2014 10:18 AM MSFT_xExchExchangeCertificate
d---- 10/3/2014 10:18 AM MSFT_xExchExchangeServer
d---- 10/3/2014 10:18 AM MSFT_xExchImapSettings
d---- 10/3/2014 10:18 AM MSFT_xExchMailboxDatabase
d---- 10/3/2014 10:18 AM MSFT_xExchMailboxDatabaseCopy
d---- 10/3/2014 10:18 AM MSFT_xExchMapiVirtualDirectory
d---- 10/3/2014 10:18 AM MSFT_xExchOabVirtualDirectory
d---- 10/3/2014 10:18 AM MSFT_xExchOutlookAnywhere
d---- 10/3/2014 10:18 AM MSFT_xExchOwaVirtualDirectory
d---- 10/3/2014 10:18 AM MSFT_xExchPopSettings
d---- 10/3/2014 10:18 AM MSFT_xExchPowershellVirtualDirectory
d---- 10/3/2014 10:18 AM MSFT_xExchReceiveConnector
d---- 10/3/2014 10:18 AM MSFT_xExchUMService
d---- 10/3/2014 10:18 AM MSFT_xExchWaitForDAG
d---- 10/3/2014 10:18 AM MSFT_xExchWaitForMailboxDatabase
d---- 10/3/2014 10:18 AM MSFT_xExchWebServicesVirtualDirectory

 

The Examples folder contains a handful of sample configuration scripts that show how to use various xExchange resources:

PS C:\> Get-ChildItem 'C:\Program Files\WindowsPowerShell\Modules\xExchange\Examples'

    Directory: C:\Program Files\WindowsPowerShell\Modules\xExchange\Examples

Mode LastWriteTime Length Name
---- ------------- ------ ----
d---- 10/10/2014 12:02 PM ConfigureAutoMountPoint-FromCalculator
d---- 10/10/2014 12:02 PM ConfigureAutoMountPoints-Manual
d---- 10/10/2014 12:02 PM ConfigureDatabases-FromCalculator
d---- 10/10/2014 12:02 PM ConfigureDatabases-Manual
d---- 10/10/2014 12:02 PM ConfigureVirtualDirectories
d---- 10/10/2014 12:02 PM CreateAndConfigureDAG
d---- 10/10/2014 12:04 PM EndToEndExample
d---- 10/10/2014 12:02 PM HelperScripts
d---- 10/10/2014 12:02 PM QuickStartTemplate
d---- 10/10/2014 12:02 PM SimpleOneResourceExample

 

The Test folder contains the tests that were used to verify resource functionality during development of the module. There should be no need to use this if just writing configuration scripts, but this may be useful to others who are trying to write their own DSC modules or resources:

PS C:\> Get-ChildItem 'C:\Program Files\WindowsPowerShell\Modules\xExchange\Test'

    Directory: C:\Program Files\WindowsPowerShell\Modules\xExchange\Test

Mode LastWriteTime Length Name
---- ------------- ------ ----
-a--- 10/10/2014 10:12 AM 31091 Test-xExchange.ps1

 

Learning More about xExchange

In the next post in this series, I will talk about the included QuickStartTemplate. This consists of two files that contain common elements used in most xExchange configuraton scripts. In subsequent posts, I plan to cover at least the following topics:

  • Creating and configuring one or more Database Availability Groups

  • Configuring CAS settings for multiple Active Directory Sites

  • Using the CSVs that are generated by the Exchange Server Role Requirements Calculator to automatically build out mount points, databases and copies

  • Using xExchange with a DSC Pull Server

 

Resources

First, here's the link to download the xExchange module:

PowerShell Gallery | xExchange
https://www.powershellgallery.com/packages/xExchange/

 

Here’s a handful of resources that I found helpful when learning about DSC:

Get Started with Windows PowerShell Desired State Configuration
https://technet.microsoft.com/en-us/library/dn249918.aspx

Separating Configuration and Environment Data
https://technet.microsoft.com/en-us/library/dn249925.aspx

Desired State Configuration Blog Series – Part 1, Information about DSC
https://blogs.technet.com/b/privatecloud/archive/2014/04/25/desired-state-configuration-blog-series-part-1-learning-about-dsc.aspx

Want to secure credentials in Windows PowerShell Desired State Configuration?
https://blogs.msdn.com/b/powershell/archive/2014/01/31/want-to-secure-credentials-in-windows-powershell-desired-state-configuration.aspx