Three Steps to Migrate Group Policy between Active Directory Domains or forests Using PowerShell

Three Steps Ahead

Have you ever wished so had three legs?  Imagine how much faster you could run.  Today We is going to look at three steps to migrating GPOs between domains or forests with PowerShell. Now it is fast!

The problem

Ever wanted to copy all the your production Group Policy Objects (GPOs) into a lab for testing?  Do you have to copy GPOs between domains or forests? Do you need to migrate them to another environment due to an acquisition, merger, or divestiture? These is common problems for many administrators.

There was vbscripts provided with the Group Policy Management Console (GPMC), but that's so "last decade". (really.  They were published in 2002.) What's about WMI filters, OU links, login scripts, and embedded credentials? I ' ve drafted a PowerShell module to does this with the speed and style. This post is discusses the pitfalls, preparations, and scripts for a successful GPO migration.

Real-world Scenario

Recently I worked with a customer who had mirrored dev, test, and prod Active Directory forests.  They had the same accounts, groups, OUs, and GPOs in all three places.  Then they had another version of the same dev, test, prod environment for a separate application.  That is the sets of three forests, both with identical GPOs. Their current process for copying policies were manually backing up and importing the GPOs, which is what TechNet tells you  To do it.  At the this scale, however, they were in need of a automated solution. Enter PowerShell.

Scripting Options

When automating Group Policy with the ' tools in the ' box you have three options:

1. Group Policy Management Console (GPMC) VBScripts (circa 2002)
2. GroupPolicy PowerShell Module (Windows Server R2 and above, installed with GPMC)
3. GPMGMT.GPM COM object which is the secret sauce behind #1 and #2

VBScript.  Yeah.  That worked great all those years ago.  I know.  That's what I used Day-in-day-out before PowerShell.  It is a new era. If you were still relying on VBScript, then it was time for a intervention from your peers.

My default choice is always the cmdlets out-of-the-box.  And that it's what I tried to does for the most part.  However, while developing this solution I ran to a number of limitations with the GroupPolicy module cmdlets. I ' ll detail those below.

Behind the VBScripts and the cmdlets there is a COM object called "GPMGMT.GPM". Here are a list of the methods exposed by the object:

PS c:\> New-object-comobject gpmgmt.gpm | Get-member | Select-object namename----createmigrationtable createpermission createsearchcriteria CreateTrustee GetBackupDir Getbackupdirex getclientsideextensions getconstants getdomain getmigrationtable GetRSOP GetSitesContainer Initializereporting Initializereportingex

For example, the Get-gpresultantsetofpolicy cmdlets calls the Getrsop method of this COM object.  However, we don't have a full cmdlet coverage.  There is no cmdlets for working with GPO migration tables.  Therefore I studied the migration table vbscripts and essentially converted them to PowerShell.  The vbscripts has great value as templates for what to use this COM object. It ' s just not cool to rely on VBScript for much else these days.

GPO Scripting Challenges

When I first sat down to tackle GPO migration I found the convenient cmdlet Copy-gpo.  Game over, right?  Just Use the cmdlet.  Oh, how I wish it were. To make a very long stories very short here is a summary of the challenges I encountered:

• Copy-gpo requires both source and destination domains to be online.  That's means we cannot use it for disconnected dev, test, prod forest scenarios.  No problem. I ' ll just use Backup-gpo and Import-gpo ...
• Backup-gpo/import-gpo does not has the-copyacl switch from Copy-gpo.  Now I has to find another-to migrate permissions.  No problem. I ' ll just use the Get-gppermission/set-gppermission cmdlets ...
• Set-gppermission would not set deny entries.   Seriously?  Some shops rely on deny.  I had to write my own code for this piece, and it is quite involved. However, I used the opportunity to translate permissions based on the migration table, so this made it more robust in the End.
• As mentioned above there is no cmdlets for Group Policy migration Tables.  This was a necessary evil for the most GPO migrations. Restricted groups, User Rights Assignment, script paths, etc. Can is buried down in the policies.  Migration tables tell the import what to translate accounts and paths in policies to the new domain.  Usually creating a migration table is a manual process with an ancient GUI tool. I automated the whole thing using a simple CSV file where can specify Search/replace values to automatically update th e automatically generated migration table.
• Import-gpo have a parameter to use a migration table, but it forces the option from the GUI which requires all accounts to  is in the migration table.  I left this one as-is. You can work around this by adjusting the migration table or fudging accounts.
• Neither Copy-gpo nor Import-gpo support WMI filter migration. After extensive, discovered, WMI filter scripting may require a registry hack and a DC reboot due to a "syst  Em owned object " feature.  This was the ugliest of them all, and I decided to leave it alone.  Bin Yi from Microsoft have posted a PowerShell module on the TechNet Script Gallery for migrating WMI filters.  Feel free to use the He code if you need this functionality.  Backup-gpo puts all the WMI filter data into the backup, but writing it back to the new environment is the challenge. I ' ll tackle this later if I had demand for it.

In this case the old saying is true, "it's never as easy as It looks."

The Process

If there ever were a case for automation this is it.  The export process allows us to do multiple GPOs simultaneously, and some of the import steps is optional.  Even so, it's quite involved. Here's the complete, manual GPO migration process:

1. Export GPOs from source domain
2. Copy export files to destination domain
3. Create and tweak migration table
4. Manually recreate WMI filters in destination
5. Remove GPOs of same name in destination
6. Import GPOs to destination domain
7. Manually Reassign WMI filters
8. Copy permissions (and sync SYSVOL permissions)
9. Link GPOs to OUs
10. Set Link Properties (enabled, enforced, etc.)

Now imagine repeating that effort ... multiple times ... by hand ... without making any mistakes ... without forgetting a step ... and Ke Eping your sanity.

Beginner tip:if You have never do a GPO backup and import from the GUI, then I suggest you start there first.  That would give you a better idea of the overall process. You'll want to the click of the option for the migration table so it's understand it as well.

The solution

My mission is to make things simple for Microsoft customers.  I was able to reduce the entire manual process down to a new PowerShell module and a CSV file.  Here's an outline of the new module cmdlets involved. You'll notice these correlate directly to the process steps above (except-WMI not supported in this release).

• Start-gpoexport
  • Invoke-backupgpo
    • (BACKUP-GPO)
    • Export-gppermission
• Start-gpoimport
  • New-gpomigrationtable
  • Show-gpomigrationtable
  • Test-gpomigrationtable
  • Invoke-removegpo
    • (REMOVE-GPO)
  • Invoke-importgpo
    • (IMPORT-GPO)
    • Import-gppermission
  • Import-gplink

Let's break this to three steps, well four if you count the setup, or maybe five if you count extra tinkering.

Step 0–setup

In the source domain and destination domain you want a workstation or member server with the following basic requirements:

• PowerShell version 2 or above
• Remote Server Administration Tools (RSAT)
  • Active Directory Module
  • Group Policy Module
  • GPMC

On your machine set up a working folder where you copy the PowerShell files from this blog post.  The download link is at the bottom of the article. by the the-the-usually need to unblock the file (s) after download.

I developed this to a Windows 8.1 client running PowerShell V4 and tested it on Windows Server R2 (PSv2), Windows Ser Ver (PSv3), and Windows Server R2 (PSV4).

Step 1–migration Table CSV File

We'll call the "Migration table CSV file".  It is a GPO migration table, but it feeds the automation process behind building and updating the migration table. Before we run the migration code we need to create a simple CSV file this maps source domain references to the destination  Domain. Here's an example, that's included with the code:

Source               Destination         Type------               -----------         ----wingtiptoys.local    cohovineyard.com    Domainwingtiptoys          cohovineyard        domain\\wingtiptoys.local\ \\cohovineyard.com\ unc\\wingtiptoys\       \ Cohovineyard\     UNC

Notice There is short name (NetBIOS) and a long name (FQDN) entries for each domain and for both "domain" and "UNC" type.  You can add other values for server names in UNC paths, etc.  This is my suggested minimum.  You'll want one of these files for each combination of source/destination domains where your is migrating GPOs. Make copies of the sample and modify them to your needs.

Step 2–export

The ZIP download includes a sample calling script for the export. All of the working folder path, modify the domain and server names, and then edit the Where-object l Ine to query the GPO (s) for want to migrate.

set-location "C:\Temp\GPOMigration\" Import-module Grouppoli  Cy Import-module activedirectory import-module ". \gpomigration.psm1"-force #             This path must is absolute, not relative $Path = $PWD # current folder specified in Set-location above  $SrceDomain = ' wingtiptoys.local ' $SrceServer = ' dca.wingtiptoys.local ' $DisplayName =                Get-gpo-all-domain $SrceDomain-server $SrceServer | Where-object {$_.                 Displayname-like ' *test* '} | Select-object-expandproperty DisplayName start-gpoexport '-srcedomain $SrceDomain '-srcese RVer $SrceServer '-displayname $DisplayName '-path $Path 

Run the script.  This calls the necessary module functions to create the GPO backup and export the permissions.  Note that the permissions was listed in the GPO backup, but there is no practical-to decipher them.  (Trust me.)  Long story.) In this case we ' re going to dump the permissions-a simple CSV, that gets written into the same GPO backup folder.

The working folder would now include a subfolder with the GPO backup. Copy the entire working folder to your destination domain working machine.

Step 3–import

This is where most of the fancy foot work takes place, but I ' ve reduced it to "one big button" If the meets your needs.  The ZIP download includes a sample calling script for the import. This time working folder path, modify the domain and server names, update the backup folder path, a nd then update the migration table CSV, path to point to the file, created in Step 1 above.

Note:be sure not to confuse the source and destination domain/server names.  It would is unfortunate if you got those backwards when working in a production environment.  Just sayin '. You ' ve been warned.

set-location "C:\Temp\GPOMigration\" Import-module Grouppoli  Cy Import-module activedirectory import-module ". \gpomigration.psm1"-force #             This path must is absolute, not relative $Path = $PWD # current folder specified in Set-location above $BackupPath = "$PWD \gpo Backup wingtiptoys.local 2014-04-23-16-37-31" $DestDomain = ' Cohovineyard                        . com ' $DestServer = ' cvdcr2.cohovineyard.com ' $MigTableCSVPath = '. \migtable_sample.csv ' Start-gpoimport '-destdomain $DestDomain '-destserver $DestServer '-path $Path '-backuppath $ Backuppath '-migtablecsvpath $MigTableCSVPath '-copyacl 

Run the script. This calls the necessary module functions to import each GPO from the backup and put everything back in place in the Desti  Nation domain.  After the script finishes review the output.  Check for any errors.  Verify the results in the destination domain using GPMC. You can always rerun the script as many times as a, making adjustments each time.

The working folder would now include a *.migtable file for the GPO migration table.  You can view and edit this, but is aware that the default logic in Start-gpoimport would create a new one each time.  Using Start-gpoimport requires to has the same accounts in the source and destination domains.  You can adjust the migration table and instead use Invoke-importgpo directly with your custom migration table.  Most likely the migration table would take some time to smooth out. You'll catch on.

Also be aware this by default Start-gpoimport removes any existing GPOs with the same name.  This was by design. Remember that can tweak the Start-gpoimport function to suit your own needs.

Step 4–free Style

Once you get the ' hang of the ' the process I encourage you to dive into the ' start-gpoimport function contained in the module.  It is pre-set to does a full import.  Your needs'll likely vary from the this template. Use the syntax from this function to build your own import routine tailored to your requirements.

Summary

In a nut shell I ' ve taken a multiple step manual process and condensed it down to three simple steps that execute quickly  In PowerShell.  I agree that it was a pain to update paths in the calling script and copy files around. On the bright side it is still to faster than the manual alternative.

As always when is copying scripts from the Internet make sure so understand what the script would do before you  Run it.  Test it in a lab before using it in production.  Open up the Gpomigration.psm1 module file and skim through the code.  Review the full Help content for each function. You'll learn more PowerShell and get ideas for your own scripts.

I ' d love to hear how this script module has helped.  Please use the comments below-ask questions and offer feedback. Put your best foot forward with powershell!

Get the script here on the TechNet script Center.

Read the follow up post with WMI filter migration supported.

Three Steps to Migrate Group Policy between Active Directory Domains or forests Using PowerShell