Mike Hendrickson https://docs.microsoft.com/archive/blogs/mhendric/feed.xml Tue, 16 Apr 2019 06:28:07 GMT en-US hourly 1 Mike Hendrickson's Scripts and Tools https://docs.microsoft.com/archive/blogs/mhendric/mike-hendricksons-scripts-and-tools Fri, 03 Mar 2017 16:42:00 GMT https://blogs.technet.microsoft.com/mhendric/?p=685

The following is a list of scripts and tools that Mike Hendrickson has created or collaborated on.


General Windows Server Scripts and Tools

Get-FilteredLogContent.ps1

https://gallery.technet.microsoft.com/Get-FilteredLogContentps1-2513eae4
Used to filter out log entries from one or more file paths on one or more target computers.

Get-PerfmonSummaryStats.ps1

https://gallery.technet.microsoft.com/Get-PerfmonSummaryStatsps1-73b096e5
Used to gather summary statistics of performance counter data from one or more performance monitor .blg files, on one or more computers.Summary statistics for each counter include: Average, Maximum, Minimum, Sum, and Count. Groups and averages related counters into per file, per computer, and all computer groups.


Exchange Server Specific Scripts and Tools

Add-TransportDatabaseMountPoint.ps1

https://gallery.technet.microsoft.com/Add-TransportDatabaseMountP-f0e559e6
Creates a mount point for the Exchange Transport database, and assigns appropriate permissions for the Exchange Transport Service.

Get-ClientsFromRPCClientAccessLogs.ps1

https://gallery.technet.microsoft.com/Get-ClientsFromRPCClientAcc-a62c845a
Parses the RPC Client Access logs of one or more Exchange 2010+ servers looking for a specific client operation type, and exports the found results to .CSV. Performs the search of each target computer in parallel. The target computers perform their log search locally, and then return the results to the machine Where-Object the script is executed from. This approach conserves memory on the script computer, and significantly speeds up the collection time.

Get-ExchangeDatabaseUsage.ps1

https://gallery.technet.microsoft.com/Get-ExchangeDatabaseUsageps-61cec9ad
Gathers usage and consumption statistics on Exchange Database and Mailbox Usage. Statistics focus on categories like mailbox counts, mailbox quotas, mailbox sizes, and database sizes. Each time the script is run, the following information is written to disk: Per Database statistics. Per Mailbox statistics. A database heat map, showing which databases are over or under provisioned. A mailbox move map, showing the required mailbox moves to reduce database heat.

Get-MailboxSizeInventory.ps1

https://gallery.technet.microsoft.com/Get-MailboxSizeInventoryps1-119560bc
Gets an inventory of the sizes of all mailboxes in an Exchange 2010/2013/2016 environment, and saves the results to .CSV.

Get-RemoteExchangeSession.ps1

https://gallery.technet.microsoft.com/Get-RemoteExchangeSessionps-ec575a12
Used to establish a Remote PowerShell session to Exchange with the same capabilities as Exchange Management Shell. Exchange Management tools must be installed on the machine using this module.

GetTransactionLogStats.ps1

https://gallery.technet.microsoft.com/office/GetTransactionLogStatsps1-3b530ac3
Used to collect and analyze Exchange transaction log generation statistics. Designed to be run as an hourly scheduled task, on the top of each hour. Can be run against one or more servers and databases.

HighItemFolders.ps1

https://gallery.technet.microsoft.com/scriptcenter/42fc40d2-46a8-4e48-b15c-f0ad23357739
A script that can analyze folders on all versions, and determine if they were over their limit. It can be used against the entire organization, a single server, or a single database.

xExchange Module for PowerShell Desired State Configuration (Collaboration)

https://github.com/PowerShell/xExchange
https://www.powershellgallery.com/packages/xExchange/
The xExchange module contains many DSC resources for configuring and managing Exchange 2013 and 2016 servers including individual server properties, databases, mount points, and Database Availability Groups.

]]> Quickly Finding Trends in Large Volumes of Performance Monitor Log Files https://docs.microsoft.com/archive/blogs/mhendric/quickly-finding-trends-in-large-volumes-of-performance-monitor-log-files Thu, 17 Nov 2016 23:05:16 GMT https://blogs.technet.microsoft.com/mhendric/?p=555

I’ve spent a lot of time recently trying to troubleshoot performance problems with the System drives in a 100+ Exchange Server 2013/2016 environment. As a result of a number of different factors, the System drives started failing much earlier than expected; about a year into their service life. This manifested itself in various ways, including very slow OS performance, disk failures for one or both disks in the mirror, and file and file system corruption. Once disks started to fail, some servers would get to a point where they would be unable to boot again after a reboot. Others seemed to operate fine, but would fail with corruption type errors when trying to apply Exchange Cumulative Updates, or other Hotfixes.

As a way to identify which servers were good and which had disks that were bad or failing, one approach I decided to take was using Performance Monitor, and looking at the Average and Maximum values for Disk read latency, write latency, and queuing. Specifically, I wanted to look at the "Avg. Disk Sec/Read", "Avg. Disk Sec/Write", and "Avg. Disk Queue Length" counters for LogicalDisk.

The biggest problem with doing this analysis was how to efficiently find problem counters in hundreds of PerfMon logs on hundreds of Exchange Servers, while being cognizant of the time that it took to process all those files, and the system resources (CPU, Memory, Network) used in the process. To solve this, I wrote a new PowerShell script, Get-PerfMonSummaryStats.ps1.

Get-PerfMonSummaryStats.ps1

Get-PerfMonSummaryStats.ps1 is designed to look at one or more counters in one or more Performance Monitor .blg files spread across one or more computers. With each counter that is found, the range of sample values for that counter will be measured to obtain the Average, Maximum, Minimum, and Sum of values. These values can be used to quickly identify trends in large amounts of Performance Monitor .blg files, and determine which files may warrant further investigation.

The script can be run both locally or remotely, but is designed primarily to be run remotely against many machines at once. When run Remotely, each target machine is responsible for inspecting specified counters in one or more PerfMon files, and summarizing the results. Instead of sending back the raw counter data for all the counters that are found, only summaries are sent back to the machine where the script was executed. This greatly reduces the network requirements for doing a remote PerfMon analysis.

The output of the script is a variable which contains three members: CounterSummaries, ComputerSummaries, and FileSummaries. These variables are used to store groupings of counter measurements at the counter level, computer level, and file level:

  • CounterSummaries: These contain groupings of all discovered measurements for each unique counter path. Each counter will only be listed once in this output.

  • ComputerSummaries: These contain groupings of the counter measurements taken from all files on each computer. For each computer, a counter will only be displayed one time.

  • FileSummaries: These are the counter measurements found in individual files for each computer. Similar counters will be displayed once for each counter in each file they were discovered in.

Examples

The following examples show how to analyze perfmon files, and manipulate the output variable from the script. To start with, I’m going to do a local log analysis against 29 perfmon files located in the D:\PerfLogs directory. These files were originally retrieved from two different Exchange Servers. I’m specifically asking for all LogicalDisk counters for all disks to be analyzed.

PS> $stats = .\Get-PerfmonSummaryStats.ps1 -Path D:\PerfLogs\ -Counter "\\*\LogicalDisk(*)\*" -Verbose


Next I’ll show the contents of the output variable. Note the CounterSummaries, ComputerSummaries, and FileSummaries members.

PS> $stats | fl

Here’s what the CounterSummaries member looks like. Note that no computers or files are listed in this output. These are the merged measurements for every counter found in every file on every computer.

PS> $stats.CounterSummaries | ft

Here’s what the ComputerSummaries member looks like. Notice that each counter shows up twice, once for each computer:

PS> $stats.ComputerSummaries | ft

Here’s what the FileSummaries look like. Notice that the same counter shows up many times, corresponding to each time they were found in a file.

PS> $stats.FileSummaries | ft

If I want to get a list of the unique counter paths found in the analysis, I can run:

PS> $stats.CounterSummaries.CounterPath

To look at specific counters, I can filter on CounterPath. In this example, I’m going to use wildcards to get Avg. Disk sec/Read and Avg. Disk sec/Write counters for all disks. I’m also sorting by the Maximum value:

PS> $stats.CounterSummaries | Where-Object {$_.CounterPath -like "*avg. disk sec*"} | Sort-Object -Property Maximum -Descending | ft

Avg. Disk Sec/Read for the C: drive jumps to the top of the list. Let’s get the files that have that counter, and sort by Maximum:

PS> $stats.FileSummaries | Where-Object {$_.CounterPath -like "\logicaldisk(c:)\avg. disk sec/read"} | Sort-Object -Property Maximum -Descending | ft

To get just the first file, I can use Select-Object:

PS> $stats.FileSummaries | Where-Object {$_.CounterPath -like "\logicaldisk(c:)\avg. disk sec/read"} | Sort-Object -Property Maximum -Descending | Select-Object -First 1

Alternately, if I just wanted to see which computer had the highest value, I can do the same thing in ComputerSummaries:

PS> $stats.ComputerSummaries | Where-Object {$_.CounterPath -like "\logicaldisk(c:)\avg. disk sec/read"} | Sort-Object -Property Maximum -Descending | Select-Object -First 1

Now I’m going to move onto a new analysis on the same files. This time I’m going to look at all Memory and Processor counters.

PS> $stats = .\Get-PerfmonSummaryStats.ps1 -Path D:\PerfLogs\ -Counter "\\*\Memory\*","\\*\Processor(*)\*" -Verbose

Here’s the counter paths discovered in the new analysis.

PS> $stats.CounterSummaries.CounterPath

Here’s how to get the total processor time spent on all computers, and sort by Maximum.

PS> $stats.ComputerSummaries | Where-Object {$_.CounterPath -like "\processor(_total)\% processor time"} | Sort-Object Maximum -Descending

Now I’ll grab the file that contained the highest value.

PS> $stats.FileSummaries | Where-Object {$_.CounterPath -like "\processor(_total)\% processor time"} | Sort-Object Average -Descending | Select-Object -First 1

Conclusion

I’ve found this script to save a lot of time, and make the job a lot easier when working with large amounts of performance monitor files. Hopefully you will find this useful as well.

]]> Moving the Exchange Transport Database to a Mount Point https://docs.microsoft.com/archive/blogs/mhendric/moving-the-exchange-transport-database-to-a-mount-point Tue, 11 Oct 2016 21:15:03 GMT https://blogs.technet.microsoft.com/mhendric/?p=215

This is my first blog post in quite some time. I have a number of PowerShell scripts and tools that I’ve developed over the past year which I’ve been meaning to share. Starting with this script, I’m going to start posting them on my personal GitHub repository, and blogging about them here on my TechNet blog.

DISCLAIMER

The process and script described in this post is not officially supported by Microsoft. I have tested the procedure to work with Exchange 2013 and 2016, and have afterwards tested upgrading to Exchange 2013 CU14 and Exchange 2016 CU3 after applying these changes. While this script should work without issue, I highly recommend testing it yourself before introducing into a production environment.

Overview

I recently came across an issue with one of my customers where the Operating System drive on their Exchange 2013 servers had too much load on it, in part because the Exchange Transport Database was located in the default location on the Operating System drive. This issue was identified by consistently high values for both read latency (Avg. Disk sec/read), as well as disk queueing (Avg. Disk Queue Length).

To try to reduce some of the load on the Operating System drive, we decided to move the Transport Database to a new, dedicated disk. After consulting TechNet, we came across the following article on how to accomplish this:

Change the location of the queue database
https://technet.microsoft.com/en-us/library/bb125177(v=exchg.150).aspx

While reviewing the instructions, we noticed the following disclaimer:

Any customized per-server settings you make in Exchange XML application configuration files, for example, web.config files on Client Access servers or the EdgeTransport.exe.config file on Mailbox servers, will be overwritten when you install an Exchange Cumulative Update (CU). Make sure that you save this information so you can easily re-configure your server after the install. You must re-configure these settings after you install an Exchange CU.

Essentially what this says is that any time a Cumulative Update is applied, you would lose the changes made in the Transport config file, and as such, would have to remember to update the Transport config.

As a way to avoid having to change the Transport Database path after each Cumulative Update, we came up with the idea of using a Mount Point, which would be located at the default Transport Database location of ‘C:\Program Files\Microsoft\Exchange Server\V15\TransportRoles\data\Queue’. That way we could move the Transport Database to a different disk, but as far as Exchange is concerned, it would still be at the default location. This would prevent us from having to do any changes to the Transport config file.

Automating Setup of the Transport Database Mount Point

Script Location: Add-TransportDatabaseMountPoint.ps1

After reviewing and testing the steps required to setup this Mount Point, I decided to write a PowerShell script to accomplish the task, as the customer in question had over 100 servers that needed to be modified.

The script takes the following actions:

  • Creates a new partition on a specified disk number.

  • Removes permissions that don't need to be on the Mount Point folder, or Mount Point itself.

  • Adds required permissions to the Mount Point folder and Mount Point. Specifically, it gives Full Control permissions to SYSTEM, NETWORK SERVICE, and Local Administrators.

  • Stops the Microsoft Exchange Transport service, and the Microsoft Exchange Health Manager service (to prevent it from starting the Transport service back up).

  • Moves any existing Transport database files to a temporary location.

  • Adds a Mount Point to the new partition.

  • Moves the existing Transport database files to the Mount Point.

  • Starts the Microsoft Exchange Transport service, and the Microsoft Exchange Health Manager service.

  • Pre-creates the ‘System Volume Information’ folder underneath the Mount Point if it doesn’t already exist.

  • Gives SYSTEM, NETWORK SERVICE, and BUILTIN\Administrators permissions to the System Volume Information folder underneath the Mount Point.

The script will only take action if required. If nothing has been configured for the Mount Point yet, the script output will look as follows:

If the script has already been successfully run, output will be minimal:

Lessons Learned

I hit a couple issues while trying to figure out how to correctly put the Transport Database within a Mount Point that are worth noting.

Lesson 1: Set permissions on the folder AND the Mount Point

The first issue that I encountered while trying to create this script was where to set appropriate permissions. By looking at the existing Queue folder, I knew that SYSTEM, NETWORK SERVICE, and BUILTIN\Administrators were supposed to have Full Control on the folder. In my first attempt, I added these permissions to the new Queue folder after a Mount Point was added. After doing so, the Transport Service failed to start. In research, I found that not only do you have to add permissions to the Mount Point folder, but you also have to add permissions to the volume itself.

Below is what the Security looks like on the properties of the ‘C:\Program Files\Microsoft\Exchange Server\V15\TransportRoles\data\Queue’ folder after setting up the Mount Point:

If you go to the General tab, you can click on Properties to get to properties of the Mount Point itself:

This will take you to the General properties of the Mount Point:

If you go to Security here, you can set permissions on the Mount Point itself:

Lesson 2: Cumulative Updates need permissions to the System Volume Information folder

The other major issue I encountered was in regards to applying Cumulative Updates. When testing in my lab, I used the script to setup the new Mount Point, made sure the services started just fine, and then tried to do a Cumulative Update. I did this with both Exchange 2013 and 2016, and the CU’s for both succeeded. We then used this script to move the Transport database to a new location on an entire DAG in my customer’s environment. A week later, they tried to apply the latest Cumulative Update for Exchange 2016, which failed in the ‘Mailbox Role: Mailbox service’ step with error:

Microsoft.Exchange.Management.Deployment.ExsetdataException: An error occurred with error code '3221684229' and message 'Access is denied.'.

Here's a screenshot of the error within Setup:

After doing some research, I found that this could occur if the account running setup does not have permissions to the hidden ‘System Volume Information’ folder within the root of a volume, which only SYSTEM has access to by default. The reason my testing did not catch this is because this folder is not created until after a reboot. The script was adjusted to pre-create the folder, which will cause it to inherit the permissions that were already set on the Mount Point and volume. If the folder already exists, it will check that appropriate permissions are present.

To check if the System Volume Information folder exists or has the right permissions, first go to Folder Options, and verify that 'Show hidden files, folders, and drives' is checked, and 'Hide protected operating system files' is unchecked.

After setting these Folder Options, you should see the System Volume Information folder in the Queue, as well as $RECYCLE.BIN.

Go to properties of System Volume Information to set the appropriate security.

]]> Deploying and Configuring Exchange 2013 Using DSC - An End to End Example https://docs.microsoft.com/archive/blogs/mhendric/deploying-and-configuring-exchange-2013-using-dsc-an-end-to-end-example Wed, 13 May 2015 15:07:00 GMT https://blogs.technet.microsoft.com/mhendric/2015/05/13/deploying-and-configuring-exchange-2013-using-dsc-an-end-to-end-example/

Just last week, I had the privilege of presenting at Microsoft Ignite 2015. The topic of my presentation was how to deploy and configure Exchange 2013 using DSC. Specifically, I talked about how to perform the Exchange specific phases of an end to end Exchange deployment, including automating Jetstress, installing Exchange, and performing server, DAG, database, and mount point configuration. I also talked about some lessons learned while using DSC to deploy and configure Exchange in a large scale environment for one of my customers.

If you are interested in checking out this presentation, the recording and slide deck is available here:

Automating Microsoft Exchange Server 2013 Configuration with PowerShell Desired State Configuration
https://channel9.msdn.com/events/ignite/2015/BRK3150

The demo scripts I used are attached to the slide deck, which is available in the above link. You can also download the demo files directly here:

BRK3150-Demo-Files.zip

Hope you find this useful!

]]> Installing Exchange Using DSC - Managing Exchange 2013 With DSC - Part 5 https://docs.microsoft.com/archive/blogs/mhendric/installing-exchange-using-dsc-managing-exchange-2013-with-dsc-part-5 Thu, 18 Dec 2014 06:48:00 GMT https://blogs.technet.microsoft.com/mhendric/2014/12/18/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:

]]> Listen To Us Talk About xExchange https://docs.microsoft.com/archive/blogs/mhendric/listen-to-us-talk-about-xexchange Wed, 03 Dec 2014 07:30:30 GMT https://blogs.technet.microsoft.com/mhendric/2014/12/03/listen-to-us-talk-about-xexchange/

Along with Jason Walker, a PFE at Microsoft and co-developer of xExchange, I was recently a guest on the PowerScripting Podcast. We were invited on to talk about the xExchange module, and using it to configure Exchange Server 2013. The topics covered should be interesting to both DSC Resource developers, as well as DSC consumers. We cover the development process that we went through to create the initial 20+ resources. We then talk about how the majority of xExchange resources map to existing Exchange Server cmdlets, and how they should be easy to understand and consume for those familiar with the Exchange Management Shell. If this sounds interesting to you, you can download the podcast from the following site:

Episode 289 – PowerScripting Podcast – Mike Hendrickson and Jason Walker from Microsoft on Configuring Exchange With DSC
https://powershell.org/wp/2014/11/30/episode-289-powerscripting-podcast-mike-hendrickson-and-jason-walker-from-microsoft-on-configuring-exchange-with-dsc/

Thanks!

]]> Using a DSC Pull Server to Deploy the xExchange Module - Managing Exchange 2013 With DSC - Part 4 https://docs.microsoft.com/archive/blogs/mhendric/using-a-dsc-pull-server-to-deploy-the-xexchange-module-managing-exchange-2013-with-dsc-part-4 Mon, 10 Nov 2014 08:55:00 GMT https://blogs.technet.microsoft.com/mhendric/2014/11/10/using-a-dsc-pull-server-to-deploy-the-xexchange-module-managing-exchange-2013-with-dsc-part-4/

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

 

Using a DSC Pull Server to Deploy the xExchange Module

For this post, I’m going to cover how to deploy a configuration utilizing the xExchange module via a DSC pull server. The steps I will be covering are mostly based on the below article. I will just be expanding on concepts that I thought needed a little more explanation, and talking about portions that may be different when working with Exchange.

Windows PowerShell Desired State Configuration Pull Servers
https://technet.microsoft.com/en-us/library/dn249913.aspx

 

Test Servers

I will be referencing two different test servers in this blog post. I will show how to execute all the steps directly on the pull server, as I expect most people would rather configure their Exchange servers remotely from a central location than from multiple locations. The two test servers are:

  • DSCPULL-1: A Windows Server 2012 machine which will be setup as a DSC pull server

  • E15-1: An Exchange 2013 server

Note that most of the documentation on pull servers that I've found covers setting them up on Windows Server 2012 R2. I’m going to demonstrate setting one up on Windows Server 2012, as I hit some issues trying to get it to work that are worth sharing (these issues have been reported, and will be fixed soon).

 

Sample Scripts

The scripts that are used in the examples in this post are included in PullServerScripts.zip. I will be extracting the contents of the zip to C:\DSCScripts on my pull server, DSCPULL-1, but they could go in any location.

 

Pull Server Prerequisites

The following components will need to be installed or downloaded onto the DSC pull server:

 

Installing Pull Server Prerequisites

Windows Management Framework 4

Installing WMF 4 is pretty straightforward. All you need to do is download the package for the appropriate version of Windows, and double click it to start the installation.

 

Internet Information Services

The TechNet article on DSC pull servers does mention that IIS is a prerequisite, but doesn’t state specifically which components need to be installed. That being the case, I tried, and was successful, at just choosing the defaults options for IIS.

Using the Add Roles and Features Wizard, you first want to check the ‘Web Server (IIS)’ role:

 

When prompted, choose that you want to include management tools:

 

You shouldn’t need to add any additional Role Services underneath Web Server. These are the default options that were selected for me:


 

xPSDesiredStateConfiguration

After extracting the zip file for xPSDesiredStateConfiguration, copy the xPSDesiredStateConfiguration folder to ‘C:\Program Files\WindowsPowerShell\Modules’:

 

One thing worth mentioning is that for the copy of xPSDesiredStateConfiguration I downloaded (v3.0.2.0), all the folders and files were Read Only by default. If you plan on modifying any of the sample scripts, you may want to uncheck Read Only at the root folder:

 

xExchange (Optional)

On my pull server, I chose to copy the extracted xExchange module to the ‘C:\Program Files\WindowsPowerShell\Modules’ directory as well. This isn’t a requirement, but will make it easier to write xExchange based configuration scripts directly on the pull server, as the Powershell ISE will be able to recognize the Exchange resources. After copying over the xExchange module, I now have two modules in the Modules directory:

 

Windows Update (Optional)

After installing all of the above features and components, I highly recommend running Windows Update to make sure the server is completely up to date.

 

Preparing a Certificate

Now that the pull server prerequisites have been installed, the next thing that needs to be done is to obtain a certificate. The certificate will be used for two things:

  1. Securing communications between the DSC pull server and target computers

  2. Encrypting credentials that will be passed to xExchange resources.

 If you wanted, you could use two separate certificates for this, but I’m going to just use a single certificate for both.

 

Requesting the Certificate

There’s a ton of different ways out there to get a certificate, so I’m just going to cover an easy to use method which I already have setup in my lab. In the lab, I have one of my Domain Controllers configured with Active Directory Certificate Services, and installed as an Enterprise Root CA. With this setup, I can easily request a certicate using the Certificates snap-in in the mmc and sending the request directly to my CA.

On DSCPULL-1, I’m going to open up mmc, go to 'Add/Remove Snap-in', and choose the Certificates snap-in:

 

After hitting add, it asks what object the snap-in will manage certificates for. The certificate needs to be stored in the Personal store of the Local Computer, so I’m going to choose ‘Computer account’:

 

Next I'll choose ‘Local computer’:

 

Once the snap-in is opened, the first thing I want to do is request a certificate. To do this, I will right click on the Personal store, choose ‘All Tasks’, and ‘Request New Certificate’:

 

I only have a single Certificate Enrollment Policy, so I can hit Next again:

 

Now I need to choose the certificate type that I'd like to request. I’ve experimented with using both a Computer or a Workstation certificate for DSC, and both work. Since the Computer template is available with a default CA installation, I will choose Computer.

Before hitting Enroll, I need to expand Details, and go to Properties on the certificate so I can complete some extra fields:

 

Within the certificate properties, the first thing I’m going to do is go to the Subject tab, and add in a Common name of PSDSCPullServer. This matches the EndpointName we will use later in Sample_xDscWebServices.ps1, the the script to setup IIS to host a DSC pull server:

 

On the Private Key tab, I’m going to check the box to make the private key exportable, as we’ll need to export a copy of the Private Key and import it in the Personal store of each target computer that will be configured.

After checking this box, I’m going to hit OK to close out the Properties, and then Enroll to request the certificate:

 

After hitting Enroll, I now see the requested certificate in the Personal store:

 

Exporting the Private and Public Key

Now I’m going to export the certificate twice, once with just the Public key, and once with the Private key. The Public key export will be used by the DSC pull server to encrypt credentials. The Private key will be imported in each target node, and will be used to decrypt credentials when configurations are applied.

 

Exporting the Private Key

First I’m going to export the Private key. To do this, I right click on the certificate, go to All Tasks, and choose Export:

 

Next I'll choose 'Yes, export the private key':

 

In the Export options, I’m going to choose to ‘Include all certificates in the certificate path if possible’, and ‘Export all extended properties’:

 

Since this is a Private key export, I have to specify a means to secure the export file. I’m going to use a Password:

 

Now I’ll specify the name and location of the export file, c:\privatekey.pfx, and hit Next, then Finish:

 

Exporting the Public Key

Now we need to export the Public key. The initial steps to perform the export are the same as exporting a Private key. When I get to this screen, I want to choose to 'not export the private key':

 

I’ll choose to DER encode the .CER file:

 

For the export location, I’m going to choose c:\publickey.cer, then hit Next and Finish:

 

I now have two certificate exports:

 

Making Note of the Certificate Thumbprint

The final thing I need to do within the Certificates snap-in is make note of the certificate’s thumbprint. To do this, I’m going to go to properties of the certificate. On the Details tab, scroll down to the Thumbprint property:

 

IMPORTANT: It is important to note that you probably don’t want to copy/paste the Thumbprint directly out of certificate properties. Doing so copies some additional Unicode characters which will break your DSC configuration scripts. Instead I recommend opening notepad separately and just manually typing in the Thumbprint as you see it. For more information, see the very end of this post.

 

Remotely Importing the Private Key on Target Computers

Now that I have a certificate, I need to import the private key on each target computer, which in this case is just E15-1. There are a variety of methods to do this, so I'm going to choose a method that allows me to initiate a remote import from a central location.

The following commands are included in the example script, RemotelyImportCert.ps1.What this script does is copy the private key export over to E15-1, then remotely execute Import-PfxCertificate on E15-1. The password being requested is the password that was specified during the private key export:

copy c:\privatekey.pfx \\e15-1\c$
$password = Read-Host -AsSecureString
Invoke-Command -ComputerName e15-1  -ArgumentList $password -ScriptBlock `
    {Import-PfxCertificate -CertStoreLocation Cert:\LocalMachine\My -FilePath C:\privatekey.pfx -Password $args[0]}

 

Creating the Pull Server

Now that the I have all the prerequisites ready, it's time to setup the pull server. To do this I'm going to modify an example config script that ships with xPSDesiredStateConfiguration, Sample_xDscWebServices.ps1, which should be located in the module within the 'xPSDesiredStateConfiguration\Examples' folder. I'm going to copy the file to 'C:\DSCScripts'.

 

Sample_xDscWebServices.ps1 (Modified)

configuration Sample_xDscWebService
{
    param 
    (
        [string[]]$NodeName = 'localhost',

        [ValidateNotNullOrEmpty()]
        [string] $certificateThumbPrint
    )

    Import-DSCResource -ModuleName xPSDesiredStateConfiguration

    Node $NodeName
    {
        WindowsFeature DSCServiceFeature
        {
            Ensure = "Present"
            Name   = "DSC-Service"            
        }

        xDscWebService PSDSCPullServer
        {
            Ensure                  = "Present"
            EndpointName            = "PSDSCPullServer"
            Port                    = 8080
            PhysicalPath            = "$env:SystemDrive\inetpub\wwwroot\PSDSCPullServer"
            CertificateThumbPrint   = $certificateThumbPrint         
            ModulePath              = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Modules"
            ConfigurationPath       = "$env:PROGRAMFILES\WindowsPowerShell\DscService\Configuration"            
            State                   = "Started"
            DependsOn               = "[WindowsFeature]DSCServiceFeature"                        
        }

        xDscWebService PSDSCComplianceServer
        {
            Ensure                  = "Present"
            EndpointName            = "PSDSCComplianceServer"
            Port                    = 9080
            PhysicalPath            = "$env:SystemDrive\inetpub\wwwroot\PSDSCComplianceServer"
            CertificateThumbPrint   = "AllowUnencryptedTraffic"
            State                   = "Started"
            IsComplianceServer      = $true
            DependsOn               = @("[WindowsFeature]DSCServiceFeature","[xDSCWebService]PSDSCPullServer")
        }
    }
}

Sample_xDscWebService -certificateThumbPrint c9586647cc93a3fac8791ded121bc68a03c7fa87
Start-DscConfiguration -Verbose -Wait -Path .\Sample_xDscWebService -ComputerName "localhost"

 

I only made two changes to Sample_xDscWebServices.ps1, which was adding the two lines at the end of the script:

  • The first line compiles the script, and passes in the thumbprint of the certificate that was created earlier

  • The second line executes the configuration, and configures IIS for use as a pull server

 

After successfully executing the script, I see the following output:


 

WINDOWS 2012 ONLY

EDIT (12/18/14): This issue was resolved in version 3.0.3.0 of xPSDesiredStateConfiguration. If you run into this issue, make sure to download the latest version of the module.

Here's the one place that I had to diverge from the TechNet instructions to get the pull server to work with Windows 2012. Note that this issue has been reported as a bug, and should be fixed in the next release of xPSDesiredStateConfiguration. I found the solution to this by following this stackoverflow post.

Essentially the problem is that the xDscWebService resource which is included in xPSDesiredStateConfiguration (v3.0.2.0) registers a database provider that is only available in Windows 2012 R2. To fix this, we need to edit the web.config file which is located in 'C:\inetpub\wwwroot\PSDSCPullServer' (the PhysicalPath property in Sample_xDscWebServices.ps1):

 

Open the web.config file in Notepad. Find the following lines:

<add key="dbprovider" value="ESENT" />
<add key="dbconnectionstr" value="C:\Program Files\WindowsPowerShell\DscService\Devices.edb" />

 

Replace them with:

<add key="dbprovider" value="System.Data.OleDb" />
<add key="dbconnectionstr" value="Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Program Files\WindowsPowerShell\DscService\Devices.mdb;"/>

 

Finally, you'll need to restart the server, or at a minimum restart IIS for the changes to take effect.

 

Preparing the xExchange Module for Deployment

Now I need to prepare the xExchange module for deployment to target nodes. Without doing this step, the target nodes will not have a local copy of xExchange to work with when they try to execute their configuration.

To set this up, I'm going to copy the downloaded xExchange module to the path specified in ModulePath in Sample_xDscWebServices.ps1. This is 'C:\Program Files\WindowsPowerShell\DscServices\Modules'. Instead of putting the extracted module in this folder though, we're going to drop the zip file exactly as it was downloaded from TechNet. Essentially it needs to be in the format MODULENAME_#.#.#.#.zip, where #.#.#.# is the module version.

Here's a couple screenshots that show what it should look like:

 

Now I need to generate a checksum file for all modules (which for me is just xExchange) in 'C:\Program Files\WindowsPowerShell\DscServices\Modules'. To do this, I'm going to run the following command:

New-DscCheckSum -ConfigurationPath "C:\Program Files\WindowsPowerShell\DscServices\Modules" `
    -OutPath "C:\Program Files\WindowsPowerShell\DscServices\Modules" -Verbose -Force

 

After doing this, a checksum file shows up in the same Modules folder:

 

Preparing Configuration Scripts for Target Servers

Generating a Unique GUID for Each Target Server

Before we can setup a configuration script, we must first generate a unique GUID for each target server. This GUID will be used to name the target MOF file for each computer, and also when configuring the Local Configuration Manager on the target node to tell it which configuration to retrieve.

For every server that will be configured, we'll want to run the following command to generate a GUID:

[Guid]::NewGuid().ToString()

 

The output will look similar to the following. Make sure to save the GUID somewhere for later use.

3f5452c9-aa68-4494-b94d-70f4c92b28a7

 

Setting Up the Exchange Configuration Script

The next configuration script we need to setup is the script that will be used for configuring Exchange. For this, I am going to start with the QuickStartTemplate described in this post. The example is located in the xExchange\Examples\QuickStartTemplate folder of the xExchange module.

To avoid confusion, I'm going to copy the two template files to a new location, and rename them. The original files are QuickStartTemplate.ps1 and QuickStartTemplate-Config.psd1. I'm going to copy these to C:\DSCScripts, and rename them to ConfigureExchange.ps1 and ConfigureExchange-Config.psd1.

 

Renamed but otherwise unmodified, the two configuration files look as follows:

 

ConfigureExchange.ps1 (Unmodified)

Configuration QuickStartTemplate
{
    param
    (
        [PSCredential]$ShellCreds
    )

    Import-DscResource -Module xExchange

    Node $AllNodes.NodeName
    {
        #Used when passing credentials securely. This configures the thumbprint of the 
        #cert that will be used to decrypt the creds
        LocalConfigurationManager
        {
            CertificateId = $Node.Thumbprint
        }
    }
}

#Get credentials if they haven't already been passed
if ($ShellCreds -eq $null)
{
    $ShellCreds = Get-Credential -Message 'Enter credentials for establishing Remote Powershell sessions to Exchange'
}

###Compiles the example
QuickStartTemplate -ConfigurationData $PSScriptRoot\QuickStartTemplate-Config.psd1 -ShellCreds $ShellCreds

 

ConfigureExchange-Config.psd1 (Unmodified)

@{
    AllNodes = @(
        #Settings under 'NodeName = *' apply to all nodes.
        @{
            NodeName        = '*'

            #CertificateFile and Thumbprint are used for securing credentials. See:
            #https://blogs.msdn.com/b/powershell/archive/2014/01/31/want-to-secure-credentials-in-windows-powershell-desired-state-configuration.aspx
            
            #The location on the compiling machine of the public key export of the certfificate which will be used to encrypt credentials
            CertificateFile = 'C:\publickey.cer' 

            #Thumbprint of the certificate being used for encrypting credentials
            Thumbprint      = '39bef4b2e82599233154465323ebf96a12b60673' 
        }

        #Individual target nodes are defined next
        @{
            NodeName = 'e15-1'
        }

        @{
            NodeName = 'e15-2'
        }
    );
}

 

Now I'll make the following modifications:

 

ConfigureExchange.ps1 (Modified)

Configuration ConfigureExchange
{
    param
    (
        [PSCredential]$ShellCreds
    )

    Import-DscResource -Module xExchange

    Node $AllNodes.NodeName
    {
        xExchOutlookAnywhere OAVdir
        {
            Identity                           = "$($Node.NodeName)\Rpc (Default Web Site)"
            Credential                         = $ShellCreds
            ExternalClientAuthenticationMethod = 'Ntlm'
            ExternalClientsRequireSSL          = $true
            ExternalHostName                   = 'mail.mikelab.local'
            IISAuthenticationMethods           = 'Ntlm'
            InternalClientAuthenticationMethod = 'Ntlm'
            InternalClientsRequireSSL          = $true
            InternalHostName                   = 'mail-site1.mikelab.local'
            AllowServiceRestart                = $true
        }
    }
}

#Get credentials if they haven't already been passed
if ($ShellCreds -eq $null)
{
    $ShellCreds = Get-Credential -Message 'Enter credentials for establishing Remote Powershell sessions to Exchange'
}

###Compiles the example
ConfigureExchange -ConfigurationData $PSScriptRoot\ConfigureExchange-Config.psd1 -ShellCreds $ShellCreds

 

For ConfigureExchange.ps1, I made a few changes:

  • I replaced all instances of QuickStartTemplate with ConfigureExchange

  • I removed the LocalConfigurationManager section, as we will be configuring the LCM at a later point in a separate script

  • I added an xExchOutlookAnywhere resource (which I copied from the ConfigureVirtualDirectories example in xExchange)

 

ConfigureExchange-Config.psd1 (Modified)

@{
    AllNodes = @(
        #Settings in this section will apply to all nodes.
        @{
            NodeName        = '*'

            #CertificateFile and Thumbprint are used for securing credentials. See:
            #https://blogs.msdn.com/b/powershell/archive/2014/01/31/want-to-secure-credentials-in-windows-powershell-desired-state-configuration.aspx
            
            #The location on the compiling machine of the public key export of the certfificate which will be used to encrypt credentials
            CertificateFile = 'C:\publickey.cer'

            #The thumbprint of the Encryption Certificate used to decrypt the credentials
            #on target node
            Thumbprint      = 'c9586647cc93a3fac8791ded121bc68a03c7fa87' 
        }

        #Individual target nodes are defined next
        @{
            NodeName = 'e15-1'
            NodeGuid = '3f5452c9-aa68-4494-b94d-70f4c92b28a7'
        }
    );
}

 

Here are the changes made for ConfigureExchange-Config.psd1:

  • I removed node E15-2, as I am only configuring a single server in this example

  • I updated Thumbprint to contain the thumbprint of the certificate that was generated earlier

  • I added a NodeGuid property to E15-1's section, and specified the GUID that was generated for the server earlier

 

Compiling the Script, and Moving and Renaming the Target .MOF

The next step is to compile the script, move the target computer's .MOF to the proper location for pulling, and rename it using the GUID that was generated earlier.

Note that the computer that is compiling the script MUST be compiling it with the same version of xExchange that was dropped into and checksummed in the 'C:\Program Files\WindowsPowerShell\DscServices\Modules' folder. If not, you may get a Desired State Configuration error with Event ID 4104 on the target machine when it tries to download the configuration. To look for this or any other DSC errors within Event Viewer on the target machine, go to 'Applications and Service Logs\Microsoft\Windows\Desired State Configuration', then choose the Operational log.

In the below error, I had compiled the script using v1.0.2.1 of the xExchange module, but had zipped and checksummed v1.0.0.0 of the module in the DscServices\Modules folder.

 

Compiling the Script

I can compile the script by running ConfigureExchange.ps1. Doing so, I get a file named e15-1.mof:

 

Renaming the .MOF

Now I'm going to rename e15-1.mof to 3f5452c9-aa68-4494-b94d-70f4c92b28a7.mof (the GUID generated for E15-1), and copy the file to 'C:\Program Files\WindowsPowerShell\DscService\Configuration' (the path specified in ConfigurationPath when the pull server was setup).

 

Checksumming the .MOF

Finally, I'm going to run New-DSCCheckSum to generate a checksum for all configurations in the Configuration folder:

New-DscCheckSum -ConfigurationPath "C:\Program Files\WindowsPowerShell\DscServices\Configuration" `
    -OutPath "C:\Program Files\WindowsPowerShell\DscServices\Configuration" -Verbose -Force

 

At this point, the Configuration folder should look as follows:

 

Setting Up the 'Local Configuration Manager' Configuration Script

The last step in the process is to tell the target node to start pulling the configuration. To do this, we need to configure the Local Configuration Manager on the target node. To get started, I'm going to copy the SimpleMetaConfigurationForPull script which is included in this article. I'm going to save the contents into a new file, ConfigureTargetLCMs.ps1.

Unmodified, ConfigureTargetLCMs.ps1 looks as follows:

 

ConfigureTargetLCMs.ps1 (Unmodified)

Configuration SimpleMetaConfigurationForPull 
{ 
    LocalConfigurationManager 
    { 
        ConfigurationID = "1C707B86-EF8E-4C29-B7C1-34DA2190AE24";
        RefreshMode = "PULL";
        DownloadManagerName = "WebDownloadManager";
        RebootNodeIfNeeded = $true;
        RefreshFrequencyMins = 15;
        ConfigurationModeFrequencyMins = 30; 
        ConfigurationMode = "ApplyAndAutoCorrect";
        DownloadManagerCustomData = 
            @{ServerUrl = "https://PullServer:8080/PSDSCPullServer/PSDSCPullServer.svc";
              AllowUnsecureConnection = “TRUE”}
    }
}
SimpleMetaConfigurationForPull -Output "."

 

Now I'll make the following modifications:

 

ConfigureTargetLCMs.ps1 (Modified)

Configuration ConfigureTargetLCMs 
{
    Node $AllNodes.NodeName
    {
        LocalConfigurationManager 
        {
            CertificateId                  = $Node.Thumbprint
            ConfigurationID                = $Node.NodeGuid;
            RefreshMode                    = "PULL";
            DownloadManagerName            = "WebDownloadManager";
            RebootNodeIfNeeded             = $true;
            RefreshFrequencyMins           = 15;
            ConfigurationModeFrequencyMins = 30; 
            ConfigurationMode              = "ApplyAndAutoCorrect";
            DownloadManagerCustomData      = @{
                ServerUrl               = "https://dscpull-1.mikelab.local:8080/PSDSCPullServer.svc";
                AllowUnsecureConnection = “TRUE”}

            ### Note that the URL used to be configured differently, and contained an additional subfolder in the path
            ### prior to v3.0.3.4 of xPSDesiredStateConfiguration. This was the old style.
            #DownloadManagerCustomData      = @{
            #    ServerUrl               = "https://dscpull-1.mikelab.local:8080/PSDSCPullServer/PSDSCPullServer.svc";
            #    AllowUnsecureConnection = “TRUE”}
        }
    }
}

ConfigureTargetLCMs -ConfigurationData $PSScriptRoot\ConfigureExchange-Config.psd1

 

Here's the specific changes I made:

  • I renamed all instances of SimpleMetaConfigurationForPull to ConfigureTargetLCMs

  • Moved the LocalConfigurationManager section into a Node block, so that the script can be used for multiple nodes

  • Added a CertificateId property, and specify that it will use $Node.Thumbprint from ConfigureExchange-Config.psd1

  • Changed ConfigurationID to use $Node.NodeGuid from ConfigureExchange-Config.psd1

  • Changed the ServerUrl to use https, and also to include the FQDN of the pull server, dscpull-1

  • Updated the compile line to include a ConfigurationData file; the same ConfigureExchange-Config.psd1 file we created earlier

  • Removed the PSDSCPullServer subfolder from ServerUrl. Version 3.0.3.4 and higher of xPSDesiredStateConfiguration no longer setup the pull server with this subfolder.

 

Compiling, Executing and Verifying the 'Local Configuration Manager' Script

Now that everything is in place, all I have left to do is compile and execute the LCM configuration script, ConfigureTargetLCMs.ps1.

 

Compiling the Script

I can compile the script by just running it. Note that this time I get a .meta.mof file instead of a plain .mof file, as I am configuring the Local Configuration Manager:

 

Executing the Configuration

To execute the configuration, I'll run:

Set-DscLocalConfigurationManager -Path .\ConfigureTargetLCMs -Verbose

 

Verifying the Configuration

To confirm that the configuration was successful, I can look in the Event Viewer of the target computer. The following event, Desired Sate Configuration, Event ID 4160, indicates that the configuration was successful, and the machine will attempt to pull it's configuration after a reboot:

 

After the reboot, you can again go into the Event Viewer of the target computer to check if the configuation was pulled and applied. If everything runs successfully, you will just see a single error, a Desired State Configuration event, with Event ID 4194. This error is ignorable. DSC wants to delete the existing configuration for the computer, but since this is the first iteration, it has no configuration to delete:

 

In addition to 20 or 30 other Informational events, you will see events 4108 and 4109 indicating that required modules, and required configuration, was downloaded successfully from the pull server. If you don't see these, there will most likely be more than one Error or Warning in the recent Event Viewer.

]]> Automating Mount Point Setup and Maintenance for AutoReseed - Managing Exchange 2013 With DSC - Part 3 https://docs.microsoft.com/archive/blogs/mhendric/automating-mount-point-setup-and-maintenance-for-autoreseed-managing-exchange-2013-with-dsc-part-3 Mon, 27 Oct 2014 15:32:00 GMT https://blogs.technet.microsoft.com/mhendric/2014/10/27/automating-mount-point-setup-and-maintenance-for-autoreseed-managing-exchange-2013-with-dsc-part-3/

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

 

Automating Mount Point Setup and Maintenance for AutoReseed

xExchAutoMountPoint is a resource within the xExchange module that was designed specifically to be used with AutoReseed, a feature introduced in Exchange 2013. Setting up AutoReseed requires that you create a relatively complex mount point structure, where volumes for databases and spare volumes will be mounted. Database mount points go under C:\ExchangeDatabases, and spare volumes go under C:\ExchangeVolumes. On larger servers with 4 databases copies per disk, you could easily end up with over 100 mount points per server.

The Exchange Server Role Requirements Calculator already has the capability of generating CSV’s defining the required databases and copies per server, and can also generate PowerShell scripts for creating mount points, databases, and database copies using those CSV's. If all you want to do is configure the server once and forget it, those scripts are more than sufficient for the job.

Seeing as how these scripts already existed, a big driver for creating the xExchAutoMountPoint resource was to deal with what happens after a failed disk is replaced. Right now the (simplified) AutoReseed process for a fully configured and operational server is as follows:

  • Server has a disk failure

  • AutoReseed detects the failed disk, remaps a spare volume as a database volume, and initiates a reseed from a known good copy

  • Administrator pulls the failed disk, and replaces it with a good disk

  • Administrator assigns the new disk a mount point in C:\ExchangeVolumes

  • Administrator formats the volume

  • (OPTIONAL) Administrator applies Bitlocker to volume

 

With xExchAutoMountPoint (and optionally the xBitlocker module and xBLAutoBitlocker resource), the last three steps can be completely automated. Note that this requires that the configuration is setup in pull mode, where the configuration is regularly inspected for differences. Using these resources with pull mode, the new workflow would be as follows:

  • Server has a disk failure

  • AutoReseed detects the failed disk, remaps a spare volume as a database volume, and initiates a reseed from a known good copy

  • Administrator pulls the failed disk, and replaces it with a good disk

  • xExchAutoMountPoint determines that the number of active ExchangeVolumes mount points is less than the required number of mount points, and that there is an available disk with no assigned mount points

  • xExchAutoMountPoint assigns an ExchangeVolumes mount point to the new disk, and formats it

  • (OPTIONAL) xBLAutoBitlocker determines that there is a Fixed data disk online that has a mount point assigned, but is not Bitlocker'ed, and applies Bitlocker

 

So essentially, all the administrator has to do is pull the failed disk, and replace it with a new disk. xExchAutoMountPoint and xBLAutoBitlocker take care of the work that is required to get the new disk ready for AutoReseed.

 

When to Run xExchAutoMountPoint?

Before jumping into examples, I wanted to quickly comment on when you should run xExchAutoMountPoint. Depending on the pre-validation you do on your servers, you may actually want to run xExchAutoMountPoint in two different scripts.

Many administrators like to run Jetstress against their database volumes prior to installing Exchange so that they can burn in their disks, and verify disk performance. If you are one of these administrators, you may want to run a script with xExchAutoMountPoint by itself prior to installing Exchange. That way you can create your mount point structure for Jetstress. After Jetstress has been run and Exchange is installed, if you are going to implement the rest of your Exchange configuration in pull mode, you could add the xExchAutoMountPoint resource in that configuration script as well. That way you can have mount points recreated automatically after disk failures.

 

Example 1 - Manually Specifying Database and Disk Structure for AutoReseed

For this first example, I will show how to manually feed database information into the xExchAutoMountPoint resource. I will be working with 2 servers, and 4 total databases. Both servers will have 2 disks for databases, where each disk has 2 database copies per disk. The servers will also have a third disk to use as a spare.

The following graphic shows what this example looks like. Each folder in the graphic is a mount point that will be assigned to the specified volume. Remember that even though the disks have multiple mount points, each mount point on a single disk shows the same physical disk contents.

 

Now I will show the configuration scripts which implement this design. Both scripts are included in the xExchange\Examples\ConfigureAutoMountPoints-Manual folder of the xExchange module.

ConfigureAutoMountPoints-Manual.ps1

Configuration ConfigureAutoMountPointsManual
{
    Import-DscResource -Module xExchange

    Node $AllNodes.NodeName
    {
        xExchAutoMountPoint AMP
        {
            Identity                       = $Node.NodeName
            AutoDagDatabasesRootFolderPath = 'C:\ExchangeDatabases'
            AutoDagVolumesRootFolderPath   = 'C:\ExchangeVolumes'
            DiskToDBMap                    = $Node.DiskToDBMap
            SpareVolumeCount               = 1
            VolumePrefix                   = 'EXVOL'
        }
    }
}

Note the following:

  • I hardcoded AutoDagDatabasesRootFolderPath and AutoDagVolumesRootFolderPath within the config script, as these would be the same regardless of how many servers and databases I was configuring. When working with DSC in general, if a setting is going to be the same for every single machine being configured, I'll hardcode it directly in the configuration script. If the settings are not going to be the same for each target machine, I'll probably abstract them to the configuration data file.

  • Even though both servers in this example have copies of the exact same databases, I specify what the DiskToDBMap should look like in the configuration data file instead of hard coding it in the script. In larger DAG's, it is likely that each server will have copies of different databases, and as such will require different mount point structures. It makes more sense to put the DiskToDBMap in the configuration data file, where you can specify a different map per server.

  • I specify a SpareVolumeCount of 1, as I plan on having 1 spare disk for AutoReseed.

  • I specify a VolumePrefix of EXVOL. This does two things. First, when volumes are created, they will be assigned a volume label of EXVOL#, where # increments depending on the number of total disks being used for AutoReseed. Second, it specifies that ExchangeVolume mount points will be created under C:\ExchangeVolumes\EXVOL#. Note that EXVOL is the default value for VolumePrefix, so I could actually omit VolumePrefix altogether in this example.

 

ConfigureAutoMountPoints-Manual-Config.psd1

@{
    AllNodes = @(
        @{
            NodeName    = 'e15-1'
            DiskToDBMap = 'DB1,DB2','DB3,DB4'
        }

        @{
            NodeName    = 'e15-2'
            DiskToDBMap = 'DB1,DB2','DB3,DB4'
        }
    );
}

The main thing to note here is the format for DiskToDBMap. The expected input here is a string array (string[]), where each string in the array contains a comma separated list of DB mount points that should be created on a single disk. For both nodes in this example, DB1 and DB2 will be placed on one disk, and DB3 and DB4 will be placed on another.

 

The Exchange Server Role Requirements Calculator and Servers.csv

Manually filling out the DiskToDBMap is easy enough in small environments, but can quickly become unwieldy in larger DAGs. I figured that out pretty fast once I started trying to fill out the map for my customer who has over 200 databases per DAG, and over 80 copies per server. To make this easier, I wrote a helper script which is included in the xExchange module, and is located at xExchange\Examples\HelperScripts\ExchangeConfigHelper.psm1. The function that we will use, DBMapFromServersCsv, takes the Servers.csv file that is generated by the calculator, and turns the relevant disk information into a DiskToDBMap.

 

The Sample Topology

For the topology, I'm using a copy of the Exchange Server Role Requirements Calculator which defines the following:

  • 1 DAG

  • 4 servers

  • 10 data disks + 1 spare per server

  • 40 database copies per server

  • 4 database copies per disk

 

An important thing to note in the calculator is the server names that were put into the Input tab. The server names I use are in the format SRV-nn-##, where nn is the DAG identifier, and ## is the node identifier. As an example, the first server in the first DAG would be SRV-01-01.

In this example, I'm just configuring servers in a single DAG, but in real life, you may be configuring multiple DAGs. Since the calculator will only generate CSV files for a single DAG, we need a way to be able to reuse the same CSV files for multiple DAGs which share a similar structure. To do this, I put a placeholder for the DAG number in the server name. This way, even if I'm configuring SRV-01-01, SRV-02-01, or SRV-03-01, they can all use the same definition for SRV-nn-01.

 

On the Input tab, right next to the server names, I also define the database prefix. Here, I again use -nn- instead of a specific DAG number so that the same Servers.csv file can be used for multiple DAGs.

 

Generating Servers.csv

With the calculator configured, we need to generate the Servers.csv file which will be fed into the configuration script. To do this, go to the Distribution tab, and hit the Export DB Mount List button.

 

After hitting the button, the following window comes up. For xExchAutoMountPoint, the only thing we care about is the Export Path, where Servers.csv will be created. The other properties are configured directly in the configuration script and don't need to be pulled from Servers.csv.

 

After hitting OK, you'll get the following confirmation showing where Servers.csv was sent to:

 

Here's a screenshot of what the Servers.csv file looks like. The two columns that are consumed by the helper function, DBMapFromServersCsv, are ServerName and DbMap:

 

Using the Helper Module

To demonstrate what the helper function does, I wrote a simple test script which shows it's output. For demo purposes, I put ExchangeConfigHelper.psm1, Servers.csv, and TestHelper.ps1 all in the same folder:

 

TestHelper.ps1 looks as follows:

Import-Module .\ExchangeConfigHelper.psm1

$dbMap = DBMapFromServersCsv `
    -ServersCsvPath "Servers.csv" `
    -ServerNameInCsv "SRV-nn-01" `
    -DbNameReplacements @{"-nn-" = "-01-"}
    
$dbMap

 

The important points of this script are as follows:

  • I have to import the ExchangeConfigHelper.psm1 module, as that is where the DBMapFromServersCsv function lives

  • ServersCsvPath is the path to the Servers.csv file on the machine which will be compiling the configuration. If no folder path is specified, it will use the current directory

  • I pass in SRV-nn-01 for ServerNameInCsv, as that will be the ServerName in Servers.csv that the DbMap property will be processed for

  • For DbNameReplacements, I pass in a hashtable, where the key '-nn-' is what should be replaced, and the value '-01-' is what it should be replaced with. If you want to make multiple replacements, you can seperate the key value pairs with a semicolon. Note that due to the way a hashtable operates, the replacements will be processed in a (seemingly) random order, and not necessarily the order you put them in. As such you may need to carefully plan out what multiple replacements look like so they do not interfere with each other.

 

After running the test script, we can see what the $dbMap variable looks like. Each line in the output is a separate string in a string array:

DAG-01-DB01,DAG-01-DB02,DAG-01-DB03,DAG-01-DB04
DAG-01-DB05,DAG-01-DB06,DAG-01-DB07,DAG-01-DB08
DAG-01-DB09,DAG-01-DB10,DAG-01-DB11,DAG-01-DB12
DAG-01-DB13,DAG-01-DB14,DAG-01-DB15,DAG-01-DB16
DAG-01-DB17,DAG-01-DB18,DAG-01-DB19,DAG-01-DB20
DAG-01-DB21,DAG-01-DB22,DAG-01-DB23,DAG-01-DB24
DAG-01-DB25,DAG-01-DB26,DAG-01-DB27,DAG-01-DB28
DAG-01-DB29,DAG-01-DB30,DAG-01-DB31,DAG-01-DB32
DAG-01-DB33,DAG-01-DB34,DAG-01-DB35,DAG-01-DB36
DAG-01-DB37,DAG-01-DB38,DAG-01-DB39,DAG-01-DB40

 

This is equivalent to if I had manually typed the following in the configuration data file (although everything would be on a single line; you can't define an array across multiple lines like I do here):

DiskToDBMap = 'DAG-01-DB01,DAG-01-DB02,DAG-01-DB03,DAG-01-DB04',`
                'DAG-01-DB05,DAG-01-DB06,DAG-01-DB07,DAG-01-DB08',`
                'DAG-01-DB09,DAG-01-DB10,DAG-01-DB11,DAG-01-DB12',`
                'DAG-01-DB13,DAG-01-DB14,DAG-01-DB15,DAG-01-DB16',`
                'DAG-01-DB17,DAG-01-DB18,DAG-01-DB19,DAG-01-DB20',`
                'DAG-01-DB21,DAG-01-DB22,DAG-01-DB23,DAG-01-DB24',`
                'DAG-01-DB25,DAG-01-DB26,DAG-01-DB27,DAG-01-DB28',`
                'DAG-01-DB29,DAG-01-DB30,DAG-01-DB31,DAG-01-DB32',`
                'DAG-01-DB33,DAG-01-DB34,DAG-01-DB35,DAG-01-DB36',`
                'DAG-01-DB37,DAG-01-DB38,DAG-01-DB39,DAG-01-DB40'

 

Example 2 - Using Servers.csv as Input for xExchAutoMountPoint

Now that we know how to generate a Servers.csv file, and also how to work with the DBMapFromServersCsv helper function, we can look at the next demo scripts. These show how to use Servers.csv to populate the DiskToDBMap. Both scripts are included in the xExchange\Examples\ConfigureAutoMountPoints-FromCalculator folder of the xExchange module.

 

ConfigureAutoMountPoints-FromCalculator.ps1

Configuration ConfigureAutoMountPointsFromCalculator
{
    Import-DscResource -Module xExchange

    Import-Module "$((Get-Item -LiteralPath "$($PSScriptRoot)").Parent.FullName)\HelperScripts\ExchangeConfigHelper.psm1"

    Node $AllNodes.NodeName
    {
        $dagSettings = $ConfigurationData[$Node.DAGId]
        
        $dbMap = DBMapFromServersCsv `
                    -ServersCsvPath "$($PSScriptRoot)\CalculatorAndScripts\Servers.csv" `
                    -ServerNameInCsv $Node.ServerNameInCsv `
                    -DbNameReplacements $dagSettings.DbNameReplacements

        xExchAutoMountPoint AMP
        {
            Identity                       = $Node.NodeName
            AutoDagDatabasesRootFolderPath = 'C:\ExchangeDatabases'
            AutoDagVolumesRootFolderPath   = 'C:\ExchangeVolumes'
            DiskToDBMap                    = $dbMap
            SpareVolumeCount               = 1
            VolumePrefix                   = 'EXVOL'
        }
    }
}

 

There are a few things worth noting here. First, since we're using the helper module, we have to import it. The location I have specified is relative to the location of the configuration script, ConfigureAutoMountPoints-FromCalculator.ps1, as it is located in the xExchange download.

Import-Module "$((Get-Item -LiteralPath "$($PSScriptRoot)").Parent.FullName)\HelperScripts\ExchangeConfigHelper.psm1"

 

Instead of using a relative location for the helper module, you could just as easily specify the exact location:

Import-Module "C:\HelperScripts\ExchangeConfigHelper.psm1"

 

The next line locates the DAG settings for the node being processed, and put's them in a variable for easy usage later:

$dagSettings = $ConfigurationData[$Node.DAGId]

 

Now I get the DBMap using the helper function, as I did earlier, and send it to the variable $dbMap. This time however, I pass in a variable for ServerNameInCsv and DbNameReplacements, so that the same script can be used to configure multiple nodes. Both of these variables are defined in the configuration data file.

$dbMap = DBMapFromServersCsv `
    -ServersCsvPath "$($PSScriptRoot)\CalculatorAndScripts\Servers.csv" `
    -ServerNameInCsv $Node.ServerNameInCsv `
    -DbNameReplacements $dagSettings.DbNameReplacements

 

The xExchAutoMountPoint resource looks almost the same as in the manual example. The only difference is for DiskToDBMap, we are passing in $dbMap, which was generated by the helper function.

xExchAutoMountPoint AMP
{
    Identity                       = $Node.NodeName
    AutoDagDatabasesRootFolderPath = 'C:\ExchangeDatabases'
    AutoDagVolumesRootFolderPath   = 'C:\ExchangeVolumes'
    DiskToDBMap                    = $dbMap
    SpareVolumeCount               = 1
    VolumePrefix                   = 'EXVOL'
}

 

ConfigureAutoMountPoints-FromCalculator-Config.psd1

@{
    AllNodes = @(
        @{
            NodeName        = 'SRV-01-01'
            ServerNameInCsv = 'SRV-nn-01'
            DAGId           = "DAG1"
        }

        @{
            NodeName        = 'SRV-01-02'
            ServerNameInCsv = 'SRV-nn-02'
            DAGId           = "DAG1"
        }
        @{
            NodeName        = 'SRV-01-03'
            ServerNameInCsv = 'SRV-nn-03'
            DAGId           = "DAG1"
        }

        @{
            NodeName        = 'SRV-01-04'
            ServerNameInCsv = 'SRV-nn-04'
            DAGId           = "DAG1"
        }        
    );
    
    DAG1 = @{
        DbNameReplacements = @{"-nn-" = "-01-"}
    }
}

 

There's a couple things of note in this configuration data file. First, this data file makes use of a new node in the hashtable which is a sibling of AllNodes. This node is named DAG1, and can be used to define properties that are specific to that DAG. In this example, the only thing defined in here is the replacements to make in the database names when taken out of Servers.csv.

DAG1 = @{
    DbNameReplacements = @{"-nn-" = "-01-"}
}

 

When looking up DAG settings for a node in the configuration script, the DAG1 node is referenced via the DAGId property in the node:

DAGId           = "DAG1"

 

Summary

In conclusion, the xExchAutoMountPoint resource can be used to automatically create the ExchangeDatabases and ExchangVolumes mount points that are required for AutoReseed. You can use it a single time during the initial setup of your Exchange servers to create your mount points, but you can also use it on a regular basis to set new disks back up automatically after failed disks are replaced. For smaller environments, you can fill out the disk and database information directly in your configuration scripts. For larger environments, it is probably a good idea to use Servers.csv from the Exchange Server Role Requirements Calculator as input.

 

Related Reading

AutoReseed: Exchange 2013 Help
https://technet.microsoft.com/en-us/library/dn789209(v=exchg.150).aspx

Configure AutoReseed for a database availability group
https://technet.microsoft.com/en-us/library/jj619303(v=exchg.150).aspx

]]> The QuickStart Template - Managing Exchange 2013 With DSC - Part 2 https://docs.microsoft.com/archive/blogs/mhendric/the-quickstart-template-managing-exchange-2013-with-dsc-part-2 Fri, 17 Oct 2014 09:48:00 GMT https://blogs.technet.microsoft.com/mhendric/2014/10/17/the-quickstart-template-managing-exchange-2013-with-dsc-part-2/ 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

 

The QuickStart Template

Most of the resources that are available in the xExchange module have similar requirements when used in a configuration script. Almost all the resources require that a PSCredential object is passed in, which contains the credentials of the account that will be used to establish a Remote Powershell session to Exchange. Microsoft recommends that when credentials are used within a DSC configuration script, they be encrypted and decrypted using a certificate. If this is not done, passwords will be stored in plain text in the compiled .MOF files for each target computer. For more information, see:

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

 

In addition to the full examples that are included with xExchange, I have created a template which contains common elements that will be used in most configuration scripts which utilize xExchange. This will hopefully make it easier to get started writing your own configuration scripts, or to understand the differences in components.

 

Template Files

The template contains two files, QuickStartTemplate.ps1, and QuickStartTemplate-Config.psd1. QuickStartTemplate.ps1 is the main configuration script, and what will be compiled into a .MOF file for DSC consumption. QuickStartTemplate-Config.psd1 contains configuration data and variables that are passed into, and utilized by QuickStartTemplate.ps1. The full files look as follows:

 

QuickStartTemplate.ps1 Full:

    Configuration QuickStartTemplate
    {
        param
        (
            [PSCredential]$ShellCreds
        )

        Import-DscResource -Module xExchange

        Node $AllNodes.NodeName
        {
            #Used when passing credentials securely. This configures the thumbprint of the 
            #cert that will be used to decrypt the creds
            LocalConfigurationManager
            {
                CertificateId = $Node.Thumbprint
            }
        }
    }

    #Get credentials if they haven't already been passed
    if ($ShellCreds -eq $null)
    {
        $ShellCreds = Get-Credential -Message 'Enter credentials for establishing Remote Powershell sessions to Exchange'
    }

    ###Compiles the example
    QuickStartTemplate -ConfigurationData $PSScriptRoot\QuickStartTemplate-Config.psd1 -ShellCreds $ShellCreds

 

QuickStartTemplate-Config.psd1 Full:

    @{
        AllNodes = @(
            #Settings in this section will apply to all nodes.
            @{
                NodeName        = '*'

                #The path to the .cer file containing the public key of the Encryption
                #Certificate used to encrypt credentials for this node

                CertificateFile = 'C:\publickey.cer'


                #The thumbprint of the Encryption Certificate used to decrypt the credentials
                #on target node
                Thumbprint      = '98e1858ee4da01e4fb9f0519bc60d9c30f33b1c6' 
            }

            #Each individual server that will be configured needs to be defined next.
            @{
                NodeName = 'e15-1'
            }

            @{
                NodeName = 'e15-2'
            }
        );
    }

 

To understand the basic DSC components of these, I recommend reading the following two Technet articles. The first article is useful for understanding the components in QuickStartTemplate.ps1, and how the config script is compiled into a MOF file. The second article helps to understand why it is a good idea to break some configuration into a separate section, which is what is done in QuickStartTemplate-Config.psd1, and how to do so.

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

 

Individual Components

Now I’ll break down the individual components of these that are not covered in the above articles.

 

QuickStartTemplate.ps1 Broken Down:

The first section within the Configuration block is the parameters section. In this template, as well as most of my example scripts, there is only a single parameter being passed, a PSCredential object, $ShellCreds. These are the credentials that will be used by the resources to establish a Remote Powershell session to Exchange. The account being used must have appropriate RBAC rights to the corresponding Exchange cmdlets used by the resource (for instance, to use xExchOwaVirtualDirectory, the account must have access to the Get/Set-OwaVirtualDirectory cmdlets). Note that even though xExchange uses Remote Powershell, the server being configured is just making a Remote Powershell session to itself.

    param
    (
        [PSCredential]$ShellCreds
    )

 

The next line in the script imports the xExchange module for use as a DSC resource. Without doing this, the script will fail to compile if any xExchange resources are used.

    Import-DscResource -Module xExchange

 

For the template, only a single DSC resource is used within the Node block, a LocalConfigurationManager resource. In all other samples, xExchange resources are used within the Node block, after the LocalConfigurationManager section.

The purpose of the LocalConfigurationManager resource within the template is to pass in the thumbprint of the certificate that the target node can use at run time to decrypt credentials.

$Node.Thumbprint comes from QuickStartTemplate-Config.psd1.

    LocalConfigurationManager
    {
        CertificateId = $Node.Thumbprint
    }

 

Outside of the Configuration block, the first block of code is used to prompt for and store credentials when the configuration script is executed. These will then be passed into the Configuration block as a parameter. The reason I check to see if credentials are null is so that if I’m troubleshooting or running the script multiple times for some reason, I only have to enter the credentials a single time.

    if ($ShellCreds -eq $null)
    {
        $ShellCreds = Get-Credential -Message 'Enter credentials for establishing Remote Powershell sessions to Exchange'
    }

 

QuickStartTemplate-Config.psd1 Broken Down:

Within the AllNodes node of the configuration data, the first section defines configuration that will be specific to … all nodes. That is specified by the NodeName = ‘*’. The first item that is defined in this section is, CertificateFile, the path to public key export of the certificate that will be used to encrypt credentials on the node compiling the MOFs. The next defined item is Thumbprint. This is the thumbprint of the certificate that was used to encrypt the credentials, and that will be used on target nodes to decrypt the credentials. This certificate will need to be imported, with private key, on each target node that will be configured.

If there were other things that were going to be common to all servers, like ProductKey, they could go in here. They could also just be hard coded in the configuration script. 

    @{
        NodeName        = '*'

        CertificateFile = 'C:\publickey.cer'

        Thumbprint      = '98e1858ee4da01e4fb9f0519bc60d9c30f33b1c6' 
    }

 

The next section defines the individual nodes that will have MOF files created for them when the configuration script is compiled. For the template, all that is specified here is the NodeName. In most other examples, computer specific information is put in these as well.

    @{
        NodeName = 'e15-1'
    }

    @{
        NodeName = 'e15-2'
    }

 

Adding an xExchange Resource

Now I am just going to add a single xExchange resource to the template, an xExchOwaVirtualDirectory resource. At this point, the configuration script is very close to the SimpleOneResourceExample that is also included with the module.

    Configuration QuickStartTemplate
    {
        param
        (
            [PSCredential]$ShellCreds
        )

        Import-DscResource -Module xExchange

        Node $AllNodes.NodeName
        {
            #Used when passing credentials securely. This configures the thumbprint of the 
            #cert that will be used to decrypt the creds
            LocalConfigurationManager
            {
                CertificateId = $Node.Thumbprint
            }
        
            xExchOwaVirtualDirectory OWAVdir
            {
                Identity                      = "$($Node.NodeName)\owa (Default Web Site)"
                Credential                    = $ShellCreds
                BasicAuthentication           = $false
                ExternalAuthenticationMethods = 'Ntlm','WindowsIntegrated'
                ExternalUrl                   = "https://mail-ext.mikelab.local/owa"
                FormsAuthentication           = $false
                InternalUrl                   = "https://mail-int.mikelab.local/owa"    
                WindowsAuthentication         = $true
                AllowServiceRestart           = $true
            }        
        }
    }

    #Get credentials if they haven't already been passed
    if ($ShellCreds -eq $null)
    {
        $ShellCreds = Get-Credential -Message 'Enter credentials for establishing Remote Powershell sessions to Exchange'
    }

    ###Compiles the example
    QuickStartTemplate -ConfigurationData $PSScriptRoot\QuickStartTemplate-Config.psd1 -ShellCreds $ShellCreds

 

Testing the Script

After updating the configuration script and data file with your own certificate information and computer information, the next step is to compile it. The very last line in the script is what initiates the compilation, so all you have to do is run the script. However you could just manually compile it with:

    QuickStartTemplate -ConfigurationData $PSScriptRoot\QuickStartTemplate-Config.psd1 -ShellCreds $ShellCreds

 

After it prompts for credentials, if everything ran successfully, you will see output like the following. There should be both a .mof, and a .meta.mof file for each node that is defined in QuickStartTemplate-Config.psd1. The .mof is what actually contains information about how to use the DSC resources. The .meta.mof file contains information required to decrypt the credentials.

PS C:\QuickStartTemplate> C:\QuickStartTemplate\QuickStartTemplate.ps1

    Directory: C:\QuickStartTemplate\QuickStartTemplate

Mode                LastWriteTime     Length Name
----                -------------     ------ ----
-a---        10/10/2014   1:54 PM       2936 e15-1.mof
-a---        10/10/2014   1:54 PM        848 e15-1.meta.mof
-a---        10/10/2014   1:54 PM       2936 e15-2.mof
-a---        10/10/2014   1:54 PM        848 e15-2.meta.mof

 

Next we need to configure the Local Configuration Manager on the target computers to be able to decrypt credentials using the specified certificate. This is done with the following command (in this case we are just doing a single computer, E15-1):

    Set-DscLocalConfigurationManager -Path .\QuickStartTemplate -Verbose -ComputerName "E15-1"

 

If it runs successfully, the output should look as follows:


Finally, we can execute the configuration in Push mode. Again, we’ll just work against a single computer. The command is:

    Start-DscConfiguration -Verbose -Wait -Path .\QuickStartTemplate -ComputerName "E15-1"

 

If it runs successfully, the output should look similar to the following:

 

Common Issues

Issue: Trying to apply the configuration fails with “The SendConfigurationApply function did not succeed”:


 

Cause: This can occur if you attempt to copy the Thumbprint of the certificate directly out of the properties window for the certificate. When you do this, it copies the thumbprint string in Unicode instead of ANSI.

This will not be noticeable in the Powershell ISE:


However, when you try to save the file, it will throw the following Warning:

If you open the file in notepad though, save it as type ANSI, and re-open the file in Notepad, you will see an extra ? listed before the thumbprint:

Solution: The easiest solution for this is to not copy and paste out of the certificate properties, and instead just manually type in the Thumbprint. If you still have issues, make sure that the file is saved in ANSI format using Notepad, and then check that you don’t have any hidden characters in the string.

 

]]> Introducing xExchange - Managing Exchange 2013 With DSC - Part 1 https://docs.microsoft.com/archive/blogs/mhendric/introducing-xexchange-managing-exchange-2013-with-dsc-part-1 Fri, 17 Oct 2014 09:47:00 GMT https://blogs.technet.microsoft.com/mhendric/2014/10/17/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

 

]]>