Improved compatibility of ClearQuest with Windows 7 and Windows Server 2008 R2

Content

Rational ClearQuest Version 7.1.2 introduces changes that improve compatibility and usability with User Account Control (UAC) for Microsoft Windows 7 and Microsoft Windows Server 2008 R2.

---

I. Background

II. Problem statement

III. Workarounds

IV. Non-workarounds

V. Changes in ClearQuest to support UAC

VI. Summary of program privilege elevation changes in ClearQuest 7.1.2 running on Windows 7

---

I. Background

Rational ClearQuest stores information about schema repositories (also referred to as connections) in the Windows registry. The default behavior is to store the schema repository information in the HKEY Local Machine (HKLM) key. The policy of storing schema repository information in the Windows registry allows one user to add repositories for all users of the host to access. The default behavior is necessary for any ClearQuest services that run as the local system account because that account cannot use the ClearQuest Maintenance Tool to add its own repositories.

The Maintenance Tool is used to add, modify, delete, move, copy, and upgrade schema repositories (also referred to as master databases). The connection information for these repositories is stored in the Windows registry. You can use the ClearQuest Designer to add additional user databases to the repository. The connection information for these databases is also stored in the Windows registry. When the ClearQuest for Windows client or the Eclipse RCP-based ClearQuest Client connect to the user database, the entire list of databases in that repository is refreshed in the registry based on the values stored in the master database. If a database administrator moves a user database or logs on to a moved database on a given host, all users on the host can connect to the user database because the HKLM key is automatically refreshed during the move or log-on operation.

---

II. Problem statement

A Windows feature introduced in Windows Vista, User Account Control (UAC), protects the HKLM registry key from programs that do not have the authority to change it. As the result, ClearQuest versions earlier than 7.1.2 do not function properly on Windows 7 and Windows Vista unless the UAC feature is disabled. Disabling UAC, which is generally discouraged for security reasons, allows these ClearQuest versions to function as they do in earlier versions. However, even with UAC disabled, you must be a Windows administrator (a built-in administrator, or a member of the Administrator group) to perform operations that modify the HKLM key.

The errors you see when using ClearQuest without administrative privileges depend on which program you use. When you use the Maintenance Tool to create or import repositories, the operation fails with an error stating that the tool cannot modify the HKLM and HKEY Current User (HKCU) keys, although the tool only attempted to modify the HKLM key. When you use the Designer to create a new user database or a test database, a similar error displays stating that the tool cannot modify the registry. An error also displays if you use the ClearQuest for Windows client or the Eclipse RCP-based ClearQuest Client. This is because these clients try to refresh the databases in the HKLM registry key when you log on.

---

III. Workarounds

Two workarounds are available. One is to run processes as an administrator. The other is to set a behavior flag that instructs ClearQuest to use the HKCU registry key and the HKLM key.

• Running processes as an administrator

To use ClearQuest with UAC enabled, you must run ClearQuest processes by using the Run as administrator option. Using this option displays the UAC consent or user authentication window . If consent or authentication is successful, the program runs with elevated process tokens, allowing the previously mentioned registry changes.

You can also use ClearQuest command-line tools such as installutil and multiutil to modify the registry. To run these tools, you need to run in a command shell that was started by using the Run as administrator option. Tools that run in such command shells are automatically granted privileges to make registry changes.

The following screen capture illustrates how to start an elevated command shell.

• Using the HKCU and HKLM registry keys

The previous workaround requires that the you have access to an administrative account on the host computer. Some users do not have such account access. As an alternative, you can enable the USE_BOTH_HKCU_AND_HKLM behavior flag. This instructs ClearQuest to use both the HKCU and HKLM registry keys.

When the USE_BOTH_HKCU_AND_HKLM behavior flag is enabled, ClearQuest writes to the HKCU key if the HKLM key is not modifiable. Once ClearQuest writes to the HKCU key, any databases registered in the HKLM key are no longer available. These databases need to be imported again so that they are available in the HKCU key. This also means that any databases that are added to the registry in this way can only be seen by this user. This behavior might be desirable on host computers shared by many users who do not use the same schema repositories and user databases.

There are several ways to set the USE_BOTH_HKCU_AND_HKLM behavior flag.
• The most common way is to set the registry key. For example:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Rational Software\ClearQuest\Diagnostic]
"Behavior"="USE_BOTH_HKCU_AND_HKLM"

• Another way to set the behavior flag is to set the CQ_DIAG_BEHAVIOR system environment variable. To do this, you must use a account with administrative privileges.
1. Right click My Computer and select Properties.
   
2. Click Advanced system settings.
   
3. Select the Advanced tab.
   
4. Click Environment Variables.
   
5. Click New and enter the values specified in the following screen capture.
   
   
   
6. Click OK.
   
7. Click OK again until you dismiss all the windows.

Now all new programs will use this behavior flag. Any existing command shells and programs continue to use older versions of the environment variables.

To confirm that the CQ_DIAG_BEHAVIOR environment variable exists, run the command set in a command-prompt window. Look for CQ_DIAG_BEHAVIOR=USE_BOTH_HKCU_AND_HKLM in the output. Now all databases will be registered in HKCU for non-administrative users.

---

IV. Non-workarounds

Disabling UAC on Windows 7 or Windows Vista does not resolve this issue. The reason is that UAC functions as a notification system. UAC notifies you when privilege elevation is needed or requested. If UAC is disabled, the notification system is disabled but the underlying resources like the HKLM key and system files are still protected. You still need administrative privileges to add or modify databases in the HKLM key.

---

V. Changes in ClearQuest to support UAC

Starting in Version 7.1.2, ClearQuest introduces basic support for UAC:

1. Administrative programs that modify the registry, such as the Designer and the Maintenance Tool, automatically request privilege elevation. This behavior occurs instead of requiring you to select Run as administrator. The privilege-elevation request occurs only if you are an administrator or a member of the administrator group. If you are not an administrator, you are allowed to run the tools. However, you are not allowed to perform operations that require a registry change. Instead, an error message displays.
   
2. Administrative programs that need to modify the HKLM registry key, but are not elevated, return a more informative error message that the program needs to be run by someone with administrative privileges. This replaces the previous error message that only stated that you could not modify a registry key.
   
3. Non-administrative programs, such as the ClearQuest for Windows client, can run even though they cannot refresh the registry. Note that if the registry cannot be refreshed and a database has moved, the registry will contain stale information. You will not be able to log on in this case because the registry needs to be refreshed.
   
4. Command-line tools that run in a command window and require administrative privileges must be run from an administrative command window. Otherwise, the commands fail and display an error message. Tools that run in a command window do not prompt for a consent or authorization, in keeping with Microsoft console behavior.
   
5. ClearQuest programs do not trigger Program Compatibility Analysis (PCA) warnings. These are warnings that display when a program exits, for example, "This program may not have been installed correctly...". This is true for any program that has "install" or "setup" in the name, such as installutil or cqdbsetup (Maintenance Tool).
   
6. The multiutil program requires full administrative privileges to ensure that it can write to the registry. The tool fails and displays an error message if it does not have full administrative privileges. This prevents the multiutil command from failing in the middle of an operation due to registry issues, which could leave the database in an inconsistent state.

---

VI. Summary of program privilege elevation changes in ClearQuest 7.1.2 running on Windows 7

The following table lists several ClearQuest programs and how they are elevated in Windows 7.

Program	Elevation type1	Notes
ClearQuest for Windows client	Manual	Refreshing database connection parameters requires elevation. *
ClearQuest Client (Eclipse RCP-based)	Manual	Refreshing database connection parameters and adding new schema repositories require elevation. *
Legacy Designer	Automatic when run by an administrator	Creating or moving databases or modifying database properties requires elevation.
Designer 7.1	Manual	Cannot create new databases unless elevated.
installutil **	Manual	Operations that move, modify, add databases, set database connect options, and upgrade the system version require elevation. Elevation is automatic when running in an administrative command shell.
multiutil **	Manual/required	All operations require elevation, such as running in an administrative command shell.
Maintenance Tool	Automatic when run by an administrator	Creating, moving, renaming, removing, or adding repositories requires elevation. Upgrading databases requires elevation if the upgrade is not in place.
packageutil **	Manual	The registerpath and registerpackage subcommands require elevation.

* Failure to refresh connection parameters prevents access to the database.

** This is a command-line tool. Running a command-line tool requires running it in an elevated command shell. You can do this by right clicking on the command-prompt program and selecting Run as administrator.


¹ Elevation types

• Manual: Elevation must be manually requested. For GUI applications, this means right-clicking on the application and selecting Run as administrator. For command-line tools, elevation occurs only if the command shell was started by selecting Run as administrator. To elevate command-line tools in a scheduled task, the task must be configured to run as an administrative user and to Run with highest privileges.

• Automatic when run by an administrator: If you are a member of the administrator group, Windows requests elevation when the program is run. Otherwise, elevation occurs only when it is set manually.