- Print
- DarkLight
- PDF
Connect to Your Machines
- Print
- DarkLight
- PDF
- New
Monitor and manage physical and virtual machines in your environment by installing the ControlUp Agent on your machines. The Agent lets you see real-time metrics of your machines, user sessions, processes, and much more information. Any machine with the Agent installed is considered a "managed machine".
You do not need to install the Agent on Linux machines. Instead, ControlUp gathers information from an SSH connection and a lightweight Linux Data Collector.
There are two main ways to install the Agent on a machine:
Agent Security
We recommend that you take precaution to secure the connection between the Agent and your Consoles / Monitors. Visit Agent Security Best Practices to learn more.
Machine Requirements
The ControlUp Agent can be installed on machines with:
- Windows 10 or higher
- Windows Server 2012 or higher
- .NET Framework 4.5 or higher
- Open inbound TCP port 40705 for communication with the ControlUp Console and ControlUp Monitor
Remote Agent Installation
You can remotely install the ControlUp Agent onto machines from the Console. Remote installation from the Console requires:
- You are signed in to the Console with a user that has Local admin privileges on the target machine where you want to install the Agent. Your user must also have Add Machine permission in your ControlUp security policy.
- Ping availability to the target machine.
- WMI availability to the target machine. Win32_ComputerSystem is used to retrieve information about the remote machine. Make sure that you allow WMI through your firewall. For more information, click here.
- RPC availability to the target machine. The administrative share (Admin$) must be reachable from the Console machine.
- The target machine has a resolvable DNS host name.
RPC and WMI availability are required only for the initial remote deployment of the Agent, and are not used for ongoing Agent communication.
If you can't meet these requirements in your environment, see Local Agent Installation below.
Install Agents from the Console
- Sign in to the Console with a user that has the permissions described above.
- In the Home ribbon, select Add Machines.
To add machines directly to a folder in your organization tree, right-click a folder and select Add > Machines.
In the Add Machines window, search for the machines that you want to add from your Active Directory. You can also search for machines by their IP addresses, or with a text file.
By default, ControlUp searches for machines using the DNS suffix configured in the Active Directory DNSHostName attribute of your account. You can specify an Alternate suffix to use a DNS suffix that is different from your domain name.Select the machine that you want to add and click Add. The pane on the right shows the machines currently selected for addition to ControlUp. You can:
- Hold ctrl or shift to select multiple machines.
- Click Add All to add every machine in your search result.
If you have multiple ControlUp Sites, select which site you want to add the machines to.
Click OK to confirm your selection. If the Deploy agents automatically option is enabled in your Agent settings, then the Agent is installed on the machines that you added. If the option is disabled, then right-click on the machine and go to Agent Control to install the Agent.
Install Agents on Hypervisor-Managed Machines
After you have added a hypervisor to ControlUp, you can see all machines managed by the hypervisor. To install the Agent on these machines, follow these steps:
In ControlUp, go to the folder where your added your hypervisor to view the machines managed by the hypervisor.
Select Install Agent on a machine. To install the Agent on multiple machines, you can ctrl-click or shift-click to select multiple machines and right-click > Deploy ControlUp Agent.
Select the folder where you want the machines to be added once the Agent is installed.
Optionally, you can change the Credentials used to install the Agents on the machines. If you change the credentials and click Scan. If the credentials have sufficient permission to install the Agent, the Description column updates to Done.
Click OK to install the Agent on the selected machines
Any VM with a status of "Unmanaged" does not have IP address information from the hypervisor, and therefore you can't install the Agent using this method.
Remote Agent Installation from the Monitor
If Deploy agents automatically is enabled in your Agent settings, the ControlUp Monitor automatically installs the Agent on a machine when a machine is in your Console organization tree, but does not have an Agent installed.
Remote Agent installation from the Monitor requires:
- The same network requirements as the Console described above.
- The domain identity (AD service account) used by the Monitor must have the Allow log on locally user right.
Local Agent Installation
You can locally install the ControlUp Agent on a machine with an MSI package. Use this feature if you can't meet the requirements for remote Agent installation in your environment.
Manual Installation with GUI
Download the Agent MSI package from our Download Center.
Open the Real-Time Console and go to Agent Settings and copy your Agents Authentication Key. The key is used to connect the Agent to your ControlUp environment.
Run the installation of the MSI package on the machine where you want to install the Agent.
During the installation, paste the authentication key that you copied from the Real-Time Console.
Complete the installation. The Agent is installed on the machine and the machine can be monitored from the Real-Time Console.
Command Line Installation with 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 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 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 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 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
When you install an Agent, ControlUp tests the machine and communication requirements. You can configure which tests are performed during Agent deployment in your Agent Settings. If there was a problem installing the Agent on a Machine, you can see an error message in the real-time grid describing the problem.
You can also check the connection status from your Monitors to your Agents by going to Settings > Monitors > Data Sources.
For detailed troubleshooting of specific problems you might have when installing Agents, visit Agent Failed to Install.