[MS-GPPREF]:
Group Policy: Preferences Extension Data Structure
Intellectual Property Rights Notice for Open Specifications Documentation
Technical Documentation. Microsoft publishes Open Specifications documentation (“this documentation”) for protocols, file formats, data portability, computer languages, and standards support. Additionally, overview documents cover inter-protocol relationships and interactions.
Copyrights. This documentation is covered by Microsoft copyrights. Regardless of any other terms that are contained in the terms of use for the Microsoft website that hosts this documentation, you can make copies of it in order to develop implementations of the technologies that are described in this documentation and can distribute portions of it in your implementations that use these technologies or in your documentation as necessary to properly document the implementation. You can also distribute in your implementation, with or without modification, any schemas, IDLs, or code samples that are included in the documentation. This permission also applies to any documents that are referenced in the Open Specifications documentation.
No Trade Secrets. Microsoft does not claim any trade secret rights in this documentation.
Patents. Microsoft has patents that might cover your implementations of the technologies described in the Open Specifications documentation. Neither this notice nor Microsoft's delivery of this documentation grants any licenses under those patents or any other Microsoft patents. However, a given Open Specifications document might be covered by the Microsoft Open Specifications Promise or the Microsoft Community Promise. If you would prefer a written license, or if the technologies described in this documentation are not covered by the Open Specifications Promise or Community Promise, as applicable, patent licenses are available by contacting .
License Programs. To see all of the protocols in scope under a specific license program and the associated patents, visit the Patent Map.
Trademarks. The names of companies and products contained in this documentation might be covered by trademarks or similar intellectual property rights. This notice does not grant any licenses under those rights. For a list of Microsoft trademarks, visit
Fictitious Names. The example companies, organizations, products, domain names, email addresses, logos, people, places, and events that are depicted in this documentation are fictitious. No association with any real company, organization, product, domain name, email address, logo, person, place, or event is intended or should be inferred.
Reservation of Rights. All other rights are reserved, and this notice does not grant any rights other than as specifically described above, whether by implication, estoppel, or otherwise.
Tools. The Open Specifications documentation does not require the use of Microsoft programming tools or programming environments in order for you to develop an implementation. If you have access to Microsoft programming tools and environments, you are free to take advantage of them. Certain Open Specifications documents are intended for use in conjunction with publicly available standards specifications and network programming art and, as such, assume that the reader either is familiar with the aforementioned material or has immediate access to it.
Support. For questions and support, please contact .
Revision Summary
Date / Revision History / Revision Class / Comments8/10/2007 / 1.0 / Major / Version 1.0 release
9/28/2007 / 1.0.1 / Editorial / Changed language and formatting in the technical content.
10/23/2007 / 2.0 / Major / Updated and revised the technical content.
1/25/2008 / 2.0.1 / Editorial / Changed language and formatting in the technical content.
3/14/2008 / 3.0 / Major / Updated and revised the technical content.
6/20/2008 / 3.0.1 / Editorial / Changed language and formatting in the technical content.
7/25/2008 / 3.1 / Minor / Clarified the meaning of the technical content.
8/29/2008 / 3.2 / Minor / Split single section into multiple sections.
10/24/2008 / 4.0 / Major / Updated and revised the technical content.
12/5/2008 / 5.0 / Major / Updated and revised the technical content.
1/16/2009 / 5.0.1 / Editorial / Changed language and formatting in the technical content.
2/27/2009 / 5.0.2 / Editorial / Changed language and formatting in the technical content.
4/10/2009 / 5.0.3 / Editorial / Changed language and formatting in the technical content.
5/22/2009 / 5.1 / Minor / Clarified the meaning of the technical content.
7/2/2009 / 6.0 / Major / Updated and revised the technical content.
8/14/2009 / 6.0.1 / Editorial / Changed language and formatting in the technical content.
9/25/2009 / 7.0 / Major / Updated and revised the technical content.
11/6/2009 / 7.1 / Minor / Clarified the meaning of the technical content.
12/18/2009 / 8.0 / Major / Updated and revised the technical content.
1/29/2010 / 8.1 / Minor / Clarified the meaning of the technical content.
3/12/2010 / 9.0 / Major / Updated and revised the technical content.
4/23/2010 / 9.1 / Minor / Clarified the meaning of the technical content.
6/4/2010 / 9.2 / Minor / Clarified the meaning of the technical content.
7/16/2010 / 9.2 / None / No changes to the meaning, language, or formatting of the technical content.
8/27/2010 / 9.2 / None / No changes to the meaning, language, or formatting of the technical content.
10/8/2010 / 10.0 / Major / Updated and revised the technical content.
11/19/2010 / 11.0 / Major / Updated and revised the technical content.
1/7/2011 / 12.0 / Major / Updated and revised the technical content.
2/11/2011 / 13.0 / Major / Updated and revised the technical content.
3/25/2011 / 14.0 / Major / Updated and revised the technical content.
5/6/2011 / 15.0 / Major / Updated and revised the technical content.
6/17/2011 / 16.0 / Major / Updated and revised the technical content.
9/23/2011 / 16.0 / None / No changes to the meaning, language, or formatting of the technical content.
12/16/2011 / 17.0 / Major / Updated and revised the technical content.
3/30/2012 / 17.0 / None / No changes to the meaning, language, or formatting of the technical content.
7/12/2012 / 18.0 / Major / Updated and revised the technical content.
10/25/2012 / 18.1 / Minor / Clarified the meaning of the technical content.
1/31/2013 / 18.1 / None / No changes to the meaning, language, or formatting of the technical content.
8/8/2013 / 19.0 / Major / Updated and revised the technical content.
11/14/2013 / 20.0 / Major / Updated and revised the technical content.
2/13/2014 / 20.0 / None / No changes to the meaning, language, or formatting of the technical content.
5/15/2014 / 20.0 / None / No changes to the meaning, language, or formatting of the technical content.
6/30/2015 / 21.0 / Major / Significantly changed the technical content.
10/16/2015 / 21.0 / None / No changes to the meaning, language, or formatting of the technical content.
7/14/2016 / 22.0 / Major / Significantly changed the technical content.
6/1/2017 / 23.0 / Major / Significantly changed the technical content.
Table of Contents
1Introduction
1.1Glossary
1.2References
1.2.1Normative References
1.2.2Informative References
1.3Overview
1.3.1Preferences Encoding Overview
1.4Relationship to Other Protocols
1.5Prerequisites/Preconditions
1.6Applicability Statement
1.7Versioning and Capability Negotiation
1.8Vendor-Extensible Fields
1.9Standards Assignments
2Messages
2.1Transport
2.2Message Syntax
2.2.1Preferences Policy Message Syntax
2.2.1.1Preferences Policy File Format
2.2.1.1.1Common XML Schema
2.2.1.1.2Outer and Inner Element Names and CLSIDs
2.2.1.1.3Common XML Attributes
2.2.1.1.4Password Encryption
2.2.1.1.5Expanding Environment Variables
2.2.1.2DataSources
2.2.1.2.1Element-Specific Attributes
2.2.1.2.2DataSources Schema
2.2.1.3Devices
2.2.1.3.1Element-Specific Attributes
2.2.1.3.2Devices Schema
2.2.1.4Drives
2.2.1.4.1Element-Specific Attributes
2.2.1.4.2Drives Schema
2.2.1.5EnvironmentVariables
2.2.1.5.1Element-Specific Attributes
2.2.1.5.2EnvironmentVariables Schema
2.2.1.6Files
2.2.1.6.1Element-Specific Attributes
2.2.1.6.2Files Schema
2.2.1.7FolderOptions
2.2.1.7.1GlobalFolderOptions element
2.2.1.7.2GlobalFolderOptionsVista element
2.2.1.7.3FileType element
2.2.1.7.4OpenWith element
2.2.1.7.5FolderOptions Schema
2.2.1.8Folders
2.2.1.8.1Element-Specific Attributes
2.2.1.8.2Folders Schema
2.2.1.9IniFiles
2.2.1.9.1Element-Specific Attributes
2.2.1.9.2IniFiles Schema
2.2.1.10InternetSettings
2.2.1.10.1Internet Settings (Internet Explorer 5 and 6)
2.2.1.10.2Internet Explorer 7 Registry Keys
2.2.1.10.3Internet Explorer 8 and Internet Explorer 9 Registry Keys
2.2.1.10.4Internet Explorer 10 and Internet Explorer 11 Registry Keys
2.2.1.10.5InternetSettings Schema
2.2.1.11Local Users and Groups
2.2.1.11.1Group Inner Element
2.2.1.11.2User Inner Element
2.2.1.11.3Groups Schema
2.2.1.12NetworkOptions
2.2.1.12.1DUN Element
2.2.1.12.2VPN Element
2.2.1.12.3NetworkOptions Schema
2.2.1.13NetworkShare
2.2.1.13.1Element-Specific Attributes
2.2.1.13.2NetworkShareSettings Schema
2.2.1.14PowerOptions
2.2.1.14.1GlobalPowerOptions element
2.2.1.14.2PowerScheme element
2.2.1.14.3GlobalPowerOptionsV2 Element
2.2.1.14.4PowerOptions Schema
2.2.1.15Printers
2.2.1.15.1LocalPrinter element
2.2.1.15.2SharedPrinter Element
2.2.1.15.3PortPrinter element
2.2.1.15.4Printers Schema
2.2.1.16Regional Options
2.2.1.16.1Element-Specific Attributes
2.2.1.16.2Regional Schema
2.2.1.17Registry
2.2.1.17.1Element-Specific Attributes
2.2.1.17.2RegistrySettings Schema
2.2.1.18Scheduled Tasks
2.2.1.18.1Task Inner Element
2.2.1.18.2ImmediateTask Inner Element
2.2.1.18.3TaskV2 Inner Element
2.2.1.18.4ImmediateTaskV2 Inner Element
2.2.1.18.5ScheduledTasks Schema
2.2.1.19Services
2.2.1.19.1Element-Specific Attributes
2.2.1.19.2NTServices Schema
2.2.1.20Shortcuts
2.2.1.20.1Element-Specific Attributes
2.2.1.20.2Shortcuts Schema
2.2.1.21Start Menu
2.2.1.21.1StartMenu Inner Element
2.2.1.21.2StartMenuVista Inner Element
2.2.1.21.3Combined StartMenu and StartMenuVista Attribute Values
2.2.1.21.4StartMenuTaskbar Schema
2.2.1.22Targeting
2.2.1.23Applications
2.2.1.23.1Applications Schema
2.2.2Policy Administration Message Syntax
2.3Directory Service Schema Elements
3Protocol Details
3.1Administrative Add-in Details
3.1.1Abstract Data Model
3.1.2Timers
3.1.3Initialization
3.1.4Higher-Layer Triggered Events
3.1.5Message Processing Events and Sequencing Rules
3.1.5.1Policy Administration Update Message Sequencing
3.1.5.2Policy Administration Delete Message Sequencing
3.1.5.3Policy Administration Load Message Sequencing
3.1.6Timer Events
3.1.7Other Local Events
3.2Client Add-in Details
3.2.1Abstract Data Model
3.2.1.1Preferences Setting State
3.2.2Timers
3.2.3Initialization
3.2.4Higher-Layer Triggered Events
3.2.4.1Process Group Policy
3.2.5Message Processing Events and Sequencing Rules
3.2.5.1Preferences Policy Message Sequencing
3.2.5.1.1Deleted GPO List Processing
3.2.5.1.2New or Changed GPO List Processing
3.2.6Timer Events
3.2.7Other Local Events
4Protocol Examples
4.1Preferences Policy Application Message
4.2Protocol Samples
4.2.1DataSources XML Example
4.2.2Devices XML Example
4.2.3Mapped Drives XML Example
4.2.4EnvironmentVariables XML Example
4.2.5Files XML Example
4.2.6FolderOptions XML Example
4.2.7Folders XML Example
4.2.8IniFile XML Example
4.2.9InternetSettings XML Example
4.2.10Local Users and Groups Example
4.2.11NetworkOptions XML Example
4.2.12NetworkShareSettings XML Example
4.2.13PowerOptions XML Example
4.2.14Printers XML Example
4.2.15Regional Options XML Example
4.2.16RegistrySettings XML Example
4.2.17ScheduledTasks XML Example
4.2.18NTServices XML Example
4.2.19Shortcuts XML Example
4.2.20StartMenu XML Example
4.2.21Targeting Sample
4.2.22Applications XML Sample
5Security
5.1Security Considerations for Implementers
5.2Index of Security Parameters
6Appendix A: Product Behavior
7Change Tracking
8Index
1Introduction
This document specifies the Group Policy: Preferences Extension protocol, which provides a mechanism for an administrator to manage and deploy preferences.
Sections 1.5, 1.8, 1.9, 2, and 3 of this specification are normative. All other sections and examples in this specification are informative.
1.1Glossary
This document uses the following terms:
Active Directory: A general-purpose network directory service. Active Directory also refers to the Windows implementation of a directory service. Active Directory stores information about a variety of objects in the network. Importantly, user accounts, computer accounts, groups, and all related credential information used by the Windows implementation of Kerberos are stored in Active Directory. Active Directory is either deployed as Active Directory Domain Services (AD DS) or Active Directory Lightweight Directory Services (AD LDS). [MS-ADTS] describes both forms. For more information, see [MS-AUTHSOD] section 1.1.1.5.2, Lightweight Directory Access Protocol (LDAP) versions 2 and 3, Kerberos, and DNS.
Challenge-Handshake Authentication Protocol (CHAP): A protocol for user authentication to a remote resource. For more information, see [RFC1994] and [RFC2759].
client-side extension GUID (CSE GUID): A GUID that enables a specific client-side extension on the Group Policy client to be associated with policy data that is stored in the logical and physical components of a Group Policy Object (GPO) on the Group Policy server, for that particular extension.
computer-scoped Group Policy Object path: A scoped Group Policy Object (GPO) path that ends in "\Machine".
curly braced GUID string: The string representation of a 128-bit globally unique identifier (GUID) using the form {XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}, where X denotes a hexadecimal digit. The string representation between the enclosing braces is the standard representation of a GUID as described in [RFC4122] section 3. Unlike a GUIDString, a curly braced GUID string includes enclosing braces.
dial-up network (DUN) connection: A mechanism consisting of hardware and software that allows computers at remote locations to connect and share resources on a network. Typically, a DUN connection uses a telephone connection with modems to provide the communications channel.
domain: A set of users and computers sharing a common namespace and management infrastructure. At least one computer member of the set must act as a domain controller (DC) and host a member list that identifies all members of the domain, as well as optionally hosting the Active Directory service. The domain controller provides authentication of members, creating a unit of trust for its members. Each domain has an identifier that is shared among its members. For more information, see [MS-AUTHSOD] section 1.1.1.5 and [MS-ADTS].
environment variable: A set of string name/value pairs that are used to abstract host-specific parameters, such as the location of the operating system or installed binaries.
Extensible Authentication Protocol (EAP): A framework for authentication that is used to provide a pluggable model for adding authentication protocols for use in network access authentication, as specified in [RFC3748].
fully qualified domain name (FQDN): An unambiguous domain name that gives an absolute location in the Domain Name System's (DNS) hierarchy tree, as defined in [RFC1035] section 3.1 and [RFC2181] section 11.
globally unique identifier (GUID): A term used interchangeably with universally unique identifier (UUID) in Microsoft protocol technical documents (TDs). Interchanging the usage of these terms does not imply or require a specific algorithm or mechanism to generate the value. Specifically, the use of this term does not imply or require that the algorithms described in [RFC4122] or [C706] must be used for generating the GUID. See also universally unique identifier (UUID).
group object: A database object that represents a collection of user and group objects and has a security identifier (SID) value.
Group Policy Object (GPO): A collection of administrator-defined specifications of the policy settings that can be applied to groups of computers in a domain. Each GPO includes two elements: an object that resides in the Active Directory for the domain, and a corresponding file system subdirectory that resides on the sysvol DFS share of the Group Policy server for the domain.
Group Policy Object (GPO) path: A domain-based Distributed File System (DFS) path for a directory on the server that is accessible through the DFS/SMB protocols. This path will always be a Universal Naming Convention (UNC) path of the form: "\\<dns domain name>\sysvol\<dns domain name>\policies\<gpo guid>", where <dns domain name> is the DNS domain name of the domain and <gpo guid> is a Group Policy Object (GPO) GUID.
Group Policy server: A server holding a database of Group Policy Objects (GPOs) that can be retrieved by other machines. The Group Policy server must be a domain controller (DC).
policy setting: A statement of the possible behaviors of an element of a domain member computer's behavior that can be configured by an administrator.
preference: A value for one or more Group Policy settings that is not stored in a standard location in the registry. Instead, it is stored in another part of the registry or in administrative (.adm) files.
registry: A local system-defined database in which applications and system components store and retrieve configuration data. It is a hierarchical data store with lightly typed elements that are logically stored in tree format. Applications use the registry API to retrieve, modify, or delete registry data. The data stored in the registry varies according to the version of the operating system.
scoped Group Policy Object (GPO) path: A Group Policy Object (GPO) path appended with "\User" for the user policy mode of policy application, and "\Machine" for the computer policy mode.
security identifier (SID): An identifier for security principals that is used to identify an account or a group. Conceptually, theSID is composed of an account authority portion (typically a domain) and a smaller integer representing an identity relative to the account authority, termed the relative identifier (RID). The SID format is specified in [MS-DTYP] section 2.4.2; a string representation of SIDs is specified in [MS-DTYP] section 2.4.2 and [MS-AZOD] section 1.1.1.2.
Server Message Block (SMB): A protocol that is used to request file and print services from server systems over a network. The SMB protocol extends the CIFS protocol with additional security, file, and disk management support. For more information, see [CIFS] and [MS-SMB].
tool extension GUID or administrative plug-in GUID: A GUID defined separately for each of the user policy settings and computer policy settings that associates a specific administrative tool plug-in with a set of policy settings that can be stored in a Group Policy Object (GPO).
user object: An object of class user. A user object is a security principal object; the principal is a person or service entity running on the computer. The shared secret allows the person or service entity to authenticate itself, as described in ([MS-AUTHSOD] section 1.1.1.1).
user-scoped Group Policy Object path: A scoped Group Policy Object (GPO) path that ends in "\User".
virtual private network (VPN): A network that provides secure access to a private network over public infrastructure.
virtual private network (VPN) connection: Provides a communications path from one computer to a dedicated computer network by using another computer network (such as the Internet) to provide the transport. One typical application of a VPN is to provide secure access to a corporate computing network for an employee at a remote location.
VPN connection: A connection that transfers private data across the public network by using the routing infrastructure of the Internet.
MAY, SHOULD, MUST, SHOULD NOT, MUST NOT: These terms (in all caps) are used as defined in [RFC2119]. All statements of optional behavior use either MAY, SHOULD, or SHOULD NOT.
1.2References
Links to a document in the Microsoft Open Specifications library point to the correct section in the most recently published version of the referenced document. However, because individual documents in the library are not updated at the same time, the section numbers in the documents may not match. You can confirm the correct section numbering by checking the Errata.
1.2.1Normative References
We conduct frequent surveys of the normative references to assure their continued availability. If you have any issue with finding a normative reference, please contact . We will assist you in finding the relevant information.
[MS-ADA1] Microsoft Corporation, "Active Directory Schema Attributes A-L".
[MS-ADA2] Microsoft Corporation, "Active Directory Schema Attributes M".
[MS-ADA3] Microsoft Corporation, "Active Directory Schema Attributes N-Z".
[MS-ADLS] Microsoft Corporation, "Active Directory Lightweight Directory Services Schema".
[MS-ADSC] Microsoft Corporation, "Active Directory Schema Classes".
[MS-ADTS] Microsoft Corporation, "Active Directory Technical Specification".
[MS-GPOL] Microsoft Corporation, "Group Policy: Core Protocol".
[MS-SMB2] Microsoft Corporation, "Server Message Block (SMB) Protocol Versions 2 and 3".
[MS-SMB] Microsoft Corporation, "Server Message Block (SMB) Protocol".
[RFC1179] McLaughlin III, L., "Line Printer Daemon Protocol", RFC 1179, August 1990,
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997,
1.2.2Informative References
[MS-RRP] Microsoft Corporation, "Windows Remote Registry Protocol".
[MSDN-ACCESSDRIVER] Microsoft Corporation, "Setting Options Programmatically for the Access Driver",
[MSDN-APPSNAPIN] Microsoft Corporation, "Extending the Applications Snap-in",
[MSDN-ENVMTVAR] Microsoft Corporation, "Environment Variables", September 2007,
[MSDN-EXPLORER] Microsoft Corporation, "Common Explorer Concepts",