Copy-GPO
Copy-GPO
Copies a GPO.
Syntax
Copy-GPO [-SourceName] <string> -TargetName <string> [-CopyACL] [-MigrationTable <string>] [-SourceDomain <string>] [-SourceDomainController <string>] [-TargetDomain <string>] [-TargetDomainController <string>] [-Confirm] [-WhatIf] [<CommonParameters>]
Copy-GPO -SourceGuid <Guid> -TargetName <string> [-CopyACL] [-MigrationTable <string>] [-SourceDomain <string>] [-SourceDomainController <string>] [-TargetDomain <string>] [-TargetDomainController <string>] [-Confirm] [-WhatIf] [<CommonParameters>]
Detailed Description
The Copy-GPO cmdlet creates a (destination) GPO and copies the settings from the source GPO to the new GPO. The cmdlet can be used to copy a GPO from one domain to another domain within the same forest. You can specify a migration table to map security principals and paths when copying across domains. You can also specify whether to copy the access control list (ACL) from the source GPO to the destination GPO.
Note: Copy-GPO will not copy the source GPO if a GPO with the specified (target) display name already exists in the destination domain. In this case, an error occurs and the GPO is not copied.
Parameters
-CopyACL <SwitchParameter>
Copies the Access Control List (ACL) of the source GPO to the destination (target) GPO.
Attributes
| Name | Value |
|---|---|
Required? |
false |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
named |
-MigrationTable <string>
Specifies the location of the migration table to use for the command. You must specify the full path to the file; for example, "\\Server1\MigrationTables\TestToSalesTable.migtable". If you supply a migration table, security principals and UNC paths are mapped to the destination GPO when you copy a GPO across domains. If you do not supply a migration table, security principals and UNC paths are not modified in the destination GPO.
Attributes
| Name | Value |
|---|---|
Required? |
false |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
named |
-SourceDomain <string>
Specifies the domain of the source GPO. You must specify the fully qualified domain name (FQDN) of the domain (for example: sales.contoso.com).
If you do not specify the SourceDomain parameter, the domain of the user that is running the current session is used. (If the cmdlet is being executed from a computer startup or shutdown script, the domain of the computer is used.) For more information, see the Notes section in the full Help.
If you specify a domain that is different from the domain of the user that is running the current session (or, for a startup or shutdown script, the computer), a trust must exist between that domain and the domain of the user (or the computer).
You can also refer to the SourceDomain parameter by its built-in alias, "domainname". For more information, see about_Aliases.
Attributes
| Name | Value |
|---|---|
Required? |
false |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
named |
-SourceDomainController <string>
Specifies the name of the domain controller that this cmdlet contacts for the source domain. You can specify either the fully qualified domain name (FQDN) or the host name. For example:
FQDN: DomainController1.sales.contoso.com
Host Name: DomainController1
If you do not specify the name by using the SourceDomainController parameter, the PDC emulator is contacted.
Attributes
| Name | Value |
|---|---|
Required? |
false |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
named |
-SourceGuid <Guid>
Specifies the source GPO by its globally unique identifier (GUID). The GUID uniquely identifies the GPO.
You can also refer to the SourceGuid parameter by its built-in alias, "id". For more information, see about_Aliases.
Attributes
| Name | Value |
|---|---|
Required? |
true |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
named |
-SourceName <string>
Specifies the source GPO by its display name.
The display name is not guaranteed to be unique in the domain. If another GPO with the same display name exists in the domain an error occurs. You can use the SourceGuid parameter to uniquely identify a GPO.
You can also refer to the SourceName parameter by its built-in alias, "displayname". For more information, see about_Aliases.
Attributes
| Name | Value |
|---|---|
Required? |
true |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
1 |
-TargetDomain <string>
Specifies the domain to which you want to copy the GPO (the destination domain). You must specify the fully qualified domain name (FQDN) of the domain (for example: sales.contoso.com).
If you do not specify the TargetDomain parameter, the domain of the user that is running the current session is used. (If the cmdlet is being executed from a computer startup or shutdown script, the domain of the computer is used.) For more information, see the Notes section in the full Help.
If you specify a domain that is different from the domain of the user that is running the current session (or, for a startup or shutdown script, the computer), a trust must exist between that domain and the domain of the user (or the computer).
Attributes
| Name | Value |
|---|---|
Required? |
false |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
named |
-TargetDomainController <string>
Specifies the name of the domain controller that this cmdlet contacts for the destination domain. You can specify either the fully qualified domain name (FQDN) or the host name. For example:
FQDN: DomainController1.sales.contoso.com
Host Name: DomainController1
If you do not specify the name by using the TargetDomainController parameter, the PDC emulator is contacted.
Attributes
| Name | Value |
|---|---|
Required? |
false |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
named |
-TargetName <string>
Specifies the display name for the destination GPO. If another GPO with the same display name exists in the destination (target) domain, an error occurs.
Attributes
| Name | Value |
|---|---|
Required? |
true |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
named |
-Confirm <SwitchParameter>
Prompts you for confirmation before executing the command.
Attributes
| Name | Value |
|---|---|
Required? |
false |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
named |
-WhatIf <SwitchParameter>
Describes what would happen if you executed the command without actually executing the command.
Attributes
| Name | Value |
|---|---|
Required? |
false |
Accept wildcard characters? |
false |
Accept Pipeline Input? |
false |
Position? |
named |
-CommonParameter
This cmdlet supports the common parameters: -Verbose, -Debug, -ErrorAction, -ErrorVariable, -OutBuffer, and -OutVariable. For more information, see About Common Parameter
Input and Return Types
The input type is the type of the objects that you can pipe to the cmdlet. The return type is the type of the objects that the cmdlet emits.
Input Type |
Microsoft.GroupPolicy.Gpo. The cmdlet takes a GPO as input. GPO objects that are piped into the cmdlet are used as the source GPO. Collections that contain GPOs from different domains are not supported. |
Return Type |
Microsoft.GroupPolicy.Gpo. This cmdlet outputs a copy of the specified GPO. |
Notes
You can use the Copy-GPO cmdlet to copy a GPO within a domain or from one domain to another within the same forest.
You can use the SourceDomain and TargetDomain parameters to explicitly specify the source domain or the target domain for this cmdlet.
If you do not explicitly specify the domain, the cmdlet uses a default domain. The default domain is the domain that is used to access network resources by the security context under which the current session is running. This domain is typically the domain of the user that is running the session. For example, the domain of the user who started the session by opening Windows PowerShell from the Program Files menu, or the domain of a user that is specified in a runas command. However, computer startup and shutdown scripts execute under the context of the LocalSystem account. The LocalSystem account is a built-in local account, and it accesses network resources under the context of the computer account. Therefore, when this cmdlet is executed from a startup or shutdown script, the default domain is the domain to which the computer is joined.
Examples
EXAMPLE 1
C:\PS>
Copy-GPO -SourceName TestGpo1 -TargetName TestGpo2
DisplayName : TestGpo2
DomainName : contoso.com
Owner : CONTOSO\Domain Admins
Id : 37eeb072-cc31-42bb-8c3a-446c2b6ddd3f
GpoStatus : AllSettingsEnabled
Description :
CreationTime : 2/25/2009 9:12:05 PM
ModificationTime : 2/25/2009 9:12:05 PM
UserVersion : AD Version: 1, SysVol Version: 1
ComputerVersion : AD Version: 1, SysVol Version: 1
WmiFilter :
Description
-----------
This command copies the "TestGpo1" GPO to a GPO named "TestGpo2". The GPOs exist in the domain of the user that is running the session (or, for startup and shutdown scripts, the computer).
EXAMPLE 2
C:\PS>
Copy-GPO -SourceName TestGpo1 -SourceDomain test.contoso.com TargetName TestGpo1 -TargetDomain sales.contoso.com
Description
-----------
This command copies the "TestGpo1" GPO from the test.contoso.com domain to a GPO named TestGpo1 in the sales.contoso.com domain.
A trust relationship must exist between the source domain and the destination domain. In addition, if the source domain or the destination domain (or both) is different than the domain of the user that is running the session (or, for startup and shutdown scripts, the computer), a trust must exist between that domain and the domain of the user (or the computer).
EXAMPLE 3
C:\PS>
get-gpo -all -domain sales1.contoso.com | foreach-object {$_ | copy-gpo -targetName ($_.DisplayName) -targetdomain sales2.contoso.com -copyacl -migrationtable c:\tables\MigrationTable.migtable}
Description
-----------
This command copies all the GPOs in the sales1.contoso.com domain to the sales2.contoso.com domain.
First, all the GPOs in the source domain are retrieved by using the Get-GPO cmdlet with the All parameter. The output of Get-GPO is piped into the foreach-object command. When each GPO is evaluated, it is piped into Copy-GPO and its display name is specified for the TargetName parameter "-targetName ($_.DisplayName)". The CopyACL parameter is specified to copy the ACLs for each GPO to the destination domain. The MigrationTable parameter specifies a migration table to use to migrate Security principals and UNC paths to the destination domain. Both the CopyACL and the MigrationTable parameters are optional.
If a GPO with the same display name as a source GPO already exists in the destination domain, an error occurs when this command attempts to copy the source GPO. Because this command copies all GPOs in the source domain, errors occur for default GPOs; for example, the "Default Domain Policy" GPO and the "Default Domain Controllers Policy" GPO. These GPOs are not copied. You can suppress these error messages by supplying the ErrorAction parameter with a value of SilentlyContinue to Copy-GPO. For more information about the ErrorAction parameter, see about_CommonParameters.
The (destination) GPOs that were successfully copied are returned by this command. By default, they are printed to the display, but you can add commands to the end of the pipeline to further configure these GPOs. For example you can add a Set-GPLinks cmdlet to the end of the pipeline to link all the destination GPOs to a site, domain, or organizational unit.
A trust relationship must exist between the source domain and the destination domain. In addition, if the source domain or the destination domain (or both) is different than the domain of the user that is running the session (or, for startup and shutdown scripts, the computer), a trust must exist between that domain and the domain of the user (or the computer).