Have you ever wished that you had three legs? Imagine how much faster you could run. Today we are going to look at three steps to migrating GPOs between domains or forests with PowerShell. Now that is fast!
Have you ever wanted to copy all of 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 are common problems for many administrators.
There are Vbscripts provided with the Group Policy Management Console (GPMC), but that is so "last decade". (Really. They were published in 2002.) What about WMI filters, OU links, login scripts, and embedded credentials? I’ve drafted a PowerShell module to do this with speed and style. This post discusses the pitfalls, preparations, and scripts for a successful GPO migration.
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 two sets of three forests, both with identical GPOs. Their current process for copying policies was manually backing up and importing the GPOs, which is how TechNet tells you to do it. At this scale, however, they were in need of an automated solution. Enter PowerShell.
When automating Group Policy with the tools in the box you have three options:
Vbscript. Yeah. That worked great all those years ago. I know. That’s what I used day-in-day-out before PowerShell. But this is a new era. If you are still relying on Vbscript, then it is time for an intervention from your peers.
My default choice is always to use the cmdlets out-of-the-box. And that it what I tried to do for the most part. However, while developing this solution I ran into 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 is a list of the methods exposed by the object:
PS C:\> New-Object -ComObject GPMgmt.GPM | Get-Member | Select-Object Name Name ---- 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 do not have full cmdlet coverage. There are no cmdlets for working with GPO migration tables. Therefore I studied the migration table Vbscripts and essentially converted them to PowerShell. The Vbscripts have great value as templates for how to use this COM object. It’s just not cool to rely on Vbscript for much else these days.
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 that easy. To make a very long story very short here is a summary of the challenges I encountered:
As mentioned above there are no cmdlets for Group Policy Migration Tables. This is a necessary evil for most GPO migrations. Restricted groups, user rights assignment, script paths, etc. can be buried down in the policies. Migration tables tell the import how 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 you can specify search/replace values to automatically update the automatically generated migration table.In this case the old saying is true, “It is never as easy as it looks.”
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 are optional. Even so, it is quite involved. Here is the complete, manual GPO migration process:
Now imagine repeating that effort… multiple times… by hand… without making any mistakes… without forgetting a step… and keeping your sanity.
Beginner Tip: If you have never done a GPO backup and import from the GUI, then I suggest you start there first. That will give you a better idea of the overall process. You will want to click the option for the migration table so that you understand it as well.
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 is an outline of the new module cmdlets involved. You will notice these correlate directly to the process steps above (except for WMI not supported in this release).
Let‘s break this down into three steps, well four if you count the setup, or maybe five if you count extra tinkering.
In the source domain and destination domain you want a workstation or member server with the following basic requirements:
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 way, you will usually need to unblock the file(s) after download.
I developed this on a Windows 8.1 client running PowerShell v4 and tested it on Windows Server 2008 R2 (PSv2), Windows Server 2012 (PSv3), and Windows Server 2012 R2 (PSv4).
We will call this the “migration table CSV file”. It is not 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 that maps source domain references to the destination domain. Here is an example that is included with the code:
Source Destination Type ------ ----------- ---- wingtiptoys.local cohovineyard.com Domain wingtiptoys cohovineyard Domain \\wingtiptoys.local\ \\cohovineyard.com\ UNC \\wingtiptoys\ \\cohovineyard\ UNC
Notice there are short name (NetBIOS) and 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 will want one of these files for each combination of source/destination domains where you are migrating GPOs. Make copies of the sample and modify them to your needs.
The ZIP download includes a sample calling script for the export. All you have to do is update the working folder path, modify the domain and server names, and then edit the Where-Object line to query the GPO(s) you want to migrate.
Set-Location "C:\Temp\GPOMigration\"
Import-Module GroupPolicy
Import-Module ActiveDirectory
Import-Module ".\GPOMigration.psm1" -Force
# This path must be 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 `
-SrceServer $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 are listed in the GPO backup, but there is no practical way to decipher them. (Trust me. Long story.) In this case we’re going to dump the permissions to a simple CSV that gets written into the same GPO backup folder.
The working folder will now include a subfolder with the GPO backup. Copy the entire working folder to your destination domain working machine.
This is where most of the fancy foot work takes place, but I’ve reduced it to “one big button” if that meets your needs. The ZIP download includes a sample calling script for the import. This time you have to update the working folder path, modify the domain and server names, update the backup folder path, and then update the migration table CSV path to point to the file you created in Step 1 above.
Note: Be sure not to confuse the source and destination domain/server names. It would be 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 GroupPolicy
Import-Module ActiveDirectory
Import-Module ".\GPOMigration.psm1" -Force
# This path must be 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 destination 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 you like, making adjustments each time.
The working folder will now include a *.migtable file for the GPO migration table. You can view and edit this, but be aware that the default logic in Start-GPOImport will create a new one each time. Using Start-GPOImport requires to have 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 will take some time to smooth out. You’ll catch on.
Also be aware that by default Start-GPOImport removes any existing GPOs with the same name. This is by design. Remember that you can tweak the Start-GPOImport function to suit your own needs.
Once you get the hang of the process I encourage you to dive into the Start-GPOImport function contained in the module. It is pre-set to do a full import. Your needs will likely vary from this template. Use the syntax from this function to build your own import routine tailored to your requirements.
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 is a pain to update paths in the calling script and copy files around. On the bright side it is still way faster than the manual alternative.
As always when you are copying scripts from the internet make sure that you understand what the script will 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 will learn more PowerShell and get ideas for your own scripts.
I’d love to hear how this script module has helped you. Please use the comments below to 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
京公网安备 11010802041100号 | 京ICP备19059560号-4 | PHP1.CN 第一PHP社区 版权所有 
