-
Print
-
DarkLight
-
PDF
ControlUp Agent Installation
-
Print
-
DarkLight
-
PDF
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 2012 or higher, Windows 8 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:
- Open the console with a user that has the Add Machine permission.
- 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.
- 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.
- Download the MSI package from our Download Center.
- Open the Real-Time Console > Agent Settings > click the Copy button under Agents Authentication Key.
- 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.465 + provided authentication key:
msiexec /i ControlUpAgent-net45-x64-8.6.5.465-signed.msi /qn AUTHKEY={enter the your AuthKey here}
Silently install the 64-bit version agent 8.6.5.465 + provided authentication key. No restart after installation + log output:
msiexec.exe /i ControlUpAgent-net45-x64-8.6.5.465-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.465 + provided authentication key. Use a non-standard port and custom installation path:
msiexec.exe /i ControlUpAgent-net45-x64-8.6.5.465-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.465 + provided authentication key + use certificate for agent authentication:
msiexec /i ControlUpAgent-net45-x64-8.6.5.465-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:
-
A service cuAgent is created.
-
(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.
-
The following registry keys are added:
- Listening port
Path:HKLM\SOFTWARE\Smart-X{Version}\Agent
Key name: port
Type: DWORD - Authentication Key
Path:HKLM\SOFTWARE\Smart-X\ControlUp\Agent\Communication
Key name: AuthKey
Value: Authentication Key provided in the Agent installation
Type: REG_SZ - Service Options for cuAgent Service
Path:HKLM\SYSTEM\CurrentControlSet\Services\cuAgent
Key name: Different keys - 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 - Listening port
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
-
Open the Real-Time Console > Agent Settings > click the Copy button under Agents Authentication Key.
-
Enter the registry on the agent machine.
UnderHKLM\SOFTWARE\Smart-X\ControlUp\Agent\Communication
, add the copied authentication key to the AuthKey registry key.
-
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.