ZENworks Agent Cleanup Tool

Technical Reference

1.0 Overview

This document outlines the usage of the cleanup tool for all versions of ZENworks agents.

2.0 Prerequisites

Adhere to these prerequisites to ensure a successful cleanup.

The cleanup tool requires administrative privileges. For Windows 7 SP1 and newer operating systems, right-click and "Run as Administrator." Just being logged in as Administrator is not sufficient.
The cleanup tool is built with .NET 3.5, so the device on which it is run needs to have .NET 3.5 or better.
The self-extracting EXE contains other required DLLs that the tool set needs to function correctly, so the cleanup tool must be run from a folder containing all of the dependency files contained within the self-extracting EXE.
Please ensure that no Microsoft Windows updates or other installs or updates are running at the same time as the tool, since it calls msiexec to do some of its uninstall work.

NOTE:Because of the following impacts, it is recommended to use the ZENworks Agent Cleanup Tool (ZENworksCleanupToolPkg) only as a last option.

3.0 Impact

Initial preparation and executable outcome are provided below:

It is advisable to make all efforts to register the ZENworks agent to a ZENworks server, and deploy a system update to the agent before running the executable.
Running this executable will clear custom ZENworks settings like registry and cache settings.
Running this executable will uninstall the ZENworks agent.

Post cleanup, a reboot of the device is required to complete the uninstall process in preparation for a reinstall of the ZENworks agent.

NOTE:If the Reboot option is selected, clicking OK at the prompt to reboot restarts the machine. If the Reboot option is not selected, the prompt is just a notification and a manual reboot is required. These prompts display with or without the Silent option selected.

4.0 ZENworks Agent Cleanup Tool Usage

Reference the instructions and information below when running the executable.

Make sure that the user running the executable has sufficient rights, or else the ZENworks folders/files will not be accessible for deletion.

The executable MUST be “run as Administrator” on all operating systems. For Windows Vista and newer operating systems, just being logged in as an Administrator is NOT sufficient.
ZENworksCleanupToolPkg.exe is a winzip self-extractor package. Double-clicking it will allow the user to unzip the contents to the desired location, with the Start_ZENCleanUp.bat set to be launched automatically on extraction. The default path will be the %TEMP% folder.
The Start_ZENCleanUp.bat file will in turn launch the ZENworksCleanupTool.exe in GUI mode (by default). If the UI is NOT desired, then the “silent” option can be used to suppress the main configuration UI. There is an option “status” dialog/ui that can also be shown/hidden to give an update to where the cleanup tool is at in the overall process.
The GUI mode cleanup tool has check-box options for various operations and are as follows:
1. CORE ZENworks Agent Uninstall Options
  1. Silent: No screen output.
  2. Vanish: Delete the AgentCleanup.exe file (this executable) after next reboot.
  3. CASA:Remove casa files and registry keys.
  4. Restore Microsoft GINA:Restore msgina as the primary GINA. If the Novell client is also installed, this parameter will not have any effect.
  5. Reboot: Reboot after performing cleanup. Click OK at the prompt to auto-reboot.
    
    NOTE: Only one reboot is done if ZAA, ZFDE, and ZESM reboot options are selected.
2. CORE Location Awareness and ZESM Uninstall Options
  1. Silent:The only screen output is the confirmation to reboot.
  2. Reboot:Reboot after performing cleanup. Click OK at the prompt to auto-reboot.
    
    NOTE: Only one reboot is done if ZAA, ZFDE, and ZESM reboot options are selected.
3. Full Disk Encryption Uninstall Options
  1. Silent:No screen output.
  2. Show warning if encryption is in place:Regardless of the “silent” option, if encryption is still in place, this warning message can be shown indicating to the user that the drive(s) must be decrypted before FDE can be completely removed, so as to avoid data loss.
  3. Reboot: Reboot after performing cleanup. Click OK at the prompt to auto-reboot.
    
    NOTE: FDE may require a reboot after drives are decrypted and then the cleanup tool can complete the driver removal. This reboot option is in reference to any reboot AFTER the cleanup tool is done, so the reboot to remove encryption drivers is always required IF encryption is in place.
    
    NOTE 2: Only one reboot is done if ZAA, ZFDE, and ZESM reboot options are selected.
4. General Options
  1. Show Summary Status Dialog:This controls whether or not the summary dialog shows the status of the stages of the cleanup tool, which is independent of each cleanup action or component.
  2. ZENworks Uninstall Authentication:Removal of the CORE Location Awareness, ZESM, and ZFDE components requires a Novell Clean-up Support Key, Password, and Client “set” or a password (ZENworks Agent uninstall password, ZENworks Agent override password, or ZFDE Administrative password). The support key “set” can be obtained through a Service Request with Novell ZENworks support. If either of these components is selected for removal, then the authentication information MUST be provided.
    
    Show warning messages and dialogs for authentication: This controls whether or not a prompt is shown during the tool removal process if the authentication information is not provided in the GUI, command line option, or batch file. Additionally, if the authentication information is invalid, a dialog will be shown that prompts the user to re-enter valid authentication information. If this is NOT checked, then the tool removal will fail with an error indicating the authentication failed (if it was not valid or not provided).
    
    Key, Password, Client: This is required for tool removal of security components of ZENworks agent and can be obtained from a Novell Support representative.
    
    Administrative password: The options must be configured in ZCC, and the settings have to be applied to agent before they can be used. The options are either the ZENworks Agent uninstall password, ZENworks Agent override password, or the ZFDE Administrative password (in the FDE policy).
5. Cleanup Tool Output Log File Path: This is the path to the log files for each of the cleanup components, so each log file will go to this selected directory. The default is the same path the cleanup tool is executed from.
6. Output Settings to Batch File: This allows the administrator running the GUI version to select the options in the UI and then create a batch file with command line options to the cleanup tool for easier deployment. Simply browse for the path to save the batch file and select to “Generate Batch File”. If an existing file exists with that same name, it will be automatically overwritten.
When unzipping ZENworksCleanupToolPkg.exe, the user can choose not to launch the batch file by unchecking the option in the dialog, in which case, only the files will be extracted. The user can then manually launch ZENworksCleanupTool.exe with any of the supported parameters.
The cleanup tool can be executed as a command line tool. The GUI can update or create a batch file with the various options selected in the UI. Optionally, the following parameters can be used:

4.1 Usage

The table below describes the parameters that can be used when running the ZENworksCleanupTool.exe.

Example: ZENworksCleanupTool.exe –unZaa –casa –reboot –silent

Parameter	Description
-unZaa	Uninstall the CORE ZEnworks Adaptive Agent. If this option is specified, then by default all the other check-boxes are enabled, namely to remove ZFDE and ZESM.
-silent	No screen output for ZAA removal.
-casa	Remove CASA files and registry keys.
-restoreGina	Restore msgina as the primary GINA. If the Novell client is also installed, this parameter will not have any effect.
-vanish	Delete the AgentCleanup.exe file (this executable) automatically after the next reboot.
-logPath	Folder where the log files for each agent cleanup component will be saved.
-reboot	Reboot after performing cleanup. If this switch is not specified, the process will NOT reboot automatically. A reboot is still required before you can install the agent again, and to remove the locked files as these are marked to be deleted on the next reboot.
-unZfde	Remove the ZENworks Full Disk Encryption component.
-showEncryptedDataWarning	Regardless of the “silent” option, if encryption is still in place, this warning message can be shown indicating to the user that the drive(s) must be decrypted before FDE can be completely removed, so as to avoid data loss.
-unZesm	Remove the CORE Location Awareness component and ZENworks Endpoint Security Management component.
-hideAuthDialog	This will hide the prompt for authentication values in the event the removal of ZENworks security components is attempted. See the “support” parameter below for more information. If the authentication dialog is hidden and the values are required or the ones provided are invalid, then the cleanup tool will fail and not prompt a user to input correct values.
-hideStatusDialog	This will hide the summary status dialog. The default is to show the status dialog regardless of the “silent” parameter setting.
-support	If this parameter is passed, the next 3 text values are assumed to be the “key, password, and client” values used for authentication to allow cleanup tool removal of the ZENworks security components. If these are NOT passed and NOT specified in the UI and a tool removal of these components is attempted, then the cleanup will fail with a corresponding message. Either this parameter with the key “set” OR the “- chkUninstallPassword” is required, not both.
-chkUninstallPassword	If this parameter is passed, the next parameter is assumed to be the ZENworks Agent uninstall password, ZENworks agent override password, or ZFDE policy de- fined Administrative password. Additionally, the tool will default to use the uninstall password over any support key set information provided. You only need to specify this parameter or the “-support” with key set parameter. Not both.

4.2 Functions Performed by the Cleanup Tool

ZENworksCleanupToolPkg.exe is a self-extracting zip, which runs Start_ZENCleanUp.bat on extraction. The .bat file launches the ZENworksCleanupTool.exe in GUI mode. This EXE will in turn launch the AgentCleanup.exe and the InstallHelper.exe and performs the following operations.

Does ZFDE cleanup first, then ZESM, and then the ZAA.
Removes Service registry entries.
Removes all files, including locked files (this may only complete AFTER a reboot).
Terminates running processes.
Removes all msi entries related to ZENworks install/uninstall.
Removes other registry entries including com objects, typelibs, etc.
Restores GINA if specified.
Reboots the machine if specified (reboot is required for a complete cleanup process).

5.0 Legal Notice

For information about legal notices, trademarks, disclaimers, warranties, export and other use restrictions, U.S. Government rights, patent policy, and FIPS compliance, see https://www.microfocus.com/about/legal/.

The only warranties for products and services of Open Text and its affiliates and licensors (“Open Text”) are as may be set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. Open Text shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice.