Microsoft Windows Registry Guide, Second Edition
Extending Registry-Based Policy
You can extend registry-based policy by customizing existing administrative templates or by creating new ones. Windows provides administrative templates for its policies. Other applications, such as Office 2003 Editions, also provide templates. When you install the Microsoft Office 2003 Editions Resource Kit, it adds the Office 2003 Editions policy templates to %SystemRoot%\Inf. You should never customize these templates. You might want to create your own templates that extend registry-based policy, though.
First, the caveats: extending registry-based policy is generally something that developers do to give administrators more control over users' applications. Remember that a registry-based policy requires developers to add code that reads policies and enforces those settings to their applications. If developers added policies to their code, they almost certainly created policy templates for them, so you don't have to. On the other hand, if no code enforces a policy setting, creating an administrative template for it is useless. It almost sounds like extending registry-based policy is futile, right? But there are still times when it's useful, including times when it's extremely valuable:
- Repairing broken policies.
I don't run across broken policies often, but when I do, the only way to fix them is to create a custom template for them. For example, in the Windows XP beta, the screen saver policy stored the timeout period incorrectly in the registry. Creating a custom template was my simple fix to this.
- Creating custom administrative templates.
Windows supports hundreds of policies, as does Office 2003 Editions. Hunting for policies is sometimes frustrating. You can create a custom administrative template that assembles in one place all the policies you're deploying, making the job a bit easier. You can also rephrase the language of a policy with descriptions that are easier to understand.
- Customizing Windows.
Many of the registry settings that you can use to customize Windows have no user interface. You can build a user interface for them by creating an administrative template and then changing those settings with Group Policy Editor. For power users, this is a great reason to master this topic. This method goes against one of the primary features of Group Policy, however, because settings that you change outside the normal policy branches in the registry will tattoo the registry.
You can use any text editor to create an administrative template. Administrative templates have a language of their own, and you learn about that language in the remainder of this section. Group Policy Editor is very good at displaying intuitive error messages when a template file contains an error, giving you the line number, the erroneous keyword, and more information. In summary, here's how to use an administrative template:
Using the language that you learn about in this chapter, create an administrative template. The template file is a text file with the .adm extension.
Load the template file into Group Policy Editor as you learn to do later in this chapter in the section “Deploying Registry-Based Policy.”
Edit the settings that the administrative template defines.
The following listing is a sample administrative template that doesn't do much, but does illustrate what a template file looks like. Figure 7-4 shows what this template looks like in Group Policy Editor. The figure's annotations show some of the keywords that are responsible for different portions of a policy. For example, the keyword EXPLAIN is responsible for displaying the policy's description that you see in the figure. Throughout the remainder of this section, you'll see dozens more examples that give you the building blocks for creating your own administrative templates. Take these building blocks and copy them into your file to get started right away.
Figure 7-4 Administrative templates, such as the one in this example, define the user interface for collecting settings that the editor stores in the file Registry.pol.
Listing 7-1 example.adm
CLASS USER CATEGORY "Sample Policies" #if version >= 4 EXPLAIN "These are sample policies that don't do anything." #endif POLICY "Sample Policy" #if version >= 4 SUPPORTED "At least Microsoft Windows XP Professional" #endif EXPLAIN "This is a sample policy that doesn't do much." KEYNAME "Software\Policies" VALUENAME Sample VALUEON NUMERIC 1 VALUEOFF NUMERIC 0 END POLICY END CATEGORY
NOTE
The statements #if and #endif enclose statements that work with only certain versions of System Policy or Group Policy. Using these statements, the developer can write one administrative template that works with different versions of Windows, including Windows NT, Windows 2000, Windows Server 2003, and Windows XP. System Policy in Windows NT is version 2. Windows 2000 is version 3. Windows XP Service Pack 1 (SP1) is version 4. Windows XP SP2 and Windows Server 2003 are version 5. Thus, to make sure that Group Policy Editor in Windows 2000 ignores keywords that only Windows XP supports, the developer encloses those keywords between #if version >= 4 and #endif. To ensure that only System Policy Editor in Windows NT sees a block of keywords, enclose them between #if version = 2 and #endif. These conditional statements show that Microsoft was thinking far into the future, even back in the old days.
Comments
Comments are useful and necessary for documenting the contents of your policy templates. There are two different ways to add comments to template files. First, you can precede the comment with a semicolon (;) or with two forward slashes (//). Second, you can place comments at the end of any valid line. You see examples of comments throughout this chapter; I've documented each example that uses them. Each line in the following example is a valid comment. I prefer using // for comments.
Listing 7-2 example.adm
; This is a comment // This is also a comment CLASS USER // Per-user settings CLASS MACHINE; Per-computer settings
Strings
When creating a quick and easy template file that you'll only use once, don't feel badly about hard-coding strings, adding the string where you need it and then repeating the same string as often as necessary. The listing you saw earlier, in the section “Extending Registry-Based Policy,” uses hard-coded strings. If you're using enterprise-class template files, or if you're managing the files over time, use string variables; this makes it easier to maintain template files that use the same strings more than once. More importantly, it makes localization of template files far easier and much less error-prone.
Define strings at the end of your template file in the [strings] section. The format of each string is name="string". You must enclose the string in double quotation marks. To use string variables in your template file, use the format !!name. Each time that Group Policy Editor sees !! name, it substitutes the string for the name. Incidentally, the !! makes it easy to search template files for strings–just search the file for the double exclamation marks. The following listing is an example of how strings and string variables are used in a template file:
Listing 7-3 example.adm
POLICY !!Sample // Defined in [strings] section SUPPORTED "At least Microsoft Windows XP" // Hard-coded string EXPLAIN !!Sample_Explain // Defined in [strings] section ... [strings] Sample="Sample Policy" Sample_Explain="This sample policy doesn't do much of anything."
NOTE
In this chapter, for clarity, I tend not to use string variables. Avoiding string variables prevents you from having to look up each string as you're wading through the listings. Keep in mind that you'll want to use string variables if you plan on localizing your files.
CLASS
The first entry in a template file is the keyword CLASS. It defines whether the policies following it are per-user or per-computer; that is, it specifies whether you see the policy in User Configuration or Computer Configuration. You can use multiple CLASS keywords in a template file. When the Windows client-side extensions process the file, they merge the settings defined in the CLASS USER sections and merge the settings defined in the CLASS MACHINE sections. Then they load the settings defined in the CLASS USER sections in HKCU and the settings defined in the CLASS MACHINE sections in HKLM.
Syntax
CLASS Name
Name | This must be MACHINE or USER. MACHINE specifies that the policies following the CLASS keyword are per-computer policies, and USER specifies that the policies following the keyword are per-user policies. This keyword persists until you change it using additional CLASS keywords. |
Example
Listing 7-4 example.adm
CLASS MACHINE // Policies here are per-computer policies CLASS USER // Policies here are per-user policies CLASS MACHINE // Policies here are per-computer policies
CATEGORY
After using the keyword CLASS to define whether your policy will appear under the Computer Settings branch or the User Settings branch of Group Policy Editor, use the keyword CATEGORY to create subfolders in that branch. The editor displays your settings in that folder. Just as you can create subkeys within keys in the registry, you can create subcategories within categories by nesting the keyword CATEGORY. Just keep in mind that all that the keyword CATEGORY does is create folders.
Categories can include zero or more policies. Categories that contain no policies usually contain one or more subcategories. You use the keyword KEYNAME, which you learn about in the next section, to define a registry key in which Group Policy Editor creates settings for that category. Using the keyword KEYNAME here is optional if you're defining the key elsewhere. You end a category with END CATEGORY.
Syntax
CATEGORY Name KEYNAME Subkey Policies END CATEGORY
Name | This is the folder name that you want to see in Group Policy Editor. Use a string variable or a string enclosed in quotes. |
Subkey | This is an optional subkey of HKLM or HKCU that you can use for the category. Do not include either root key in the path, though, because the preceding keyword, CLASS, specifies which of these root keys to use. If you specify a subkey, all subcategories, policies, and parts will use it unless they specifically provide subkeys of their own. Enclose in double quotes names that contain spaces. |
Example
Listing 7-5 example.adm
CLASS USER // Settings are per-user in HKCU CATEGORY "Desktop Settings" KEYNAME "Software\Policies\System" // Add policies for the Desktop Settings category here CATEGORY "Custom Application Settings" KEYNAME "Software\Policies\CustomApps" // Add policies for the custom applications subcategory here END CATEGORY END CATEGORY
Keywords
The valid keywords you can use within a CATEGORY section are the following ones:
CATEGORY
END
KEYNAME
POLICY
KEYNAME
Use the keyword KEYNAME within a category to define which subkey of HKCU or HKLM (depending on the CLASS keyword) contains the value you're changing. Do not include a root key in the path because the keyword CLASS defines it. If the name contains spaces, you must enclose the string in double quotation marks. The example in the preceding section, “CATEGORY,” shows how to use the keyword KEYNAME.
POLICY
Use the keyword POLICY to define a policy that the administrator can change. The policy editor displays the policy and its controls in a dialog box that the administrator uses to change the policy's state and settings. You can include multiple POLICY keywords in a single category, but you don't need to include the keyword KEYNAME before each keyword POLICY. The most recent keyword KEYNAME applies for each policy. You end a policy with END POLICY.
Each policy contains a VALUENAME keyword to associate a registry value with it. By default, the policy editor assumes it's a REG_DWORD value and stores 0x01 in it when you enable the policy. The policy editor also removes the value when you disable the policy. You must use the keywords VALUEON and VALUEOFF if you don't want the editor to remove the value when you disable the policy. You don't have to use any keywords other than VALUENAME to get this behavior. However, you can specify additional options, such as drop-down list boxes, check boxes, text boxes, and more, by including optional PART keywords. You see these controls in the bottom part of the policy's dialog box. (See Figure 7-3.)
Syntax
POLICY Name [KEYNAME Subkey] EXPLAIN Help VALUENAME Value [Parts] END POLICY
Name | This is the name of the policy as you want to see it in Group Policy Editor. Use a short, descriptive name. |
Subkey | This is an optional subkey of HKLM or HKCU to use for the category. Do not include either root key in the path, though, because the preceding keyword CLASS specifies which of these root keys to use. If you specify a subkey, all subcategories, policies, and parts use it unless they specifically provide a subkey of their own. Enclose names that contain spaces in double quotes. |
Help | This is the string that Group Policy Editor displays on the Explain tab and on the Extended tab of the policy's dialog box. |
Value | This is the registry value to modify. Enabling the policy sets the REG_DWORD value to 0x01. Select the Not Configured option (disable the policy), and the policy editor removes the value from the registry. To specify values other than the default 0x01, use the keywords VALUEON and VALUEOFF directly following the keyword VALUENAME:
VALUEON [NUMERIC] Enabled VALUEOFF [NUMERIC] Disabled When you use these keywords, the policy editor sets the registry value to Enabled when you enable the policy and sets the value to Disabled when you disable the policy. The default value type is REG_SZ, but you can change it to REG_DWORD by prefixing the value with the keyword NUMERIC. Regardless, setting the policy to Not Configured removes the value altogether. |
Example
Listing 7-6 example.adm
CLASS MACHINE CATEGORY "Disk Quotas" KEYNAME "Software\Policies\MS\DiskQuota" POLICY "Enable disk quotas" EXPLAIN "Enables and disables disk quotas management." VALUENAME "Enable" VALUEON NUMERIC 1 VALUEOFF NUMERIC 0 END POLICY END CATEGORY
Keywords
The valid keywords within a POLICY section include the following:
ACTIONLISTOFF
ACTIONLISTON
END
KEYNAME
PART
VALUENAME
VALUEOFF
VALUEON
HELP
POLICY
NOTE
Additional keywords are available for policies, but they are for developers creating policy extensions. For example, CLIENTEXT associates a client-side extension with a policy via the extension's GUID. I'm not covering these additional keywords because they don't fit our purposes here.
EXPLAIN
The keyword EXPLAIN provides help text for a specific policy. In Windows 2000, Windows XP, and Windows Server 2003, each policy's dialog box includes an Explain tab, which provides details about the policy settings. You also see this help text on the Extended tab of the editor's right pane in Windows XP and Windows Server 2003. Each policy you create for Windows 2000, Windows XP, and Windows Server 2003 should contain one EXPLAIN keyword followed by a full description of the policy and its settings. Although I don't show this in my examples (because I'm trying to keep them simple), you should enclose this keyword between #if version >=3 and #endif to prevent earlier versions of the policy editor from choking on these keywords, as shown in Listing 7-7.
Listing 7-7 example.adm
#if version >=3 EXPLAIN "Enables and disables disk quotas management." #endif
VALUENAME
The keyword VALUENAME identifies the registry value that the policy editor modifies when you enable or disable the policy. The syntax is VALUENAME Name. You saw an example of this keyword earlier in this chapter in the section “POLICY.” Unless you set the keywords VALUEON and VALUEOFF, described in the next section, the policy editor creates the policy as a REG_DWORD value:
- Enabled.
Sets the value to 0x01
- Disabled.
Removes the value
- Not Configured.
Removes the value
The keywords VALUENAME, VALUEON, and VALUEOFF describe the value that enables and disables the policy. If you want to define additional settings that enable you to collect additional values to refine the policy, you must use the keyword PART. Settings in a PART section are in the bottom part of the policy's dialog box.
VALUEON and VALUEOFF
You can use the VALUEON and VALUEOFF keywords to write specific values based on the state of the policy. The section “POLICY” contains an example of how these keywords are used. The syntaxes are VALUEON [NUMERIC] Enabled and VALUEOFF [NUMERIC] Disabled. By default, the policy editor creates the value as a REG_SZ value; if you want the policy editor to create the value as a REG_DWORD value, prefix it with the NUMERIC keyword. The following are examples of both:
VALUEON 0 // Created as a REG_SZ value containing "0" VALUEOFF NUMERIC 1 // Created as a REG_DWORD value containing 0x01
ACTIONLIST
The keyword ACTIONLIST enables you to group settings together. Think of it as a list of values that you want the policy editor to change when you change a policy. The following two variants of the keyword ACTIONLIST are the most commonly used ones:
- ACTIONLISTON.
A list of values to change when the policy is enabled
- ACTIONLISTOFF.
A list of values to change when the policy is disabled
Syntax
ACTIONLIST [KEYNAME Subkey] VALUENAME Value VALUE Data END ACTIONLIST
Subkey | This is an optional subkey of HKLM or HKCU to use for the category. Do not include either root key in the path, though, because the preceding keyword CLASS specifies which of these root keys to use. If you specify a subkey, all subcategories, policies, and parts use it unless they specifically provide a subkey of their own. Enclose names that contain spaces in double quotes. |
Value | This is the registry value to modify. Enabling the policy sets the REG_DWORD value to 0x01. Select the Not Configured option, and the policy editor removes the value from the registry. To specify values other than the default 0x00 and 0x01, use the keyword VALUE. |
Data | This is the data to which you want to set the value. The default value type is REG_SZ, but you can change it to REG_DWORD by prefixing the value with the keyword NUMERIC. If you follow the keyword VALUE with the keyword DELETE (VALUE DELETE), policy editor removes the value from the registry. Regardless, setting the policy to Not Configured removes the value altogether. |
Example
Listing 7-8 example.adm
POLICY "Sample Action List" EXPLAIN "This illustrates action lists" ACTIONLISTON VALUENAME Sample1 VALUE 1 VALUENAME Sample2 VALUE 1 END ACTIONLISTON ACTIONLISTOFF VALUENAME Sample1 VALUE 0 VALUENAME Sample2 VALUE 0 END ACTIONLISTOFF END POLICY
PART
The keyword PART enables you to specify various options, including drop-down lists, text boxes, and check boxes, in the lower part of a policy's dialog box. Figure 7-5 shows an example of the settings that you want to collect in addition to enabling or disabling the policy. For simple policies that you only need to enable or disable, you won't need to use this keyword. In fact, only a relative handful of the policies in Windows use the keyword PART at all.
Figure 7-5 Use the PART keyword to collect additional data that further refines the policy.
You begin a part with the keyword PART and end it with END PART. The syntax of the keyword PART is PART Name Type. Name is the name of the part, and Type is the type of the part. Each policy can contain multiple PART keywords, and the policy editor displays them in the dialog box using the same order that they had in the administrative template. This section gives you the overall syntax of the keyword PART, and the sections following this one describe how to create the different types of parts.
Syntax
PART Name Type Keywords [KEYNAME Subkey] [DEFAULT Default] VALUENAME Name END PART
Name | This specifies the name of the setting as you want to see it in the policy's dialog box. Enclose the name in double quotes if it contains spaces. This is the setting's prompt. |
Type | This can be one of the following types:
|
Keywords | This information is specific to each type of part. See the sections following this for more information about these keywords. |
Subkey | This is an optional subkey of HKLM or HKCU to use for the category. Do not include either root key in the path, though, because the preceding keyword CLASS specifies which of these root keys to use. If you specify a subkey, all subcategories, policies, and parts use it unless they specifically provide a subkey of their own. Enclose names that contain spaces in double quotes. |
Default | This is the default value for the part. When you enable the policy, the policy editor fills the control with the default value. Use a default value that's appropriate for the part's type. |
Value | This is the registry value to modify. The value type and data depend entirely on the part's type. |
Example
Listing 7-9 example.adm
POLICY "Sample Part" EXPLAIN "This illustrates parts" KEYNAME "Software\Policies" POLICY "Sample Policy" EXPLAIN "This is a sample policy including parts." VALUENAME "Sample" PART test EDITTEXT DEFAULT "This is the default text" VALUENAME Sample END PART END POLICY
Keywords
The valid keywords within a PART section are the following ones:
CHECKBOX
COMBOBOX
DROPDOWNLIST
EDITTEXT
END
LISTBOX
NUMERIC
PART
TEXT
CHECKBOX
The keyword CHECKBOX displays a check box. In the registry, it's a REG_SZ value. By default, the check box is cleared, and the settings it writes to the registry for each of its states are as follows:
- Checked.
Writes 1 to the REG_SZ value
- Cleared.
Writes 0 to the REG_SZ value
Include the keyword DEFCHECKED within the part if you want the check box selected by default. Otherwise, the check box is cleared by default.
Syntax
PART Name CHECKBOX DEFCHECKED VALUENAME Value END PART
Name | This specifies the name of the setting as you want to see it in the policy's dialog box. Enclose the name in double quotes if it contains spaces. You see the name next to the check box. |
Value | This is the registry value to modify. Enabling the policy sets the REG_SZ value to 1. Set the Not Configured option, and the policy editor removes the value from the registry. To specify values other than the default 0 and 1, use the keywords VALUEON and VALUEOFF following the keyword VALUENAME:
VALUEON [NUMERIC] Enabled VALUEOFF [NUMERIC] Disabled When you use these keywords, the policy editor sets the registry value to Enabled when you enable the policy, and it sets the value to Disabled when you disable the policy. The default value type is REG_SZ, but you can change it to REG_DWORD by prefixing the value with the keyword NUMERIC. Regardless, setting the policy to Not Configured removes the value altogether. You can also use the keywords ACTIONLISTON and ACTIONLISTOFF to associate multiple values with a check box. |
Example
Listing 7-10 example.adm
CLASS USER CATEGORY "Sample Policies" EXPLAIN "These are sample policies that illustrate parts." POLICY "Sample Policy" SUPPORTED "At least Microsoft Windows XP Professional" EXPLAIN "This is a sample policy that illustrates a part." KEYNAME "Software\Policies" PART Sample1 CHECKBOX VALUENAME Sample1 END PART PART Sample2 CHECKBOX DEFCHECKED VALUENAME Sample2 VALUEON NUMERIC 11 VALUEOFF NUMERIC 12 END PART END POLICY END CATEGORY
Keywords
The valid keywords within a CHECKBOX section include the following:
ACTIONLISTOFF
ACTIONLISTON
DEFCHECKED
END
KEYNAME
VALUENAME
VALUEOFF
VALUEON
COMBOBOX
The keyword COMBOBOX adds a combo box to the policy's dialog box. It has one additional keyword you must use: SUGGESTIONS. This creates a list of suggestions that the policy editor places in the drop-down list. Separate the items in this list with white space, and enclose items containing spaces in double quotation marks. End the list with the END SUGGESTIONS.
A few keywords modify the behavior of the combo box:
- DEFAULT.
Specifies the default value of the combo box
- EXPANDABLETEXT.
Creates the value as a REG_EXPAND_SZ value
- MAXLENGTH.
Specifies the maximum length of the value
- NOSORT.
Prevents the policy editor from sorting the list
- REQUIRED.
Specifies that a value is required
Syntax
PART Name COMBOBOX SUGGESTIONS Suggestions END SUGGESTIONS [DEFAULT Default] [EXPANDABLETEXT] [MAXLENGTH Max] [NOSORT] [REQUIRED] VALUENAME Value END PART
Name | This specifies the name of the setting as you want to see it in the policy's dialog box. Enclose the name in double quotation marks if it contains spaces. You see the name next to the combo box. |
Suggestions | This is a list of items to put in the drop-down list. Separate each suggestion with white space (line feeds, tabs, and spaces, for example), and enclose any suggestion that includes a space in double quotes. |
Default | This is the default value for the part. When you enable the policy, the policy editor fills the control with the default value. Use a default value that's appropriate for the part's type. |
Max | This is the maximum length of the value's data. |
Value | This is the registry value to modify. The policy editor creates this in the registry as a REG_SZ value and fills it with any text that you typed or selected in the combo box. |
Example
Listing 7-11 example.adm
CLASS USER CATEGORY "Sample Policies" EXPLAIN "These are sample policies that don't do anything but illustrate parts." POLICY "Sample Policy" SUPPORTED "At least Microsoft Windows XP Professional" EXPLAIN "This is a sample policy that illustrates creating a part." KEYNAME "Software\Policies" PART Sample COMBOBOX SUGGESTIONS Sample1 Sample2 "Another Sample" END SUGGESTIONS VALUENAME Sample END PART END POLICY END CATEGORY
Keywords
The valid keywords within a COMBOBOX section are the following:
DEFAULT
END
EXPANDABLETEXT
KEYNAME
MAXLENGTH
NOSORT
REQUIRED
SUGGESTIONS
VALUENAME
DROPDOWNLIST
The keyword DROPDOWNLIST adds a drop-down list to the policy's dialog box. It has one additional keyword that you must use, and that is ITEMLIST. This creates a list of items that the policy editor places in the drop-down list. Use the syntax NAME Name VALUE Value to define each item within the ITEMLIST section. Enclose items containing spaces within double quotation marks. End the list with the END ITEMLIST.
A few keywords modify the behavior of the drop-down list:
- DEFAULT.
Specifies the default value of the drop-down list
- EXPANDABLETEXT.
Creates the value as a REG_EXPAND_SZ value
- NOSORT.
Prevents the policy editor from sorting the list
- REQUIRED.
Specifies that a value is required
Syntax
PART Name DROPDOWNLIST ITEMLIST NAME Item VALUE Data END ITEMLIST [DEFAULT Default] [EXPANDABLETEXT] [NOSORT] [REQUIRED] VALUENAME Value END PART
Name | This specifies the name of the setting as you want to see it in the policy's dialog box. Enclose the name in double quotes if it contains spaces. You see the name next to the drop-down list. |
Item | This is the name of each item in the list. This is the text that you'll see in the drop-down list. This isn't the value that the policy editor stores in the registry, though. |
Data | This is the data that you want the policy editor to store in the value when you select the associated item. |
Default | This is the default value for the part. When you enable the policy, the policy editor fills the control with the default value. Use an item defined in ITEMLIST. |
Value | This is the registry value to modify. The policy editor creates this in the registry as a REG_SZ value and fills it with the value of Data associated with the selected item. |
Example
Listing 7-12 example.adm
CLASS USER CATEGORY "Sample Policies" EXPLAIN "These are sample policies that illustrate parts." POLICY "Sample Policy" SUPPORTED "At least Microsoft Windows XP Professional" EXPLAIN "This is a sample policy that illustrates creating a part." KEYNAME "Software\Policies" PART Sample DROPDOWNLIST ITEMLIST NAME Sample1 VALUE 0 NAME Sample2 VALUE 1 NAME "Another Sample" VALUE 2 END ITEMLIST VALUENAME Sample END PART END POLICY END CATEGORY
Keywords
The valid keywords within a DROPDOWNLIST section are the following ones:
DEFAULT
END
EXPANDABLETEXT
KEYNAME
NOSORT
REQUIRED
ITEMLIST
VALUENAME
EDITTEXT
The keyword EDITTEXT enables you to enter alphanumeric text into a text box. Policy editor stores the text in a REG_SZ value. A few keywords modify the behavior of the text box:
- DEFAULT.
Specifies the default value of the text box
- EXPANDABLETEXT.
Creates the value as a REG_EXPAND_SZ value
- MAXLENGTH.
Specifies the maximum length of the value
- REQUIRED.
Specifies that a value is required
Syntax
PART Name EDITTEXT [DEFAULT Default] [EXPANDABLETEXT] [MAXLENGTH Max] [REQUIRED] VALUENAME Value END PART
Name | This specifies the name of the setting as you want to see it in the policy's dialog box. Enclose the name in double quotes if it contains spaces. You see the name next to the text box. |
Default | This is the default value for the part. When you enable the policy, the policy editor fills the control with the default value. Use a default value that's appropriate for the part's type. |
Max | This is the maximum length of the value's data. |
Value | This is the registry value to modify. The policy editor creates this in the registry as a REG_SZ value and fills it with any text that you typed. |
Example
Listing 7-13 example.adm
CLASS USER CATEGORY "Sample Policies" EXPLAIN "These are sample policies that illustrate parts." POLICY "Sample Policy" SUPPORTED "At least Microsoft Windows XP Professional" EXPLAIN "This is a sample policy that illustrates creating a part." KEYNAME "Software\Policies" PART Sample EDITTEXT VALUENAME Sample END PART END POLICY END CATEGORY
Keywords
The valid keywords within an EDITTEXT section are the following ones:
DEFAULT
END
EXPANDABLETEXT
KEYNAME
MAXLENGTH
REQUIRED
VALUENAME
LISTBOX
The keyword LISTBOX adds a list box with Add and Remove buttons to the policy's dialog box. This is the only type of part that you can use to manage multiple values in one key. You can't use the VALUENAME option with the LISTBOX part because the option doesn't associate just a single value with the list. Use the following options with the LISTBOX part type:
- ADDITIVE.
By default, the content of list boxes overwrites values already set in the registry. That means that the Windows client-side extensions remove values before setting them. When you use this keyword, the client-side extensions do not delete existing values before adding the values set in the list box.
- EXPLICITVALUE.
This keyword makes you specify the value name and data. The list box shows two columns: one for the name and one for the data. You can't use this keyword with the keyword VALUEPREFIX.
- VALUEPREFIX.
The prefix you specify determines value names. If you specify a prefix, the policy editor adds an incremental number to it. For example, a prefix of Sample generates the value names Sample1, Sample2, and so on. The prefix can be empty (“”), causing the value names to be 1, 2, and so on.
By default, without using either the EXPLICITVALUE or VALUEPREFIX keywords, only one column appears in the list box. For each entry in the list, the policy editor creates a value using the entry's text for the value's name and data. For example, the entry Sample in the list box creates a value called Sample whose data is Sample. The default behavior is seldom a desirable result.
Syntax
PART Name LISTBOX [EXPANDABLETEXT] [NOSORT] [ADDITIVE] [EXPLICITVALUE | VALUEPREFIX Prefix] END PART
Name | This specifies the name of the setting as you want to see it in the policy's dialog box. Enclose the name in double quotes if it contains spaces. |
Prefix | This is the prefix to use for incremental names. If you specify a prefix, the policy editor adds an incremental number to it. For example, a prefix of Sample generates the value names Sample1, Sample2, and so on. The prefix can be empty (""), causing the value names to be 1, 2, and so on. |
Example
Listing 7-14 example.adm
CLASS USER CATEGORY "Sample Policies" EXPLAIN "These are sample policies that illustrate parts." POLICY "Sample Policy" SUPPORTED "At least Microsoft Windows XP Professional" EXPLAIN "This is a sample policy that illustrates creating a part." KEYNAME "Software\Policies" PART Sample LISTBOX EXPLICITVALUE END PART END POLICY END CATEGORY
Keywords
The valid keywords within a LISTBOX section are the following ones:
ADDITIVE
END
EXPANDABLETEXT
EXPLICITVALUE
KEYNAME
NOSORT
VALUEPREFIX
NUMERIC
The keyword NUMERIC enables you to enter alphanumeric text by using a spin box control that adjusts the number up and down. Group Policy Editor stores the number in a REG_DWORD value, but you can change the value's type to REG_SZ using the keyword TXTCONVERT. A few other keywords modify the behavior of the text box:
- DEFAULT.
Specifies the initial value of the text box.
- MAX.
Specifies the maximum value. The default is 9999.
- MIN.
Specifies the minimum value. The default is 0.
- REQUIRED.
Specifies that a value is required.
- SPIN.
Specifies the increment to use for the spin box control. The default value is 1, and using 0 removes the spinner control.
- TXTCONVERT.
Writes values as REG_SZ values rather than as REG_DWORD.
Syntax
PART Name NUMERIC [DEFAULT Default] [MAX Max] [MIN Min] [REQUIRED] [SPIN] [TXTCONVERT] VALUENAME Value END PART
Name | This specifies the name of the setting as you want to see it in the policy's dialog box. Enclose the name in double quotes if it contains spaces. You see the name next to the text box. |
Default | This is the default value for the part. When you enable the policy, the policy editor fills the control with the default value. Use a default value that's appropriate for the part's type. |
Max | This is the maximum value. The default is 9999. |
Min | This is the minimum value. The default is 0. |
Value | This is the registry value to modify. The policy editor creates this in the registry as a REG_DWORD value, setting it to the value that you specify in the dialog box. To change the value's type to REG_SZ, use the keyword TXTCONVERT. |
Example
Listing 7-15 example.adm
CLASS USER CATEGORY "Sample Policies" EXPLAIN "These are sample policies that illustrate parts." POLICY "Sample Policy" SUPPORTED "At least Microsoft Windows XP Professional" EXPLAIN "This is a sample policy that illustrates creating a part." KEYNAME "Software\Policies" PART Sample NUMERIC DEFAULT 11 MIN 10 MAX 20 VALUENAME Sample END PART END POLICY END CATEGORY
Keywords
The valid keywords within a NUMERIC section are the following ones:
DEFAULT
END
KEYNAME
MAX
MIN
REQUIRED
SPIN
TXTCONVERT
VALUENAME
TEXT
The keyword TEXT adds static text to the bottom part of the policy's dialog box.
Syntax
PART Text TEXT END PART
Text | This is the text you want to add to the dialog box. |
Example
Listing 7-16 example.adm
CLASS USER CATEGORY "Sample Policies" EXPLAIN "These are sample policies that illustrate parts." POLICY "Sample Policy" SUPPORTED "At least Microsoft Windows XP Professional" EXPLAIN "This is a sample policy that illustrates creating a part." KEYNAME "Software\Policies" PART "This is sample text added to the dialog box." TEXT END PART END POLICY END CATEGORY