GPO Backup and Restore

From SambaWiki


Added in Samba version: 4.10

<What does the feature do, Why might users care about it, What is the Microsoft-equivalent that a Windows admin might be familiar with, etc>

GPO creation and management has a number of issues in Samba still. Synchronization of GPO often causes problems with access permissions due to missing AD file replication protocols. In order to start from scratch, building a GPO can be incredibly time consuming (as it mostly requires a GUI editor) and so allowing a backup to be restored (to a new GPO) makes this a lot easier.

In Windows, it is possible to backup (and restore) a GPO using the following Powershell commands: Backup-GPO, Restore-GPO or alternatively by using the GUI group policy editor. There are a few problems with using these tools. The output is a mix of storage formats, dependencies and has general inconsistencies which make it difficult for an admin to understand what is happening and in particular, manually edit the contents of their GPOs in the case of errors. Windows supports importing GPO using migration tables, but there are a number of file formats, where information is stored. These files and GPO settings are not supported by these tables for replacing names and other AD domain-specific data when performing migrations. By having simple XML, and a human readable formats which are easily machine parseable and allows substitution, it makes the process much more transparent (and hopefully, eventually far more complete).

How to configure it

Setup your GPO,

Generalizing a GPO (to use in a different domain)

samba-tool gpo backup --generalize --entities=<output path>

The generated entities are in the standard XML DTD header format, and are used likewise.

There are currently three types of entities: user ID (SID, usernames), ACL (SDDL), share paths (\\unc paths)

Example (entities) output
<!ENTITY SAMBA__NETWORK_PATH__82419dafed126a07d6b96c66fc943735__ "\\">
<!ENTITY SAMBA__NETWORK_PATH__0484cd41ded45a0728333a9c5e5ef619__ "\\test">
<!ENTITY SAMBA____SDDL_ACL____4ce8277be3f630300cbcf80a80e21cf4__ "D:PAR(A;CI;KA;;;BA)(A;CIIO;KA;;;CO)(A;CI;KR;;;S-1-0-0)">
<!ENTITY SAMBA____USER_ID_____d0970f5a1e19cb803f916c203d5c39c4__ "*S-1-5-21-3075996733-1131693954-1131023892-501">
<!ENTITY SAMBA____USER_ID_____7b7bc2512ee1fedcd76bdc68926d4f7b__ "Guest">

In the backup folder, the generated XML files will now contain XML entities to replace certain strings from the directory. If you are migrating a GPO across a domain, you must inspect these entities and edit them for appropriate replacements.

When generalizing a GPO, these are handled as special cases and are not complete, although Windows and migrating using their equivalent migration tables also has its problems. In some cases, you may wish to manually replace strings with entities which works as you would expect (and isn't possible for certain file types on Windows, but is possible with this tool).

Restoring with an entities file
samba-tool gpo restore --entities=<new entities file>

As you can manually edit the contents of GPO files (and replace contents with entities), do note that settings may not be applied as you expect, so you should verify after you restore.

Known issues and limitations

In Samba 4.10, there are these bugs currently open (no backports yet):

  • BUG #13825: GPE.INI files causes backup to fail
  • BUG #13806: GPT.INI failing with GPO names with accents
  • BUG #13627: GPO import doesn't enable the GPO immediately

This tool is largely independent to many Samba components. Building from source and running the latest Git master to backup and restore fixes these bugs correctly.

GPE.INI files causes backup to fail

Currently, if a GPE.INI file is created via RSAT, the backup no longer works. The only likely workaround would be to remove the GPE.INI file temporarily and copy it to its final location manually.

It would be recommended to use Samba master until this patch is backported.

GPT.INI failing with GPO names with accents

Currently, the only workaround for this bug appears to be avoiding setting a display name with non-ASCII characters. Removing the display name from the GPT.INI manually may also be an option (but note, this hasn't been tested).

In master, the name is interpreted as Latin-1 and is eventually removed entirely in any restored GPO (as the name appears to be sourced from LDAP and not this file).

GPO import doesn't enable the GPO immediately

Currently, the gPCMachineExtensionNames and gPCUserExtensionNames values on a newly restored GPO are not being set. To workaround, querying over LDAP from the DC where the backup was made, copy these values to the new GPO.

In master, this is now automatically done by the tool (but a new backup must be generated).


Manually inspecting output files and the resulting GPO in RSAT is probably the best way to ensure that the GPO work as intended. The generalization function for migrating GPO across domains is still incomplete as there are only a subset of files that support this feature in the tool.

Report any errors to Samba bugzilla, there are probably a number of files (and associated file formats) which have yet to be attempted with this tool.

For Developers

How to test it

make test TESTS=samba_tool.gpo

GPO import and export has a fallback mode to restore from binary files instead of from XML if any errors occur in the restore. Currently there isn't any way to turn this off, and so what should probably fail often doesn't.

Where the code is located

The core parsing logic for GPO is in the python gp_parse module.

The outer logic lives in netcmd/ (where the actual regex matching used to identify which parser is used) and the tests are all in the samba_tool tests.

Note: The parser for PReg .pol files is auto-generated from IDL.

Reference Docs

[MS-GPOD] and [MS-GPOD] describe an overview of how the overall Group Policy system works. Individual references to which file formats correspond to which parsers lives in the comments of each parser class in gp_parse.