Contents x
    Install-CUMonitor: Install a Monitor
      • Print
      • Dark
        Light
      • PDF
      Contents

      Install-CUMonitor: Install a Monitor

        • Print
        • Dark
          Light
        • PDF
        Article Summary

        The new ControlUp Automation module includes the Install-CUMonitor PowerShell cmdlet which allows you to install a ControlUp Monitor programmatically. To install a monitor, you must provide an API token generated from app.controlup.com.

        Benefits

        • You no longer need to use the Real-Time Console to deploy and configure monitors
        • You can install monitors on workgroup machines, allowing you to host monitors, for example, on cloud VMs

        Prerequisites

        • If your organization already exists in the Real-Time Console, the user you use to install the monitor 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 monitors. Note that running the Install-CUMonitor automatically bootstraps a new Real-Time DX organization. The name of this organization will be the same as in DEX.

        Syntax

        Install-CUMonitor
-Token <string>
-ZipFilePath <string>
-Version or -Latest <string>
-SiteName <string>
-Template <string>
-ProxySettings <ProxySettingsObject>
-DomainDns <string>
-DomainUser <string>
-DomainUserPassword <SecureString>
-PublicDNSName or -InternalDNSName <string>
-Certificate <string>
-CertificatePassword <SecureString>

        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

        -ZipFilePath

        Full path to the ZIP folder that contains the ControlUp Monitor binaries. If not provided, -Version will be used.

        No

        -Version

        Switch parameter for -Latest, monitor version.

        No

        -Latest

        Switch parameter for -Version, latest monitor version. If provided, overrides -Version.

        No

        -SiteName

        Name of the monitor site. If not provided, the monitor will be added to the default site.

        No

        -Template

        Name to define the monitor template. Available templates include:

        • -all

        • -coordinator

        • -folderagg

        • -monitoring

        • -management

        • -viewnode

        • -monitoring_only

        • -indexing_only

        If empty, the selected template will be -all.

        No

        -ProxySettings

        Proxy settings that the monitor will use to connect to the ControlUp services. If not provided, the default system proxy settings will be used. If -SiteName is provided, the proxy settings and credentials will be added to the specific site, if no proxy settings already exist.


        Example to create proxy settings variable:

        $Secure = Read-Host -AsSecureString
$proxys = New-Object -TypeName ControlUp.Automation.ProxySettings
$proxys.Password=$Secure
$proxys.Address="127.0.0.1"
$proxys.Port=80802

        No

        -DomainDns

        If provided and no AD connection already exists in the domain, the AD connection will be added with the -DomainUser and -DomainUserPassword credentials. If -SiteName is provided, the AD connection and credentials are added to the specific site.

        No

        -DomainUser

        Domain user name. If not provided, the AD connection won’t be added.

        No

        -DomainUserPassword

        Domain user password. If not provided, the AD connection won’t be added.

        Example to create password variable:

        $Pwd = Read-Host -AsSecureString

        No

        -PublicDNSName

        Switch parameter for -InternalDNSName, publicly accessible DNS name required for ControlUp Agent to communicate with monitor.

        Yes, if no -InternalDNSName

        -InternalDNSName

        Switch parameter for -PublicDNSName, internally accessible DNS name required for ControlUp Agent to communicate with monitor. Required to install a non-domain joined monitor.

        Yes, if no -PublicDNSName

        -Certificate

        Name of the certificate required for authentication.

        No

        -CertificatePassword

        Password of the certificate required for authentication.

        No

        Install Monitor on a Workgroup Machine

        To install a monitor on a workgroup machine, please follow the steps below. These steps should be executed on the machine where you intend to deploy the monitor.

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

            
      Install-Module ControlUp.Automation.dll

        2. Import the module:

            
      Import-Module [PathTo_ControlUp.Automation.dll]

        3. Install the monitor:

        PowerShell
              
Install-CUMonitor `
    -Token "[Token]" `
    -PublicDNSName "[Machine Name].[Connection-specific DNS Suffix]" `
    -InternalDNSName "[Machine Name].[Connection-specific DNS Suffix]"

        Example:

        PowerShell
        Install-CUMonitor `
    -Token "eyJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3Mzc5NzY0NjEsImlhdCI6MTcwNjQ0…." `
    -PublicDNSName "PSMonitor01.4rgvsyeccjuujimhr5m1ljkc.bx.internal.cloudapp.net" `
    -InternalDNSName "PSMonitor01.4rgvsyeccjuujimhr5m1ljkc.bx.internal.cloudapp.net" `

        4. Version 1.0.1 of the automation module requires you to manually install the ControlUp Agent on this machine. The preferred option is to use the MSI installation package. Given that this agent will be deployed on a non-domain joined machine, it's important to verify that the agent's DNS address is resolvable from your monitors in your monitor cluster. This is typically achieved through the connection-specific DNS suffix found on the agent machine. To obtain this, open a command prompt and run ipconfig /all

        PowerShell Commands
        Import-Module "C:\Program Files\Smart-X\ControlUpMonitor\Version 9.0.0.1546\ControlUp.PowerShell.User.dll"
Add-CUComputer -name [Machine Name] -DnsName [Machine Name].[Connection-specific DNS Suffix]

        Example:

        PowerShell
        Add-CUComputer -name PSMonitor01 -DnsName PSMonitor01.4rgvsyeccjuujimhr5m1ljkc.bx.internal.cloudapp.net

        If you want to deploy other monitors, repeat steps 1-4.

        Stop Workgroup Monitor
        Note that if you want to stop a workgroup monitor, you must run the Stop monitor action on the monitor in the web UI. You can't use the Real-Time Console to stop a workgroup monitor.

        If you want to deploy a monitor with custom manual settings, we recommend you use the following script as a base to create your own:

        Install-CUMonitor -Token "[Token]" -InternalDNSName "[Machine Name].[Connection-specific DNS Suffix]"

        Results

        Writes single result object to PowerShell with the following properties:

        • Error. In case of failure, the reason will be displayed.
        • Success. Indicates if the monitor installation and login completed successfully.

        In case of failure during the installation, all the changes will be canceled. In case of failure during login, the changes will be implemented.

        If these cases occur, you can uninstall the monitor by running Uninstall-CUMonitor

        Was this article helpful?
        What's Next