- Print
- DarkLight
- PDF
Install-CUAgent: Install an Agent
- Print
- DarkLight
- PDF
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 token generated from app.controlup.com (DEX).
If you provide the API token with the Install-CUAgent cmdlet, it adds the agent machine to your organization tree. By default, the cmdlet returns whether the agent was successfully installed or not.
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 Console
- Install the MSI directly without using the ZIP file
- Install agents on workgroup machines
Prerequisites
- ControlUp Real-Time DX Console Version 9.0 or higher.
- If your organization already exists in the Real-Time Console, the user you use to install the agent must be a Login Access 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>
-SiteName <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>
Parameters
Parameter | Description | Required |
---|---|---|
-Token | Token string generated by web UI for authentication and authorization. If not provided, the current profile token will be used. For more details, see manage API tokens. | Yes |
-AgentAuthenticationKey | Public key to authorize inbound connections to the agent. You can copy the key from the Real-Time Console (Settings > Agent > Agent Authentication Key) or by running the Get-AgentPublicKey cmdlet on your monitor machine. | Yes |
-AgentRegistrationKey | Public key to authorize outbound connections from the agent to the monitors. You can copy the key from the Real-Time Console (Settings > Agent > Agent Registration Key) or by running the Get-AgentRegistrationKey cmdlet on your monitor machine. | Yes |
-AddFirewallRule | Adds an inbound firewall rule to the agent service. | |
-AgentPort | Sets port for an inbound agent. By default, 40705. | No |
-BrokeringMode | If set to online, the agent will connect to online brokering service via ControlUp Hybrid Cloud Services. If set to offine, the agent will connect to brokers listed in the registry settings of the agent machines. | No |
-ConnectionType | Sets the agent communication to monitors as an Inbound or Outbound connection type. If not provided, will be set to Outbound. | No |
-FolderPath | If provided with an API token, the folder path in your organization tree to add the agent to. If the specified folder doesn't exist, it gets created. If -FolderPath not provided, the latest agent uploaded to the cloud will be installed. | No |
-InstallationDirectory | If provided, you can define a custom installation folder for the agent file. If not provided, the default installation folder will be used. | No |
-InstallAgentManager | If set to $true , installs Real-Time Agent Manager with agent. If set to $false doesn't install Agent Manager. | No |
-InstallAsMasterImage | Relevant only for outbound agents, installs the agent machine as a master image. | No |
-Latest | Switch parameter for -Version, latest agent version. If provided, overrides -Version. | No |
-ProxySettings | Proxy settings that the ControlUp Automation module will use to download the Agent binaries and register the Agent. If not provided, the default system proxy settings will be used. | No |
-ProxyToControlUpBackend | Proxy connection to ControlUp backend. | No |
-ProxyToMonitor | Proxy connection that the agent will use to connect to the monitor services. | No |
-Site | Assigns a ControlUp Monitor site ID or name from your organization to the Agent. | No |
-Version | Switch parameter for -Latest, agent version. | No |
-ZipFilePath | Full path to the ZIP folder that contains the ControlUp Agent binaries. If -ZipFilePath not provided, -Version will be used, and the agent version you specified from the cloud will be installed. | No |
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:
Install-Module ControlUp.Automation
2. Import the module:
Import-Module [DLL Path]
3. Install the agent:
Install-CUAgent
-Token "[APIToken]"
-AgentAuthenticationKey "[Authentication Key]"
-AgentRegistrationKey "[Registration Key]"
-InstallAgentManager $true
Example:
Install-CUAgent
-Token "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MjEwNDIzNDcsImlhdCI6MTcI..."
-AgentAuthenticationKey "BgIAAACkAABSU0ExAAgAAAEAAQDRBf3j8YX6MM4djuBvdfVsDCgS4..."
-AgentRegistrationKey "eyJhbGciOiJub25lIiwidHlwIjoiSldUIn0.eyJrZXkiOiJRcGZ3YkYrZFVhRzlW..."
-InstallAgentManager $true
Uninstall-CUAgent
Syntax
Uninstall-CUAgent
-Token <string>
-Force <string>
-Debug <string>
-RemainOnOrgTree <string>
Description
Uninstalls the ControlUp Agent from your local machine. If you run the cmdlet with an API token, it also removes the agent from your organization tree.
Parameters
Parameter | Description | Required |
---|---|---|
-Token | Token string generated by web UI for authentication and authorization. | No |
-Force | Uninstalls the agent even if backend errors occur. | No |
-Debug | Enables agent debugging. | No |
-RemainOnOrgTree | If provided, the agent remains in your organization tree after you uninstall it. | No |