Install-CUAgent: Install an Agent
    • Dark
      Light
    • PDF

    Install-CUAgent: Install an Agent

    • Dark
      Light
    • PDF

    Article summary

    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

    ParameterDescriptionRequired
    -TokenToken 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
    -AgentAuthenticationKeyPublic 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
    -AgentRegistrationKeyPublic 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
    -AddFirewallRuleAdds an inbound firewall rule to the agent service.
    -AgentPortSets port for an inbound agent. By default, 40705.No
    -BrokeringModeIf 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
    -ConnectionTypeSets the agent communication to monitors as an Inbound or Outbound connection type. If not provided, will be set to Outbound.No
    -FolderPathIf 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
    -InstallationDirectoryIf provided, you can define a custom installation folder for the agent file. If not provided, the default installation folder will be used.No
    -InstallAgentManagerIf set to $true, installs Real-Time Agent Manager with agent. If set to $false doesn't install Agent Manager.No
    -InstallAsMasterImageRelevant only for outbound agents, installs the agent machine as a master image.No
    -LatestSwitch parameter for -Version, latest agent version. If provided, overrides -Version.No
    -ProxySettingsProxy 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
    -ProxyToControlUpBackendProxy connection to ControlUp backend.No
    -ProxyToMonitorProxy connection that the agent will use to connect to the monitor services.No
    -SiteAssigns a ControlUp Monitor site ID or name from your organization to the Agent.No
    -VersionSwitch parameter for -Latest, agent version.No
    -ZipFilePathFull 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

    Was this article helpful?