Extending Registry-Based Policy

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:

1. 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.

2. Load the template file into Group Policy Editor as you learn to do later in this chapter in the section “Deploying Registry-Based Policy.”

3. 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: CHECKBOX. Displays a check box. The REG_DWORD value is 0x01 if you select the check box or 0x00 if you clear it. COMBOBOX. Displays a combo box. DROPDOWNLIST. Displays a combo box with a drop-down list. The user can choose only one of the items in the list. EDITTEXT. Displays a text box that accepts alphanumeric input. The value is either REG_SZ or REG_EXPAND_SZ. LISTBOX. Displays a list box with Add and Remove buttons. This is the only type that can be used to manage multiple values in one key. NUMERIC. Displays a text box with an optional spin box control that accepts a numeric value. The value is a REG_DWORD value. TEXT. Displays a line of static text. It stores no data in the registry and is useful for adding help to the dialog box.
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