Install-CUAgent: Install an Agent

The ControlUp Automation module includes the Install-CUAgent PowerShell cmdlet which allows you to download and install a ControlUp Agent on your local machine. You can either download the agent binaries from the ControlUp Cloud or from a local ZIP file. To install a non-domain joined agent on a workgroup machine, you must provide an API authentication token (API Key) generated from app.controlup.com (DEX).

If you provide the API Key with the Install-CUAgent cmdlet, it adds the agent machine to your organization tree in the Real-Time DX Console. By default, the cmdlet returns whether the agent was successfully installed or not.

From ControlUp version 9.0.5 and higher, you can use agent self-registration with either PowerShell cmdlets or our MSI to add the agent machine to your organization tree. For versions lower than 9.0.5, you must use the Console to manually add the agent machine to your organization tree.

To uninstall the agent from your local machine, use the Uninstall-CUAgent cmdlet. To update an agent, see Invoke-CUAgentUpdate.

Benefits

• Download and install agents with no need to use the Real-Time DX Console.
• Install the MSI directly without using the ZIP file.
• Install agents on workgroup machines.
• Automatically register and connect agents to monitors.

Prerequisites

• Real-Time DX Console Version 9.0 or higher.
• If your organization already exists in the Real-Time DX Console, the user you use to install the agent must be a Roles Manager.
• If your organization doesn’t exist in the console, you must be assigned the DEX Admin role for permission to deploy agents.
•  For machine requirements, see here.

Syntax

Install-CUAgent -Token <string> -InstallationDirectory <string> -FolderPath <string> -InstallAgentManager <boolean> -Site <string> -BrokeringMode <Online/Offline> -MonitorFQDNs <string> -ProxyToControlUpBackend <string> -ProxyToMonitor <string> -ZipFilePath <string> -Version or -Latest <string> -ProxySettings <ProxySettingsObject> -AgentRegistrationKey <string> -AgentPort <Int32> -AgentAuthenticationKey <string> -InstallAsMasterImage <boolean> -AddFirewallRule <boolean> -ConnectionType <string> -Debug <string>

Parameters

Install Agent on a Local Machine

To install a ControlUp Agent on a local machine, follow the steps below.

1. Open a PowerShell session with elevated permissions and install the module by running the following:

Install-Module ControlUp.Automation

The module is automatically imported.

2. Install the agent:

Install-CUAgent 
-Token "[APIKey]" or -AgentAuthenticationKey "[Authentication Key]" -AgentRegistrationKey "[Registration Key]" 

Example:

Install-CUAgent 
-Token "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MjEwNDIzNDcsImlhdCI6MTcI..."

Install Agent with Self-Registration

To install an agent using self-registration, follow the steps below.

1. Open a PowerShell session with elevated permissions and install the module by running the following:

Install-Module ControlUp.Automation

The module is automatically imported.

2. Install the agent and provide the following required parameters:

Install-CUAgent 
-Token "[APIKey]" 
-Site "[SiteName]" 
-FolderPath "[FolderPathName]"
-Version "[VersionNumber]"

Example:

Install-CUAgent 
-Token "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MjEwNDIzNDcsImlhdCI6MTcI..."
-Site "American Airlines" 
-FolderPath "EmployeeSeven\NewFolder"
-Version "9.0.5.423"

In the example above, the agent is automatically added to the organization tree in the folder "NewFolder" and assigned to the site "American Airlines." By default, the agent connects outbound to the monitor in the assigned site.

Uninstall-CUAgent

Uninstalls the ControlUp Agent from your local machine. If you run the cmdlet with an API Key, it also removes the agent from your organization tree.

Syntax

Uninstall-CUAgent
-Token <string> 
-Force <string> 
-Debug <string>
-RemainOnOrgTree <string>

Parameters