Connect to Your Machines
    • Dark
      Light
    • PDF

    Connect to Your Machines

    • Dark
      Light
    • PDF

    Article summary

    Monitor and manage physical and virtual Windows 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".

    Linux Machines

    There is no agent for Linux machines. Instead, we use SSH and a lightweight Linux Data Collector.

    There are two main ways to install the Agent on a machine:

    To learn how to add machines, watch our video.

    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 2016 or higher.
    • .NET Framework 4.5 or higher. Version 9.0 requires .NET Framework 4.8
    • Open inbound TCP port 40705 for communication with the ControlUp Console and ControlUp Monitor.
    • If you want to use the new outbound communication feature for your agents and they have Internet connectivity, ensure they can access the URLs mentioned here.
    • If you use a Microsoft Entra ID (previously known as Azure Virtual Desktop or AVD) environment for ControlUp Hybrid Cloud, ensure your cloud network has internet access for the resources defined for Hybrid Cloud.
    • If you use a Microsoft Entra ID environment for ControlUp On-premises (COP), ensure your cloud resources have a VPN to your COP environment in your local network.

    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.
    Note

    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

    1. Sign in to the Console with a user that has the permissions described above.
    2. In the Home ribbon, select Add Machines.

    Tip

    To add machines directly to a folder in your organization tree, right-click a folder and select Add > Machines.

    1. 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.

    2. 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.

    1. If you have multiple ControlUp Sites, select which site you want to add the machines to.
    2. 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:

    1. In ControlUp, go to the folder where your added your hypervisor to view the machines managed by the hypervisor.

    2. 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.

    3. Select the folder where you want the machines to be added once the Agent is installed.

    4. 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.

    5. Click OK to install the Agent on the selected machines

    Note

    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.

    • From version 9.0, this option doesn't apply to monitors. If you select this option, the console still automatically deploys the agents.
    • From versions lower than 9.0, the AD account used by the monitor requires admin rights on the machines to deploy the agent.

    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.
      Removed AD Dependency
      From version 9.0, you can deploy ControlUp Monitors on machines that are not joined to a local Active Directory (AD) domain. For details, see Removed AD Dependency for Monitors.

    Local Agent Installation

    Install the ControlUp Agent locally on a machine using an MSI package if remote installation requirements cannot be met in your environment.

    To learn more about the MSI Deployment, watch our video.

    Manual Installation with GUI

    1. Download the Agent MSI package from our Download Center.

    2. Execute the MSI package installation on the machine where the Agent is to be installed.

    3. Launch the Real-Time Console, navigate to Agent Settings, and copy your Agent's Authentication Key. This key connects the Agent to your ControlUp environment
      image.png

    4. For version 9.0, a new Registration Key is needed for outbound communication, enabling agents to obtain a Personal Access Token (PAT) from our security service. Ignore this key if you don't want to use this feature. To activate outbound later, manually add the key to the agent's registry under HKLM\SOFTWARE\Smart-X\ControlUp\Agent\Communication. Key name: RegistrationKey

    5. Paste the authentication key you copied from the Real-Time Console during installation.
      image.png

    6. Finish the MSI installation process

    7. If the machine is new and not yet part of the ControlUp organization tree, you must add it using one of two methods:

      1. Within the console, select the "Add Machines" button or
    8. Execute the Add-CUComputer cmdlet on any monitor machine. For instructions on using this cmdlet, click here.

    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.

    From version 9.0

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

    msiexec /i ControlUpAgent-RealTimeAgentManager-net6-x64-9.0.0.1616-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.

    Silently install the 64-bit version agent 9.0 + provided authentication key + registration key (needed for agent outbound communication) + use certificate for agent authentication:

    $authkey = "{enter your AuthKey here}"
    $registrationKey = "{enter your RegistrationKey here}"
    $msiPath = "{path to MSI}"
    $arguments = @(
     '/i',
     "`"$msiPath`"",  
     '/qb',
     "AUTHKEY=$authkey",
     "RegistrationKey=$registrationKey"
    )
    Start-Process -FilePath 'msiexec.exe' -ArgumentList $arguments -Wait -NoNewWindow
    

    Silently install the 64-bit version agent 9.0 from a master image + provided authentication key + registration key + use certificate for agent authentication:

    msiexec /i ControlUpAgent-RealTimeAgentManager-net6-x64-9.0.0.1616.msi /qb AUTHKEY={enter your RegistrationKey here}
    RegistrationKey={enter your RegistrationKey here} MASTER_IMAGE=true
    

    Lower than version 9.0

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

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

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

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

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

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

    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:

    4. Listening port
      Registry Key: HKLM\SOFTWARE\Smart-X{Version}\Agent
      Value: port
      Data Type: DWORD

    5. Authentication Key
      Registry Key: HKLM\SOFTWARE\Smart-X\ControlUp\Agent\Communication
      Value: AuthKey
      Data Type: REG_SZ
      Value Data: *Authentication Key provided in the Agent installation

    6. Registration Key
      Registry Key: HKLM\SOFTWARE\Smart-X\ControlUp\Agent\Communication
      Value: RegistrationKey
      Data Type: REG_SZ
      Value Data: *Registration Key provided in the Agent installation

    7. Service Options for cuAgent Service
      Registry Key: HKLM\SYSTEM\CurrentControlSet\Services\cuAgent
      Value: Different keys

    8. Agent Version and Installation Path
      Registry Key: HKLM\SOFTWARE\WOW6432Node\Smart-X\ControlUpAgent
      Value: Version
      Data Type: REG_SZ
      Value Data: Agent version

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

    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.


    Was this article helpful?