IBM Support

Upgrading to WinCollect 7.3.0: Reinstalling managed and stand-alone agents

Troubleshooting


Problem

Administrators who upgrade to WinCollect are advised to reinstall their WinCollect agents to ensure all reported issues can be applied by the installer. This technical note advises administrators how to complete a reinstallation of managed and stand-alone WinCollect agents to complete a V7.3.0 update.
Notice: Administrators who are installing WinCollect 7.3.0 Patch 1 do not need to use the Powershell utility outlined in this technical note. Administrators planning to upgrade to the latest WinCollect version can update directly to WinCollect 7.3.0 Patch 1 to avoid the issue outlined in this article. For more information, see the WinCollect 7.3.0 Patch 1 release notes.

Cause

Administrators are required to reinstall WinCollect when you upgrade to V7.3.0 to ensure that the following issues are mitigated:
 

 

Resolving The Problem

Upgrading to WinCollect V7.3.0 with the ReInstallWinCollect.ps1 PowerShell utility

The ReInstallWinCollect.ps1 PowerShell utility is intended to assist administrators with upgrades to Wincollect V7.3.0 on Windows hosts. The attached utility automates the install process to copy existing installation values and reinstall agents using the WinCollect V7.3.0 EXE for administrators who have large deployments of WinCollect agents. 

Before you begin
  • For managed WinCollect agents:
    1. Administrators must copy the existing WinCollect authorized service token from Admin > Authorized Services before you use the ReinstallWinCollect.ps1 utility.
      Note: The authorized service token cannot be expired and is assigned the User Role 'WinCollect' in the user interface.
    2. Administrators with managed WinCollect agents must install the WinCollect 7.3.0 SFS file on their QRadar Console before they run ReinstallWinCollect.ps1.
  • The ReinstallWinCollect.ps1 PowerShell utility is provided as-is to assist administrators with upgrades for managed or stand-alone WinCollect agents.
  • PowerShell must be run as local admin and users must run Set-ExecutionPolicy RemoteSigned to upgrade their WinCollect agents.
  • This script can be run on any Windows host installed with Windows Vista or later.
  • The utility is intended to run from a system drive, such as C:\, D:\, or E:\. The utility locates WinCollect installations and updates the WinCollect agent to WinCollect V7.3.0.
  • Backups of the following files are created in the current system directory:
    • For stand-alone agents, the AgentConfig.xml file is backed up.
    • For managed agents, the install_config.txt file is backed up.
  • Administrators are encouraged to review and validate the contents of the attached PowerShell utility to ensure it does not contain harmful code and conforms to your corporate security policies.
Procedure
  1. Download the ReinstallWinCollect PowerShell utility.
  2. Download a WinCollect agent install file for your Windows hosts:
    64-bit installer: QRADAR-AGENT-wincollect-7.3.0-24.x64.exe
    32-bit installer: QRADAR-AGENT-wincollect-7.3.0-24.x86.exe
  3. Copy the utility and the WinCollect agent installer to the system drive of your Windows host, such as C:\.
  4. Launch Microsoft Powershell as an administrator.
    Note: If you are logged in as a local admin, type the following command to open PowerShell as an administrator: start-process PowerShell -verb runas
  5. Type Set-ExecutionPolicy RemoteSigned.
  6. If prompted to update the policy, press Y to continue. For more information on Set-ExecutionPolicy, see https:/go.microsoft.com/fwlink/?LinkID=135170.
    image 5586
  7. Run the ReinstallWinCollect.ps1 script.
    • For managed WinCollect agents, you must include the authorized service token. For example, 
        .\ReInstallWinCollect.ps1 -Authtoken 0e32xxxx-xxxxx-xxxx-xxxx-xxxxxxxx9163
    • For stand-alone WinCollect agents, you can run the PowerShell utility without options. For example, 
        .\ReInstallWinCollect.ps1
      Note: If you experience errors running the ReInstallWinCollect.ps1 file, you might need to review the Security field properties. Right-click on the file and select Properties. In the Security field check Unblock and click Apply, then repeat this step.
      image 5591
  8. Wait for the upgrade to complete.

    Results
    The WinCollect agent is updated to V7.3.0. If you experience issues, administrators can contact QRadar Support for assistance.

Optional. Manually reinstalling a managed WinCollect V7.3.0 agent


Required software
Download the WinCollect V7.3.0 SFS file from IBM Fix Central for your QRadar version: Download the appropriate WinCollect agent install file for your Windows hosts:
Part 1: Install the WinCollect 7.3.0 SFS on the QRadar Console
The installation process restarts services on the Console, which creates a gap in event collection until services restart. Administrators can schedule the WinCollect upgrade during a maintenance window to avoid disrupting users
  1. Use SSH to log in to your Console as the root user.
  2. Copy the fix pack to the /tmp directory on the QRadar Console. If space in the /tmp directory is limited, copy the SFS to another location that has sufficient space, such as /root or /storetmp for QRadar V7.3.0 Consoles.
  3. To create the /media/updates directory, type the following command:mkdir -p /media/updates
  4. Change to the directory where you copied the patch file. For example, cd /tmp
  5. To mount the patch file to the /media/updates directory, type the following command:
    mount -o loop -t squashfs <patch file sfs name>.sfs /media/updates
  6. To run the patch installer, type the following command: /media/updates/installer
    Note: To proceed with the WinCollect Agent update, you must restart services on QRadar to apply protocol updates. The following message is displayed:
    WARNING: Services need to be shutdown in order to apply patches. This will cause an interruption to data collection and correlation.
    Do you want to continue (Y/N)?
  7. Type Y to continue with the update.

    During the update, the SFS installs new protocol updates. If your Secure Shell (SSH) session is disconnected while the upgrade is in progress, the upgrade continues. When you reopen your SSH session and run the installer again, the patch installation resumes. After the installation is complete, services are restarted, and the user interface is available.

    WARNING: Patch 144249 includes a new version of the WinCollect Configuration Server. If you do not restart the event collection service, agents cannot get new configurations and code updates.

  8. When prompted, select Y to restart services.
  9. To unmount the SFS file from the Console, type the following command: umount /media/updates

Part 2: Required information before you uninstall your agent
It is important for administrators to record values from the install_config.txt file. These values are required to ensure that duplicate managed agents are not created when you install the WinCollect exe file on your Windows host.

Before you begin
  • Administrators must record the ApplicationIdentifier and ConfigurationServer parameters on each Windows host with a WinCollect agent installed.
  • Optionally, administrators can copy the install_config.txt file to a safe location before they uninstall the WinCollect agent.
Procedure
  1. Log in to the Windows host with the WinCollect agent installed.
  2. Navigate to the WinCollect config directory.
    Note: The default installation path for this directory is C:\Program Files\IBM\WinCollect\config.
  3. Open the install_config.txt file.
  4. Record the value in the ApplicationIdentifier field.
  5. Record the value in the ConfigurationServer field. This value ensures the agent assigned to manage is using to receive its configuration updates.
  6. Open the command prompt as an administrator.
  7. To stop the WinCollect service, type: 
      net stop WinCollect
  8. To uninstall the WinCollect agent, type: 
      "msiexec /x{1E933549-2407-4A06-8EC5-83313513AE4B} REMOVE_ALL_FILES=True /qn"
  9. Confirm all of the files in the WinCollect install folder are removed.


Part 3: Installing the WinCollect agent on the Windows host

Before you begin
The following information is required before you can reinstall your WinCollect agent:
  • The WinCollect authorized service token from the QRadar Console (Admin > Authorized Services)
  • ApplicationIdentifier value from the install_config.txt file of your existing WinCollect agent.
  • ConfigurationServer value from the install_config.txt file of your existing WinCollect agent.
  • Installation path, if the administrator has defined a customized install path for WinCollect agents.

Procedure
  1. Copy the WinCollect agent installer to your Windows host.
  2. Open a command prompt as an administrator.
  3. Type the following command and replace required values: 
        wincollect-7.3.0-24.x64.exe /s /v" /qn AUTHTOKEN=<WinCollectAuthServiceToken> FULLCONSOLEADDRESS=<ConfigurationServerValue> HOSTNAME=<ApplicationIdentifier>"
    • AUTHTOKEN is the WinCollect authorized service token from your QRadar Console.
    • FULLCONSOLEADDRESS is the value from the ConfigurationServer= field from the install_config.txt. If the install_config.txt file lists ConfigurationServer=qradar.examplehost.com, then your installation command must use the same value.
    • HOSTNAME is the value from the ApplicationIdendifier from the install_config.txt. If the install_config.txt file lists ApplicationIdentifier=10.0.1.1, then your installation command must use the same value.

      Example:
      wincollect-7.3.0-24.x64.exe /s /v" /qn AUTHTOKEN=dd20fxxxx-xxxx-xxxx-xxxxx-xxxx1dd6b5e2 FULLCONSOLEADDRESS=qradar.examplehost.com HOSTNAME=10.0.1.1"
  4. Press Enter to install the agent.

    Results
    After the agent is installed, the configuration from the QRadar appliance is downloaded to the agent and the WinCollect service restarts to load the log source and destination information to provide Windows event to QRadar.

      Optional. Manually reinstalling a stand-alone WinCollect V7.3.0 agent

      This information is intended for administrators who are not familiar with PowerShell or want to manually update their agents.

      Before you begin
      Procedure
      1. Log in to the Windows host with the WinCollect agent installed.
      2. Navigate to the WinCollect config directory.
        Note: The default installation path for this directory is C:\Program Files\IBM\WinCollect\config.
      3. Open the install_config.txt file.
      4. Record the value in the ApplicationIdentifier field.
        Note: It is important for administrators to record the value exactly as displayed in the install_config.txt file.
      5. Open the command prompt as an administrator.
      6. To stop the WinCollect service, type: 
            net stop WinCollect
      7. Important. To prevent losing your configuration, ensure your agentConfig.xml file stored in a safe location before you uninstall the WinCollect agent in the next step.
      8. To uninstall the WinCollect agent, type: 
          "msiexec /x{1E933549-2407-4A06-8EC5-83313513AE4B} REMOVE_ALL_FILES=True /qn"
      9. Verify that all files are removed from the C:\Program File\IBM directory. The WinCollect directory should be removed.
      10. Copy the WinCollect agent installer to your Windows host.
      11. Type the following command to install your stand-alone WinCollect agent and include the ApplicationIdentifier value: 
            wincollect-7.3.0-24.x64.exe /s /v" /qn HOSTNAME=<ApplicationIdentifier>"
        Note: HOSTNAME in the installation command must match the value from the ApplicationIdendifier=field from the install_config.txt. If the install_config.txt file lists ApplicationIdentifier=10.0.1.1, then your installation command must use the same value. For example:
        wincollect-7.3.0-24.x64.exe /s /v" /qn HOSTNAME=10.0.1.1"
      12. To stop the WinCollect service, type: 
          net stop WinCollect
      13. Copy the AgentConfig.xml file to the WinCollect\config directory, with a default install that would be: "C:\Program Files\IBM\WinCollect\config"
      14. To start the WinCollect service, type: 
          net start WinCollect

        Results
        As the WinCollect service starts, the configuration from the QRadar appliance is loaded and the agent can provide Windows event to QRadar.

      Document Location

      Worldwide

      [{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SSBQAC","label":"IBM Security QRadar SIEM"},"ARM Category":[{"code":"a8m0z000000cwtwAAA","label":"WinCollect"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"All Version(s)","Line of Business":{"code":"LOB24","label":"Security Software"}}]

      Document Information

      Modified date:
      28 April 2021

      UID

      ibm16260883

      Page Feedback