Research In Motion 2002 Research In Motion Limited. All Rights Reserved.
Contents Overview... 1 Understanding the BlackBerry IT Policy feature... 2 Policy files and the BlackBerry Desktop Manager configuration... 2 Policy files and the BlackBerry handheld configuration... 2 Policy.inf file overview... 2 Default values... 3 Policy values... 3 Creating a BlackBerry IT Policy... 3 IT Policy Manager... 4 Editing the Policy.inf file... 4 Generating a policy.bin file... 4 Implementing BlackBerry IT Policies... 5 During the BlackBerry Desktop Software installation... 5 Scenario 1: The Policy.bin file is located in the desktop software installation directory... 5 Scenario 2: The Policy.bin file is not located in the desktop software installation directory... 6 After the BlackBerry Desktop Software installation... 7 Scenario 1: The Policy.bin file is located in the desktop software installation directory... 7 Scenario 2: The Policy.bin file is not located in the desktop software installation directory... 7 Bug resolutions... 8 The Policy.bin file in the installation directory does not work... 8 Functionality impact... 8 Workaround... 8 Status... 8 Appendix A: Policy.inf options... 9 BlackBerry Desktop Manager configuration... 9 Synchronization... 10 Redirector configuration... 12 Backup and Restore configuration... 13 Handheld security settings... 15 Message settings... 16 Owner information... 16
Overview With the release of BlackBerry Enterprise Server version 2.0, Research In Motion introduced a solution that enables administrators to define and enforce administrative policies, such as default configuration settings for both the BlackBerry Desktop Software and the BlackBerry Wireless Handheld. This functionality is facilitated through the IT Policy Manager, which is located in the \Tools directory on the BlackBerry Enterprise Server version 2.0 installation CD. This solution consists of the following key elements: Policy.bin: The policy file is used to enforce the desktop and handheld configuration parameters that are defined by the administrator. This file is in binary format and is generated by the IT Policy Manager program. Keyword.txt: This file is used to check the format of the policy.inf file and is also used to populate part of the ITPolicy.exe interface. Policy.inf: This is the source.inf file that is used to define the configuration parameters that are used to generate the Policy.bin file. ITPolicy.exe: This program file opens the IT Policy Manager, which provides an interface in which to edit the Policy.inf file, and a mechanism for generating or compiling the Policy.bin file. BlackBerry Desktop Software: This is the software for the BlackBerry solution. The BlackBerry Desktop Software reads the Policy.bin file each time that it is started. This information is then used to set policies and to communicate policy changes to the BlackBerry handheld. Note: This document provides specific information on which elements of the BlackBerry solution can be controlled, as well as how to implement and administer the IT policies. The following sections focus on the creation and deployment of the BlackBerry IT Policy files 2002 Research In Motion Limited www.blackberry.net Page 1 of 17
Understanding the BlackBerry IT Policy feature This section explains how the IT Policy feature interacts with the desktop software to define and enforce the customized configuration, with an emphasis on the Policy.inf and Policy.bin files. The discussion focuses on the features that affect the operation of the IT Policy Manager solution. This section is summarized by an overview of some common issues that users of this feature might encounter. Policy files and the BlackBerry Desktop Manager configuration BlackBerry policy files are used to define and distribute configuration changes to the BlackBerry Desktop Manager software and the BlackBerry handheld. The policy.bin file is generated based on the information that is defined in the policy.inf file. The policy.bin is, in effect, the policy file because it is the file that is used programmatically in the application of the policy. The BlackBerry Desktop Manager performs the application of policy changes based on the information it reads from the policy.bin or policy file. When the BlackBerry Desktop Manager is started, it queries a registry key to determine the path and file name of policy.bin file. The registry entry that is queried is: HKEY_CURRENT_USER\Software\Research In Motion\BlackBerry\Policy Manager\Path. The value that this registry query returns determines what happens next within the policy process. If this key exists and has a valid value, the BlackBerry Desktop Manager reads the specified file from the specified path to determine what IT Policy changes are required. If this key does not exist, or if the value is invalid (not found), then the BlackBerry Desktop Manager will try to find the policy.bin file in the root of the installation directory; for example, C:\Program Files\Research In Motion\BlackBerry. If no policy file is found, no policy changes are applied and all current settings remain unchanged. Assuming that the BlackBerry Desktop Manager is successful in locating the policy.bin file, it will read the policy.bin file. The application policy changes are determined by the value attribute, {default} or {policy}, and the time stamps of both the current settings and the policy file. Depending on the type of value attribute (default or policy) and the time stamp, a change might be applied. For more information on value attributes and policy processing, refer to the Policy.inf file overview section below. If the BlackBerry Desktop Manager does not find the policy.bin file either in the specified location or in its installation directory, it will proceed without making changes to the configuration. Policy files and the BlackBerry handheld configuration Changes to the BlackBerry handheld configuration are subject to the same rules as described above for the desktop manager configuration, with one exception. For policy changes to be affected on the BlackBerry handheld, it must be synchronized with the user s computer. When the synchronization of the handheld occurs, the BlackBerry Desktop Manager compares the policy values with those present on the handheld. If warranted, changes are made to the handheld configuration during synchronization. If the policy.bin file is not available when the BlackBerry Desktop Manager is started, no policy information will be available to update the handheld. This could be a concern for users who dial in or who often work offline. Policy.inf file overview The policy.inf file is a text file that contains the keys and values that are used to generate the policy.bin file. This file contains configuration options for many of the features of the BlackBerry Desktop Software and handheld. Each of the policy.inf options is described in detail in Appendix A: Policy.inf options. This section outlines the format of the policy.inf file and how to use the features to achieve the specific administrative goals. 2002 Research In Motion Limited www.blackberry.net Page 2 of 17
The policy.inf file is essentially a standard text file. This file has a number of specific formatting attributes that define specific types of actions. Comments can be added by placing a semicolon (;) at the start of the line. Line continuation for string values can be added by placing a backslash (\) at the end of the line. Value types supported by the policy.inf include Boolean (), integer (number values within the specified range), and string (lines of text). Values can have one of two attributes: default or policy. When generating a policy.bin file, Policy.inf files can contain all the keys, or as few as one. Default values Keys that have the default attribute are values that are set only once to configure settings. The BlackBerry Desktop Manager reads and applies these settings the first time that it reads the policy.bin file. When the BlackBerry Desktop Manager reads the policy.bin subsequent to the initial startup, it ignores the values associated with the default keys. To change a setting that has been set with a default attribute, change the value and assign the {policy} attribute. Features of values with the {default} attribute: Example: PasswordRequired {default} = or PasswordRequired = This is created by adding the {default} attribute or by adding no attribute at all, to the value in the policy.inf file. Default values are set only once, the first time that the desktop manager reads the policy.bin file. From this point forward, the value will remain the same. The only way to change a value with the default attribute is to change the value attribute to {profile} in the policy.inf file and regenerate the policy.bin file. The {default} attribute should be used to define and enforce values that are not going to change. Policy values Keys that have the policy attribute are values that are can be set when the policy.bin file is changed or updated. The BlackBerry Desktop Manager reads these settings each time that it reads the compiled policy file. If the setting's time stamp differs from that of the policy.bin file, the value defined in the policy.bin file will be applied. Features of values with the {policy} attribute: Example: PasswordRequired {policy} = This is created by adding the {policy} attribute to the value in the policy.inf file. Policy values are examined each time that the desktop manager starts and reads the policy.bin file. Values that have the {policy} attribute can be changed by altering the value in the policy.inf file and regenerating the policy.bin file. The {policy} attribute should be used for values that could be subject to change over the course of time. Creating a BlackBerry IT Policy The term policy file and policy.bin are used interchangeably when discussing the creation of BlackBerry IT Policies. The core file for implementing IT Policies with the BlackBerry solution is the policy.bin file and the policy.inf file is the file used to generate the policy.bin file. This section outlines the steps required to edit the policy.inf file and to generate a policy.bin file. 2002 Research In Motion Limited www.blackberry.net Page 3 of 17
IT Policy Manager The IT Policy Manager is used to generate the policy.bin file; the application also includes a text editor that can be used to make changes to the policy.inf files. This application and its supporting files can be located on the BlackBerry Enterprise Server installation CD, in the \tools directory. Although this application can be run from the CD, the procedure that is outlined below assumes that the application will be run from the C:\BBPolicy directory on a workstation. This can be accomplished by copying the contents of the \tools directory to a subdirectory on the local hard drive of the workstation on which the administration of the policy files will be performed. Editing the Policy.inf file This procedure describes the process of opening, editing, and saving the policy.inf file using the IT Policy Manager. This procedure assumes that the entire contents of the \tools directory on the BlackBerry Enterprise Server 2.0 installation CD have been copied to the C:\BBPolicy directory. 1. Open Windows Explorer and navigate to the C:\BBPolicy subdirectory. 2. Double-click the ITPolicy.exe file to start the IT Policy Manager. 3. On the File menu, click Open and select the policy.inf file from the C:\BBPolicy directory. Note: The screen that appears displays the full text of the policy.inf file. Complete details of each entry in this file are included in Appendix A of this document. 4. In the Device Security Settings section, select and change the value for the PasswordRequired {policy} from False to 5. On the File menu, click Save. This procedure can be used to change any of the values in the policy.inf file. Generating a policy.bin file The following procedure outlines the steps required to generate the policy.bin file using the IT Policy Manager and the C:\BBPolicy\policy.inf. Note: This procedure generates a policy.bin file based on the information provided in the policy.inf file. If the policy.inf file that is provided with the BlackBerry Enterprise Server version 2.0 is used, administrators should review each entry before generating the policy.bin file. Failure to perform this review might result in unexpected results. 1. Open Windows Explorer and navigate to the C:\BBPolicy subdirectory. 2. Double-click the ITPolicy.exe file to start the IT Policy Manager. 3. On the File menu, click Open. 4. Select the policy.inf file from the C:\BBPolicy directory. 5. On the Action menu, click Generate. 6. Click OK to confirm that the C:\BBPolicy\policy.bin file has been generated. 7. On the File menu, click Exit. The IT Policy Manager closes. 8. The policy.bin file has been generated based on the values defined in the source policy.inf file. At this point, the file can be deployed for use with the BlackBerry Desktop Manager software. 2002 Research In Motion Limited www.blackberry.net Page 4 of 17
Implementing BlackBerry IT Policies BlackBerry IT Policies can be implemented in several different ways. Each method is different because it is related to the administrative and deployment considerations of the BlackBerry solution. The following sections outline the options available for the deployment of these policies. IT Policy files can be implemented during or after the installation of the BlackBerry Desktop Software. This section describes the assumptions and steps required to deploy IT Policies in both situations. During the BlackBerry Desktop Software installation This method of deploying IT Policy files for the BlackBerry solution requires only one action at the desktop. In contrast, deploying IT Policies after the BlackBerry Desktop Software is installed requires interaction with the desktop platform to implement the IT Policy file. This section explains how to deploy IT Policies during the installation of the BlackBerry Desktop Software. Note: The following procedure assumes that the BlackBerry Desktop Software has been copied from the CD to a shared directory. It is also assumed that the person who is performing this task has both read and write access to the shared directory. Two scenarios exist for deploying the IT Policy file on the desktop. Scenario 1: The Policy.bin file is located in the desktop software installation directory. This scenario takes advantage of functionality that is provided by the desktop software. If no registry entry exists for the location and definition of a policy.bin file, the BlackBerry Desktop Software checks its installation directory for an occurrence of a policy.bin file. If this file is found, the settings that it contains are applied. This scenario depends on the policy.bin file being located in the installation directory of the BlackBerry Desktop Software. The following procedure explains how to distribute a predefined policy.bin file when installing the BlackBerry Desktop Software from a shared location. 1. Define and generate a policy.bin file. 2. Copy the policy.bin file to root of the shared installation folder. 3. Proceed with the software installation according to the BlackBerry Desktop Software installation instructions. If the installation is successful, the policy.bin file is placed in the installation directory of the BlackBerry Desktop Software. 2002 Research In Motion Limited www.blackberry.net Page 5 of 17
Scenario 2: The Policy.bin file is not located in the desktop software installation directory. This scenario defines a registry entry that the BlackBerry Desktop Software uses to find the location and name of the policy.bin file. The BlackBerry Desktop Software reads the file from this location and applies to the desktop software the setting that it defines. When the handheld is synchronized, the settings that are defined for the handheld are applied to the handheld settings. The following procedure explains how to create the appropriate registry entry in the user s registry when the BlackBerry Desktop Software is installed. 1. Edit the setup.ini file that is located in the root of the shared installation folder. 2. Locate the following entry: [Policy] PolicyPath= 3. Set this value to reflect the predefined location of the policy.bin file. Note: The value that is used for the setting must include the path and full name of the policy file. The path can either reference a drive\directory or UNC\directory combination, for example, C:\Policy\policy.bin or \\server\share\directory\policy.bin. 4. Save the file to its original location. 5. Proceed with the software installation according to the BlackBerry Desktop Software installation instructions. If the installation is successful, this scenario adds a registry key and value that references the path defined in the setup.ini file. The specific details of this registry entry are defined below. registry key HKEY_Current_User\Software\Research In Motion\BlackBerry\Policy Manager value Value Type= REG_SZ Value Name: Path Value As per the setup.ini file When the BlackBerry Desktop Software is run for the first time, the settings that are defined for the software settings are applied. Handheld settings are not applied until the handheld is synchronized with the desktop software. 2002 Research In Motion Limited www.blackberry.net Page 6 of 17
After the BlackBerry Desktop Software installation This section explains how to deploy IT Policy files after the BlackBerry Desktop Software is installed. This situation is representative of an organization that has deployed BlackBerry to several users and now requires the ability to configure specific components of the system according to corporate policy. This section explains how to successfully enable the IT Policy feature for existing BlackBerry Desktop Software installations. Note: The following procedures assume that the BlackBerry Desktop Software is installed and is fully functional. Two scenarios exist for deploying the IT Policy file in an existing BlackBerry Desktop Software installation. Scenario 1: The Policy.bin file is located in the desktop software installation directory. This scenario takes advantage of the functionality that is provided by the desktop software. If no registry entry exists for the location and definition of a policy.bin file, the BlackBerry Desktop Software checks its installation directory for an occurrence of a policy.bin file. If a file is found, its settings are applied. This scenario depends on the policy.bin file being located in the installation directory of the BlackBerry Desktop Software. The following procedure explains how to configure an existing BlackBerry Desktop Software installation to use the local policy.bin file that is located in the applications installation directory. 1. Define and generate a policy.bin file. 2. Copy the policy.bin file to the root of the desktop software installation directory, which is typically C:\program files\research In Motion\BlackBerry. If it is running, stop and restart the BlackBerry Desktop Software so that it recognizes the policy.bin file. After the file is recognized, its settings are applied to the software and the handheld. Note: The functionality afforded by scenario is only applicable if the HKEY_CURRENT_U\Software\Research In Motion\BlackBerry\Policy Manager\Path value is not present. If this value is present, it is used instead of the local policy.bin file. Scenario 2: The Policy.bin file is not located in the desktop software installation directory. This scenario defines the entries that must be added to the registry to define the location and name of the IT Policy file. After it is defined, the desktop software can locate, read, and apply the setting that is defined in the policy.bin file. Handheld settings are applied when the handheld is synchronized. The following outlines the steps required to create the appropriate registry entry within the users registry. 1. Add a subkey named Policy Manager to the following registry key: HKEY_Current_User\Software\Research In Motion\BlackBerry 2. Add a string (REG_SZ) value called Path to the Policy Manager subkey that you created in step 1. 3. Edit the value and enter the path and name of the policy.bin file. Note: The value used for the setting must include the path and full name of the policy file. The path can either reference a drive\directory or UNC\directory combination, for example, C:\Policy\policy.bin or \\server\share\directory\policy.bin. Changing the user s registry can be accomplished in several different ways: Define and distribute a.reg file that is executed by the user or in a login script. Manually define the entry with a registry editor at the user s desktop. Define and distribute an SMS installer package that includes the appropriate registry changes. The implementation of this change should be determined based on the mechanism of choice for a given environment. 2002 Research In Motion Limited www.blackberry.net Page 7 of 17
Bug resolutions The Policy.bin file in the installation directory does not work The BlackBerry Desktop Software version 2.1 Service Pack 2 introduced a bug that inhibits the use of a local policy.bin file placed in the installation directory of the BlackBerry Desktop Software. When the BlackBerry Desktop Software is installed, it creates shortcuts to the BlackBerry Desktop Manager on the user s start menu and on the desktop. For the functionality described above to work properly, the shortcut must have a valid directory in the Start In field. In this case, the directory must be the installation directory for the BlackBerry Desktop Software. Functionality impact This bug inhibits the implementation of policy files if the local policy.bin file is placed in the application installation directory. Workaround To work around this problem, in the Desktop Manager Properties window, on the Shortcut tab, in the Start In field, add the appropriate value as outlined in the procedure below. 1. On the desktop, right-click the Desktop Manager icon and click Properties. 2. In the Start In field, type the path to the installation directory. A typical value for this field would be C:\Program Files\Research In Motion\BlackBerry. 3. Click OK. Complete this task for all instances of the BlackBerry Desktop Manager shortcut. Status This has been identified as an issue with the BlackBerry Desktop Software version 2.1 Service Pack 2. It will be fixed in a later service pack. 2002 Research In Motion Limited www.blackberry.net Page 8 of 17
Appendix A: Policy.inf options This appendix provides a detailed description of each option that is available for creating the policy.inf file. BlackBerry Desktop Manager configuration HideWhenMinimized Determines whether or not the BlackBerry Desktop Manager application appears on the taskbar when it is minimized MessagePrompt Not applicable Welcome to the Desktop Manager. Not applicable EnableUSBconverter False Not applicable 2002 Research In Motion Limited www.blackberry.net Page 9 of 17
Synchronization SynchronizeNowPIM This setting enables you to specify whether or not you want PIM information to be synchronized when the user clicks Synchronize Now in the Intellisync window. SynchronizeNowEmail This setting enables you to specify whether or not you want email information to be synchronized when the user clicks Synchronize Now in the Intellisync window. SynchronizeNowDateTime This setting enables you to specify whether or not you want the date and time to be synchronized when the user clicks Synchronize Now in the Intellisync window. AutoSynchronizePIM False This setting enables you to specify whether or not you want PIM information to be synchronized automatically when the handheld is connected to the computer. 2002 Research In Motion Limited www.blackberry.net Page 10 of 17
AutoSynchronizeEmail False This setting enables you to specify whether or not you want email information to be synchronized automatically when the handheld is connected to the computer. AutoSynchronizeDateTime False This setting enables you to specify whether or not you want date and time information to be synchronized automatically when the handheld is connected to the computer. SyncFoldersInsteadOfImport This setting enables you to specify whether or not you want to synchronize folders instead of performing an import. FolderConflictDesktopWins This setting enables you to specify how information conflicts that occur between the handheld and the computer during synchronization are handled. If set to true, desktop information is used. If set to false, handheld information is used. 2002 Research In Motion Limited www.blackberry.net Page 11 of 17
Redirector configuration AutoSignature Not applicable ----------------- Sent from my BlackBerry Handheld This setting appends a signature onto outgoing messages. ForwardMessagesToHandheld This setting determines whether to forward messages to the handheld. ForwardMessagesInCradle False This setting determines whether users receive mail when the handheld is inserted in cradle. FilterRuleFile Not applicable c:\temp\test.rfi This setting sets up filter rules for email redirection. 2002 Research In Motion Limited www.blackberry.net Page 12 of 17
ForwardWhenRulesDontApply When filter rules do not apply, this setting determines whether to forward or not send messages. DontSaveSentMessages False When sending a message from handheld, this setting specifies whether or not to save a copy in the user s Sent Items folder. Backup and Restore configuration AutoBackupEnabled This value controls the value of the Automatically backup my handheld check box in the Backup and Restore Options window, which enables or disables automatic backups. AutoBackupFrequency 1 to 99 7 This value indicates how often an automatic backup is performed, in days. 2002 Research In Motion Limited www.blackberry.net Page 13 of 17
AutoBackupIncludeAll This setting controls the exclusion of email and synchronized data from the automatic backup. If set to true, the Backup all handheld application data radio button is selected. AutoBackupExcludeEmail False This setting determines whether email is excluded from automatic backups (when AutoBackupIncludeAll is false). AutoBackupExcludeSync False This setting determines whether synchronized application data is excluded from automatic backups (when AutoBackupIncludeAll is false). "Synchronized data" is data which is configured for synchronization with Intellisync; this varies according to the user's preferences. 2002 Research In Motion Limited www.blackberry.net Page 14 of 17
Handheld security settings PasswordRequired {policy} This setting determines whether a password is required on the handheld. UserCanDisablePassword This setting determines whether the user can disable the password. MinPasswordLength {policy} 1 to 12 5 This setting determines the minimum length of the password. The valid range is 1 to 12 characters, inclusive. This value indicates the minimum length of an acceptable handheld security password. MaxSecurityTimeout {policy} 1 to 60 60 This setting determines the maximum handheld security timeout. The valid range is 1 to 60 minutes, inclusive. The handheld user is permitted to select any security timeout value less than this value. 2002 Research In Motion Limited www.blackberry.net Page 15 of 17
UserCanChangeTimeout {policy} This setting determines whether the user can change the timeout length. MaxPasswordAgeInDays {policy} 0 to 365 5 Specifying a value of 0 indicates that password aging is disabled. Other values specify the maximum age of the password before the handheld user is prompted to change it. Message settings AllowPINtoPIN {policy} This setting indicates whether PIN-to-PIN messaging is permitted. If it is set to true, handheld users are permitted to use the PIN-to-PIN messaging feature. If it is set to false, this capability is hidden from the handheld user. Owner information OwnerName {default} Not applicable Not applicable 2002 Research In Motion Limited www.blackberry.net Page 16 of 17
Part Number: TAE-00047-001 2002 Research In Motion Limited. All rights reserved. The BlackBerry and RIM families of related marks, images and symbols are the exclusive properties of Research In Motion Limited. RIM, Research In Motion, 'Always On, Always Connected', the envelope in motion symbol and the BlackBerry logo are registered with the U.S. Patent and Trademark Office and may be pending or registered in other countries. All other brands, product names, company names, trademarks and service marks are the properties of their respective owners. The handheld and/or associated software are protected by copyright, international treaties and various patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D,445,428; D,433,460; D,416,256. Other patents are registered or pending in various countries around the world. Please visit www.rim.net/patents.shtml for a current listing of applicable patents. RESEARCH IN MOTION LIMITED (RIM) ON BEHALF OF ITSELF AND ITS AFFILIATES MAKES NO REPRESENTATIONS ABOUT THE SUITABILITY OF THE INFORMATION OR GRAPHICS CONTAINED IN THIS ADVISORY FOR ANY PURPOSE. THE CONTENT CONTAINED IN THIS DOCUMENT, INCLUDING RELATED GRAPHICS, ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. RIM HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS WITH REGARD TO THIS INFORMATION, INCLUDING ALL IMPLIED WARRANTIES AND CONDITIONS OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT SHALL RIM BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF INFORMATION CONTAINED HEREIN. THIS DOCUMENT, INCLUDING ANY GRAPHICS CONTINED WITHIN THE DOCUMENT, MAY CONTAIN TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. UPDATES ARE PERIODICALLY MADE TO THE INFORMATION HEREIN AND RIM MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED HEREIN AT ANY TIME. 2002 Research In Motion Limited www.blackberry.net Page 17 of 17