Windows Agent Installation

This article covers how to install the ControlUp for Desktops Agent onto Windows devices.

Supported Windows OS versions

The following Windows versions support the latest GA Agent:

• Windows 10 Version 1607+ (x64)
• Windows 11
• Windows Server 2016 or higher

Download the Agent Manager

We recommend that you install the Agent using the Agent Manager. The Agent Manager installs the Agent and automatically keeps it updated according to your version control settings. By default, the Agent Manager installs the latest GA version of the Agent.

To download the Agent Manager, go to Configuration > Downloads > Windows Agent and click Download.

If you don't want to use the Agent Manager, you can directly download the latest Agent MSI at the bottom of the Downloads page. If you don't install the Agent Manager, you can't use the version control feature. If you enable version control in your ControlUp settings, all Agents automatically install the Agent Manager.

Installation methods

There are multiple methods to install the Agent Manager.

• Interactive GUI installation - Note that this installation method does not include as many customization options.
• Command line installation - This method gives you more customization options, and lets you deploy the Agent Manager onto many devices at once.
• Cloning a Windows image - If you are deploying the Agent Manager by cloning a Windows image, follow the command line installation instructions. Note that you must add the ONLYSTARTONBOOT=1 parameter to the command if you are installing the Agent Manager onto a device that will be cloned.

Interactive GUI installation

To install the Agent Manager onto a device using the interactive GUI installer:

1.  Run the agentmanagersetup.msi file you downloaded from the Downloads page.
2. Click Next to confirm that you agree to ControlUp's End User License Agreement.
3. Click Install to install the Agent Manager.
4. Copy your Tenant Name (located on the Downloads page) and paste it into the tenant name field in the Agent Manager Setup window.
   1. Optionally, if you want the Agent to connect to your tenant using a proxy, select Use HTTPS Proxy and enter the proxy IP address and port number.
   2. Click Test to make sure that your device can reach your tenant with a GET request. If this test fails, make sure you meet the Agent prerequisites.
5. Copy your Device Registration Code (located on the Downloads page) and paste it into the device registration code field in the Agent Manager Setup window. Click Check to make sure that the code is correct. This check sends a POST request to your tenant. If this check fails even though the code is entered correctly, make sure you meet the Agent prerequisites.
6. Click OK to save the tenant name and device registration code you entered.
7. Click Finish after the installation has been completed.

The Agent Manager and Agent are now installed on your device. The Agent automatically connects to your environment and you can view your device in ControlUp.

Command line installation

To install the Windows Agent Manager from the command line:

1. After downloading the Agent Manager, copy the msiexec command on the Downloads page. This command already includes your unique tenant name and device registration code.
   
2. Optionally, add the following parameters to the msiexec command:
   • PROXY sets a web proxy IP address and port number for Agent communication. For example, PROXY=10.0.0.1:8080.
   • PROXY_TEST_IP sets an IP address to test before using the proxy server configured in the PROXY parameter. Read Proxy server configuration below for details.
   • GROUP sets the device group the device. For example, GROUP=Finance. You can use device groups to organize devices which can be useful when filtering data, performing actions, configuring Agent version control, and more. Learn more about device groups.
   • ONLYSTARTONBOOT=1 sets the Agent to not automatically start after the Agent is installed. You must use this option if you are installing the Agent onto a Windows image for cloning (for example, using Citrix PVS/MCS). The Agent starts and connects to your environment on the first boot of the cloned image.
     
     
     Example

     The following example shows you how you would configure each of these parameters on the command-line.

     msiexec /i agentmanagersetup.msi /qn DEVREGCODE=<SampleCode> TENANT=<TenantName>.sip.controlup.com ALLUSERS=1 PROXY=10.0.0.1:8080 PROXY_TEST_IP=1.2.3.4 GROUP=Finance ONLYSTARTONBOOT=1

3. After setting any additional parameters, run the command on a device to install the Agent Manager onto the device.

The Agent Manager and Agent are now installed on your device. The Agent automatically connects to your environment and you can view your device in ControlUp.

Proxy server configuration

You can configure the Agent to use a proxy server to connect to your tenant. If you want the Agent to only use a proxy when the device is in a certain location (like your company's offices), you can set a proxy test IP address. Every time the Agent starts, it pings the test IP address. If the Agent receives a response, it uses the proxy. If the Agent does not receive a response, it does not use the proxy.

If you don't configure a proxy, the Agent uses the proxy in the system-level environment variable HTTPS_PROXY (if one is set). If you do configure a proxy for the Agent, it is used instead of the proxy in the environment variable. You can configure the Agent to never use a proxy, regardless of environment variables, by setting `ProxyAddress` to 0 in the registry. Read below for details on how to do this.

To configure a proxy server during Agent installation, follow the instructions above for either Interactive GUI installation or Command line installation. Note that the interactive GUI installer doesn't give you the option to add a proxy test IP address during installation.

To configure a proxy server for an existing Agent, you can use the Registry Editor:

•   To set the proxy server, go to Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Avacee\SIP and add a string (REG_SZ) ProxyAddress. Set the value of ProxyAddress to the proxy IP and port number (for example, 10.0.0.1:8080).
• To set a test IP address, go to Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Avacee\SIP and add a string (REG_SZ) proxy_test_ip. Set the value of proxy_test_ip to the IP address to test (for example, 127.0.0.1). If you set a test IP address, the Agent uses the proxy configured in ProxyAddress only if it receives a response from a ping to the test IP address when the Agent starts.
• To configure the Agent to never use a proxy, regardless of environment variables, set the value of ProxyAddress to 0.

Scripted Agent uninstall

You can use the following PowerShell script to uninstall the Agent.

$Command = "c:\Windows\System32\msiexec.exe"

### to fully uninstall Agent Manager ###
$Params = "/x {2AE0BDC4-26B3-4352-81EA-F4811B5B9B60} /norestart /qn"
$ParamsArray = $Params.Split(" ")
& "$Command" $ParamsArray

### to fully uninstall SIP Agent ###
$Params = "/x {0EE8541E-2D9F-4382-820F-DE7B93F7ED53} /norestart /qn"
$ParamsArray = $Params.Split(" ")
& "$Command" $ParamsArray

You can run the the uninstallation script directly from ControlUp:

1. Under Configuration > Scripts click Add Script and add the PowerShell script provided above. See the Scripting Guide for more information.
2. Schedule when the script should run. For example, you can select the System - Once Per Day to run the script daily (the script will initially run a few minutes after you save it). If you want to run the script on only certain devices, set the script trigger to Custom Action. You can then run the action from ControlUp to uninstall the Agent from targeted devices.