ControlUp Agent Installation

Introduction

The ControlUp Agent is a key component in your ControlUp environment, allowing you to see real-time metrics of your machines, user sessions, processes and many more. Installing the agent converts an unmanaged (or agentless) machine to a managed machine. There are plenty of installation methods available to install the agent on a machine. In this article, all methods are explained in detail.

Agent Prerequisites

Before you can install an agent, the machine on which you deploy the agent must meet the following prerequisites:

• Windows Operating System. Windows Server 2008R2 or higher, Windows 7 or higher
• .NET Framework 4.5 or higher
• Open firewall ports, refer to the communication ports article.

How to Install the Agent

• via the Real-Time Console or
• via an MSI installer

Console-based Agent Installation

Before you install the agent on a machine using the Real-Time Console, make sure that the machine meets the following requirements:

• Local admin privileges on the target machine
• Ping to the remote machine must be available.
• WMI availability. Win32_ComputerSystem is used to retrieve information about the remote machine. Make sure to enable WMI through your firewall, for more information see here.
• RPC availability. The administrative share (Admin$) must be reachable from the Console machine.
• Resolvable DNS host name.

To install the agent from the console:

1. Open the console with a user that has the Add Machine permission.
2. Click Add Machines and select the machine you want to install the agent. CTRL / SHIFT click to select multiple machines. Press Add to add the selected machines, or click Add All to select all machines from the list. Click OK to confirm the selection.
   
3. The agent is automatically installed if the deploy agents automatically option is enabled in the Agent Settings.
   

MSI-based Agent Installation

Manual installation via GUI

The installation via an MSI package is the prefered way to install the agent, especially when opening firewall ports for RPC/SMB is not possible.

1. Download the MSI package from our Download Center.
2. Open the Real-Time Console > Agent Settings > click the Copy button under Agents Authentication Key.
3. Run the installation of the MSI package. In the Agent Authentication Key window, paste the copy authentication key.
   

Installation via msiexec

You can install the agent by using the command line.Msiexec.exe allows you to run the installation of the agent in different ways. In this section, we show you some examples of how you can install the agent:

Make sure you download the agent from our Download Center.

Silently install the 64-bit version agent 8.6.5.425 + provided authentication key:

msiexec /i ControlUpAgent-net45-x64-8.6.5.427-signed.msi /qn AUTHKEY={enter the your AuthKey here}

Silently install the 64-bit version agent 8.6.5.425 + provided authentication key. No restart after installation + log output:

msiexec.exe /i ControlUpAgent-net45-x64-8.6.5.427-signed.msi AUTHKEY={enter the your AuthKey here} /quiet /norestart /l*v C:\temp\agentinstallation.log

Silently install the 64-bit version agent 8.6.5.425 + provided authentication key. Use a non-standard port and custom installation path:

msiexec.exe /i ControlUpAgent-net45-x64-8.6.5.427-signed.msi AUTHKEY={enter the your AuthKey here} /qn PORT=40777 APPDIR="enter installation path"

Silently install the 64-bit version agent 8.6.5.425 + provided authentication key + use certificate for agent authentication:

msiexec /i ControlUpAgent-net45-x64-8.6.5.427-signed.msi /qn AUTHKEY={enter the your AuthKey here} CERTONLY=TRUE

When using CERTONLY=TRUE, you instruct the agent to only accept connections from the console / monitors that are configured to use the Certificate-based agent authentication if the relevant agent-side registry keys are not configured.

Agent Installation Flow

During the installation of the agent, the following steps are performed:

1. A service cuAgent is created.

2. (From v8.6) Creates a Windows firewall rule to add the listening port to the allowed ports list. Rule name: ControlUp Agent Port with local port 40705.

3. The following registry keys are added:

   1. Listening port
      Path: HKLM\SOFTWARE\Smart-X{Version}\Agent
      Key name: port
      Type: DWORD
   2. Authentication Key
      Path: HKLM\SOFTWARE\Smart-X\ControlUp\Agent\Communication
      Key name: AuthKey
      Value: Authentication Key provided in the Agent installation
      Type: REG_SZ
   3. Service Options for cuAgent Service
      Path: HKLM\SYSTEM\CurrentControlSet\Services\cuAgent
      Key name: Different keys
   4. Agent Version and Installation Path
      Path: HKLM\SOFTWARE\WOW6432Node\Smart-X\ControlUpAgent
      Key name: Version
      Value: Agent version
      Type: REG_SZ

   Path: HKLM\SOFTWARE\WOW6432Node\Smart-X\ControlUpAgent
   Key name: Path
   Value: Installation path
   Type: REG_SZ

Troubleshooting

This section outlines some common issues during the deployment of the agent.

Issue #1 - “The Agent Authentication Key is misconfigured”

This error appears when the agent was installed on the machine with the MSI package, but no authentication key was provided.

Solution

1. Open the Real-Time Console > Agent Settings > click the Copy button under Agents Authentication Key.
   

2. Enter the registry on the agent machine.
   Under HKLM\SOFTWARE\Smart-X\ControlUp\Agent\Communication, add the copied authentication key to the AuthKey registry key.
   

3. Re-connect the agent machine in the console.
   

Issue #2 - “Validating RPC availability. Failed to access \hostname\admin$”

This error usually appears when the firewall settings are not configured correctly. During the deployment of the Agent. Deploying the agent requires the logged in user on the console machine to be able to access the administrative share on the agent machine.

Solution

Make sure all required firewall ports are open. Refer to the communication ports article.