9.0 PowerShell Cmdlets
    • Dark
      Light
    • PDF

    9.0 PowerShell Cmdlets

    • Dark
      Light
    • PDF

    Article Summary

    9.0 Beta

    This article covers information relevant only to the version 9.0 beta release. Want to be the first to try our new features? Join the ControlUp Beta Program!

    From the 9.0 beta release, you can use the following PowerShell cmdlets to install and configure your Controlup Monitors, change your security policy, and manage API tokens for ControlUp user profiles, cloud connections, or Horizon EUC environment connections.

    Before version 9.0, you were required to install monitors using the Real-Time DX Console. Now you can deploy and manage monitors via an automated process using PowerShell. The updates include:

    • API token-based authentication. The API token contains all the essential data required for the monitor to connect seamlessly with your organization.

    • Web UI integration. You create and manage the token using our web UI. This ensures that each token is uniquely tied to specific organizational parameters, including the web UI organization ID and user ID.

    • PowerShell cmdlets module installation. You install the monitor with the module using the token.

    If you have an assigned customer success or account manager, they can provide you with the PowerShell cmdlets module to download.

    For any questions or assistance, contact us at support@controlup.com.

    Import cmdlets

    After you download the cmdlets module, you must launch all cmdlets from the module on the same host where the ControlUp Monitor service is installed.

    To enable the cmdlets to use, you must first import the module:

    1. Open a PowerShell session on the host with the ControlUp Monitor and run the following command:

      Import-Module ".\ControlUpAutomation\ControlUp.Automation.dll"

    If successful, no results display.

    1. Optionally, to verify the import of the module and list available cmdlets, run the following command:

      Get-Command -Module ControlUp.Automation

    If successful, the results display similar to the following example:

    verifycmdlets9

    Install and configure monitors

    Run the following cmdlets to install and configure your monitors:

    Cmdlet

    Description

    Install-CUMonitor

    Installs ControlUp Monitor.

    Invoke-CUMonitorUpdate

    Updates previously installed ControlUp monitor.

    Uninstall-CUMonitor

    Uninstalls ControlUp Monitor from the local machine.

    Install-CUMonitor

    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>

    DESCRIPTION

    Installs a ControlUp Monitor on your local machine. To install a monitor, you must provide an API authentication token generated from app.controlup.com.

    To create an API authentication token:

    1. Go to the web UI (app.controlup.com) and register with an email. The user must have the Manage API Keys permission.

    2. Click on your profile at the bottom-left of the screen and select Change organization > Create a new organization and create a new organization.

    3. Click API Key Management, create an API Token, and copy it. You can now use the token in your commands.

    Note that the first time you run this cmdlet, the name of the Real-Time DX Console database is given the same name as the organization you created in the web UI.

    Parameters

    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 is used.

    No

    -Version

    Switch parameter for -Latest, name of the monitor version.

    Yes, if no -Latest

    -Latest

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

    Yes, if no -Version

    -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 are used. If -SiteName is provided and no proxy settings already exist, the proxy settings and credentials are added to the specific site.

    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.

    Yes, if no -PublicDNSName

    -Certificate

    Name of the certificate required for authentication.

    Yes

    -CertificatePassword

    Password of the certificate required for authentication.

    Yes

    Results

    • Error. In case of failure, the reason will display.

    • 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 run Uninstall-CUMonitor to uninstall the monitor, or run CUMonitorCloudSpecs and CUMonitorCompleteSetupAndLogin to finish the installation.

    Invoke-CUMonitorUpdate

    SYNTAX

    Invoke-CUMonitorUpdate
    -ZipFilePath <string>
    -Version or -Latest <string>
    -ProxySettings <ProxySettingsObject>

    DESCRIPTION

    Updates the current ControlUp Monitor by either providing the ZIP file with the latest version or by providing the specific version in the -Version parameter. -Version downloads the ZIP file from the ControlUp Cloud and provides it as a local file on the monitor machine.

    Parameters

    Description

    Required

    -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, full name of the monitor version.

    Yes, if no -Latest

    -Latest

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

    Yes, if no -Version

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

    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

    Uninstall-CUMonitor

    SYNTAX

    Uninstall-CUMonitor 
    -Force
    <CommonParameters>

    DESCRIPTION

    Uninstalls ControlUp Monitor from the local machine.

    Parameters

    Description

    -Force

    Uninstalls the monitor even if backend errors occur.

    Change security policy

    Run the following cmdlets to make changes to your security policy:

    Cmdlet

    Description

    Add-CUPolicyRoles

    Creates new security policy role columns in the Security Policy panel with the Manage Solve and Use Web Application permissions set to Allow. You must configure the New-CUPolicyRoleDescriptor cmdlet before you run Add-CUPolicyRoles. Possible configurations include adding role members with New-CUPolicyRoleMember and configuring permissions set for folder with New-PolicyRoleAcl.

    Get-CUPolicyRoles

    Retrieves list of all security policy roles and members.

    Get-CUPermissionEntries

    Retrieves list of all available permission entries.

    New-CUPolicyRoleDescription

    Adds a new policy role description.

    New-CUPolicyRoleMember

    Adds a new policy role member.

    New-CUPolicyRoleAcl

    Adds a new policy role to the Access Control List (ACL) with permission to open the web UI without entering UPN credentials.

    Example below to configure the following two roles:

    • ControlUp Admins. Built-in role to add new members only.

    • Customers. Creates new role to add members and to configure the Manage Solve and Use Web Application permissions.

    $role=New-CUPolicyRoleDescription -RoleName "ControlUp Admins"
    New-CUPolicyRoleMember -Role $role -SecurityIdentifier 7d1a5930-0739-4eb5-8825-36ee10edd233 -DisplayName "Organization Engineer DW"
    
    $customer=New-CUPolicyRoleDescription -RoleName "Customers"
    New-CUPolicyRoleMember -Role $customer -SecurityIdentifier d09e999a-29ff-4be3-aeff-384ecf92b1d2 -DisplayName "Organization Customer DW"
    $permissions=@{ `"1B5974A1-3487-4054-8DF9-941318F7E2B6"=$true; ` # Use solve
                     "5AD549BF-A0AA-4241-A5F6-B11FFBD21F3A"=$false ` # Manage solve}
    New-CUPolicyRoleAcl -Role $customer -FolderId 00000000-0000-0000-0000-000000000000 -Entries $permissions
    
    Add-CUPolicyRoles -Roles $role, $customer 

    Manage API tokens

    Run the following cmdlets to manage API tokens for your ControlUp user profiles to enable use of cmdlets on workgroup machines:

    Cmdlet

    Description

    Get-CUAPIProfile

    Retrieves your current active profile.

    Set-CUAPIProfile

    Enables you to switch between different profiles. Syntax example: Set-CUAPIProfile -Profile <org-name>

    Set-CUAPIToken

    Stores an API token in a profile you define. This token is only readable by the defined user, and is securely encrypted (Base64-encoded) using DPAPI and saved under %appdata%\ControlUp\.cuapi. Syntax example: Set-CUAPIToken -Token <XXX> [-Profile “default”]

    Your tokens are securely stored and associated with profile names in the .cuapi file, for example:

    {
        "current": "username-dev",
        "profiles": [
            {
                "name": "default",
                "token": "<encrypted token>"
            },
            {
                "name": "controlup demo",
                "token": "<encrypted token>"
            },
            {
                "name": "username-dev",
                "token": "<encrypted token>"
            }
        ]

    Manage cloud connections

    Run the following cmdlets to manage cloud connections:

    Note

    In version 9.0, you can use these cmdlets to manage Azure cloud connections only.

    Cmdlet

    Description

    Add-CUCloudConnection

    Creates a new cloud connection with Azure connection type.

    Get-CUCloudConnection

    Retrieves list of all cloud connections.

    Remove-CUCloudConnection

    Removes a connection by unique ID.

    Update-CUCloudConnection

    Updates your existing site with the subscription credentials of another site that you add and configure.

    Add-CUCloudConnection syntax example:

    Add-CUCloudConnection 
    -Type Azure 
    -TenantID <TenantID> 
    -Site <SiteID> 
    -Credentials <Credentials>
    -Proxy <ProxyName>
    -DataCollectors <DataCollector1, DataCollector2>
    -EnableAvd <true>

    Manage Horizon EUC environment connections

    Run the following cmdlets to manage Horizon EUC environment connections:

    Note

    Only Horizon Standard architecture is supported for Horizon EUC environment connection cmdlets, not Cloud Pod Architecture (CPA).

    Cmdlet

    Description

    Add-AddHorizonEUCConnection

    Creates a new Horizon connection.

    Get-EUCConnections

    Retrieves list of all EUC connections.

    Remove-EUCConnection

    Removes an EUC connection by unique ID.

    Update-HorizonEUCConnection

    Removes the existing Horizon connection.


    Was this article helpful?