Powershell Cmdlets for Machine and Folder Management
    • Dark
      Light
    • PDF

    Powershell Cmdlets for Machine and Folder Management

    • Dark
      Light
    • PDF

    Article summary

    Our PowerShell cmdlets offer you finer control over your ControlUp environment, enabling you to perform actions that would be otherwise too time-consuming or not possible in the GUI.

    The ControlUp.PowerShell.User module contains most PowerShell cmdlets mentioned in this article. The monitor-specific cmdlets Clear-CUAAQueue, Get-CUAAQueue and Open-ControlUpMonitor can be found in the ControlUp.PowerShell.Monitor module.

    To load the modules, open a PowerShell session as administrator and run the following commands:

    $pathToUserModule = (Get-ChildItem "C:\Program Files\Smart-X\ControlUpMonitor\*ControlUp.PowerShell.User.dll" -Recurse | Sort-Object LastWriteTime -Descending)[0]
    
    $pathToMonitorModule = (Get-ChildItem "C:\Program Files\Smart-X\ControlUpMonitor\*ControlUp.PowerShell.Monitor.dll" -Recurse | Sort-Object LastWriteTime -Descending)[0]
    
    Import-Module $pathToUserModule, $pathToMonitorModule
    

    ControlUp PowerShell Cmdlets

    List ControlUp entities

    • Get-CUFolders. Lists all folder paths of your ControlUp organizational tree.
    • Get-CUComputers. Lists all managed machines in your ControlUp organization.
    • Get-CUSites. List all sites you added to your monitor settings.

    Add ControlUp entities

    • Add-CUComputer. Adds new machines to the your ControlUp organization.
    • Add-CUFolder. Adds a new folder to your ControlUp organizational tree.

    Remove ControlUp entities

    • Remove-CUComputer. Removes a managed machine from your ControlUp organization, but keeps the ControlUp Agent installed.
    • Remove-CUFolder. Removes a folder from the ControlUp organizational tree.

    Move ControlUp entities

    Perform actions in batches
    The following commands enable you to perform batch actions:

    Miscellaneous


    New-CUBatchUpdate

    NAME
    New-CUBatchUpdate

    SYNOPSIS
    Performs batch updates for the computer and folder commands.

    SYNTAX

    New-CUBatchUpdate  [<CommonParameters>]
    

    DESCRIPTION
    This command enables users to perform batch updates when it precedes another command that permits batch actions.

    EXAMPLES
    Example 1:

    $b = New-CUBatchUpdate
    Add-CUComputer -Name PC002 -Domain NTNET -FolderPath "\SQL Servers" -Batch $b
    Add-CUComputer -Name PC003 -Domain NTNET -FolderPath "\SQL Servers" -Batch $b
    Add-CUComputer -Name PC004 -Domain NTNET.local -DnsName PC004.SomeDNSName.com -FolderPath "\SQL Servers" -Batch $b
    Publish-CUUpdates $b
    

    This command adds three machines to the "\SQL Servers" folder path in the organizational tree. In the first two examples, machines "PC002" and "PC003" are in the domain "NTNET", and the third in the "NTNET.local" domain, with a distinct DNS name "PC004.SomeDNSName.com".

    RELATED LINKS
    Add-CUComputer


    Publish-CUUpdates

    NAME
    Publish-CUUpdates

    SYNOPSIS
    Publishes updates to the computer and folder commands.

    SYNTAX

    Publish-CUUpdates [-Batch] <BatchUpdate>  [<CommonParameters>]
    

    DESCRIPTION
    This command enables users to publish batch updates when it precedes another command that permits batch actions.

    EXAMPLES
    Example 1:

    $b = New-CUBatchUpdate
    Get-CUComputers -FolderPath “\SQL Servers” -Match SQLSRV | Remove-CUComputer -Batch $b
    Publish-CUUpdates $bName
    

    This command removes all machines from the \SQL Servers folder path that match the name "SQLSRV".

    Example 2:

    $b = New-CUBatchUpdate
    Search-CUComputersFromAD -Domain NTNET -Name *SQLSRV* | Add-CUComputer -FolderPath “\SQL Servers” -Batch $b
    Publish-CUUpdates $b
    

    The command searches for computers in the NTNET domain that contain "SQLSRV". In the organizational tree, these computers are added to the \SQLServers folder path.


    Show-CUBatchResult

    NAME
    Show-CUBatchResult

    SYNOPSIS
    Shows batch results for the performed computer and folder commands.

    SYNTAX

    Show-CUBatchResult [-Batch] <BatchUpdate> [[-ShowSuccess]]  [<CommonParameters>]
    

    DESCRIPTION
    This command enables users to show results for batch actions performed when it precedes another command that permits batch actions.

    EXAMPLES
    Example 1:

    Show-CUBatchResult Remove-CUFolder -FolderPath 'CUFolder' -ParentPath 'Organization Name'
    

    This command shows the successful/failed attempts to remove multiple folders.


    Add-CUComputer

    The Add-CUComputer cmdlet allows you to add machines to your ControlUp organizational tree. You can add domain-joined and non-domain joined machines to ControlUp.

    Note

    This cmdlet doesn't automatically install the ControlUp Agent on the machine. It only adds the machine to the organizational tree.

    NAME
    Add-CUComputer

    SYNOPSIS
    Adds a machine.

    SYNTAX

    Add-CUComputer [-Name] <string> [-Domain] <string> [[-FolderPath] <string>] [[-DnsName] <string>] [[-SiteId] <string>] [[-Description] <string>] [[-Batch] <BatchUpdate>]  [<CommonParameters>]
    

    DESCRIPTION
    Adds a machine account from Active Directory to the ControlUp Real-Time Console.
    ADComputerName describes the computer account name as it appears in Active Directory.
    DomainName describes the domain name from which the computer will be added.
    FolderPath describes the ControlUp folder path to which the computer will be added.
    This action can be performed in batches.

    PARAMETERS

    -Name
    The hostname of the machine.

    Requiredtrue
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse

    -Domain
    The domain name that this machine is joined to.

    Requiredtrue
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse 

    -FolderPath
    The folder path in your ControlUp organizational tree that the machine should be added to.

    Requiredfalse
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse 

    -DNSName
    The DNS server address that this machine connects to.

    Requiredtrue
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse 

    -SiteId
    The site ID that this machine connects to.

    Requiredtrue
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse 

    EXAMPLES

    Example 1:

    Adds the machine with the hostname DC01, located in the domain.local domain to the folder OrgName\domaincontrollers.

    Add-CUComputer -Name DC01 -DomainName domain.local -FolderPath OrgName\domaincontrollers
    

    Example 2:

    Adds the machine with the FQDN Monitor01.domain.local to the folder azureenv\monitormachines and adds a description "Master Monitor - Site: New York".

    Add-CUComputer -Name Monitor1 -DomainName domain.local -FolderPath azureenv\monitormachines -Description "Master Monitor - Site: New York"
    

    image.png

    Example 3:

    Adds the machine with the FQDN Monitor01.domain.local to the folder azureenv\monitormachines and adds this machine as a data source to all monitor machines in a specific ControlUp Site. In our case, Monitor01 is added to the New York site.
    To get the SiteId, use the Get-CUSites cmdlet.

    Add-CUComputer -AdComputerName Monitor1 -Domain domain.local -Folder 'azureenv\monitormachines' -SiteId 62ff0d5b-143d-4d24-a2e5-15ba1c14830d
    

    image.png

    RELATED LINKS
    Remove-CUComputer


    Remove-CUComputer

    NAME
    Remove-CUComputer

    SYNOPSIS
    Removes a computer from your ControlUp organization. The machine is removed as a data source from the ControlUp Monitor, but the ControlUp Agent is kept on the machine.

    SYNTAX

    Remove-CUComputer [-Name] <string> [[-Force]] [[-Batch] <BatchUpdate>]  [<CommonParameters>]    
    

    DESCRIPTION
    Removes a computer from ControlUp real-time Console.
    Name indicates the computer to be removed from ControlUp real-time Console and can be entered as it appears in ControlUp, as an FQDN or as an IP address.
    PARAMETERS

    -Name

    Requiredtrue
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse 

    EXAMPLES
    Example 1:

    Remove-CUComputer -Name 'John-PC' 
    

    Example 2:

    Remove-CUComputer -Name '117.34.2.7' 
    

    RELATED LINKS
    Add-CUComputer


    Move-CUComputer

    NAME
    Move-CUComputer

    SYNOPSIS
    Moves a computer between ControlUp folders.

    SYNTAX

    Move-CUComputer [-Name] <string> [-FolderPath] <string> [[-Force]] [[-Id] <string>] [[-Batch] <BatchUpdate>] [<CommonParameters>]
    

    DESCRIPTION
    Moves a computer between ControlUp folders.
    This indicates the computer to be moved from current location to -FolderPath, which determines the new location in the ControlUp Real-Time Console.

    The name can be entered as it appears in ControlUp, as an FQDN or as an IP address.
    This action can be performed in batches.

    PARAMETERS

    -Name

    Requiredtrue
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse 

    EXAMPLES

    Move-CUComputer -Name 'John-PC' -FolderPath '\Servers\Boston' 
    


    Add-CUFolder

    NAME
    Add-CUFolder

    SYNOPSIS
    Adds a folder to the console.

    SYNTAX

    Add-CUFolder [-Name] <string> [[-ParentPath] <string>] [[-Description] <string>] [[-ExcludeFromMonitor] <bool>] [[-Batch] <BatchUpdate>]  [<CommonParameters>] 
    

    DESCRIPTION
    Adds a folder to the ControlUp real-time Console. The folder name is specified by the -Name parameter, and its parent location by the -ParentPath parameter. If -ParentPath is not specified, the new folder is created under the root folder.
    Optional parameters - ExcludeFromMonitor determines whether the folder contents are to be excluded from connection by ControlUp Monitor services. If this parameter is not specified, its values are inherited from the parent folder.

    PARAMETERS

    -Name

    Requiredtrue
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse

    -ParentPath

    Requiredfalse
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse

    -Description

    Requiredfalse
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse

    -ExcludeFromMonitor

    Requiredfalse
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse

    EXAMPLES
    Example 1:

    Add-CUFolder -Name 'SQL Servers'
    

    Creates a folder named SQL Servers under the organization root folder.

    Example 2:

    Add-CUFolder -Name 'Production' -ParentPath 'Organization Name\SQL Servers'
    

    Creates a folder named “Production” under the SQL Servers folder.

    Example 3:

    Add-CUFolder -Name 'Test' -ParentPath 'Organization Name\SQL Servers' -Description 'Test SQL Servers' -ExcludeFromMonitor $true 
    

    Creates a folder named “Test” under the SQL Servers folder with the specified description, and instructs ControlUp to exclude this folder from monitor connections.

    RELATED LINKS
    Remove-CUFolder

    REMARKS
    The following characters are allowed: letters, numbers, space, dash and underscore.
    The following folder names are reserved and cannot be used: “Hypervisors”, “Cloud Connections”, “CVAD Sites”.


    Get-CUFolders

    Lists all folders in the ControlUp organization tree.

    Remove-CUFolder

    NAME
    Remove-CUFolder

    SYNOPSIS
    Removes a folder from the ControlUp Real-Time Console.

    SYNTAX

    Remove-CUFolder [-FolderPath] <string> [[-Force]] [[-Batch] <BatchUpdate>]  [<CommonParameters>]
    

    DESCRIPTION
    Removes a folder from the console. Folder path is specified by the -FolderPath parameter.
    Optional parameter - Force ignores any validation questions.
    This action can be performed in batches.

    PARAMETERS

    -FolderPath

    Requiredtrue
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse

    -Force

    Requiredfalse
    PositionNamed
    Accept pipeline inputfalse
    Parameter set name(All)
    Aliases                  None
    Dynamicfalse

    EXAMPLES
    Example 1:

    Remove-CUFolder -FolderPath 'MyFirstCUFolder' -ParentPath “Organization Name”  
    

    Example 2:

    Remove-CUFolder -FolderPath 'MySecondCUFolder' -ParentPath “Organization Name\XD Folders” 
    

    Example 3:

    Remove-CUFolder -FolderPath 'MyThirdCUFolder' -ParentPath “Organization Name” -Force True 
    

    RELATED LINKS
    Add-CUFolder


    Get-CUComputers

    NAME
    Get-CUComputers

    SYNOPSIS
    Returns all managed machines in the ControlUp organization

    SYNTAX

    Get-CUComputers [[-FolderPath] <string>] [[-Match] <string>] [<CommonParameters>]
    

    DESCRIPTION
    When used without parameters, the cmdlet returns all managed machine. Use the -FolderPath parameter to search in particular folder. Using the -Match parameter allows you to filter computer names with regular expressions.


    Search-CUComputersFromAD

    NAME
    Search-CUComputersFromAD

    SYNOPSIS
    Queries the Active Directory for computers that can be added to ControlUp.

    SYNTAX

    Search-CUComputersFromAD [-Name] <string> [-Domain] <string> [[-OU] <string>] [<CommonParameters>]
    

    DESCRIPTION
    Searches the Active Directory for computers with the attributes ControlUp requires (Netbios and dnsHostName). You can pipe the result set to Add-CUComputer (use batch when adding a large number of computers).
    The name is the search string for the computer name. Wildcard characters are supported.
    The domain is the FQDN or NetBIOS name for the AD domain. ControlUp must be configured for this domain.
    OUs are optional and allow for limiting search results.

    REMARKS
    To see the examples, type: "get-help Search-CUComputersFromAD -examples"
    For more information, type: "get-help Search-CUComputersFromAD -detailed"
    For technical information, type: "get-help Search-CUComputersFromAD -full"

    Set-CUComputerDescription

    NAME
    Set-CUComputerDescription

    SYNOPSIS
    Sets the description for a managed machine.

    SYNTAX

    Set-CUComputerDescription [-Name] <string> [-Description] <string> [[-Batch] <BatchUpdate>] [<CommonParameters>]
    

    DESCRIPTION
    Updates the value in the Description column for a specific managed machine.

    EXAMPLES

    Example 1:

    Set-CUComputerDescription -Name Monitor1 -Description "Primary Monitor - Site: New York"
    

    image.png

    Get-CUSites

    Returns all ControlUp sites in your ControlUp environment.

    Get-ExtractLocal

    NAME
    Get-ExtractLocal

    SYNOPSIS
    Gets the extract files mode for the ControlUp Agent deployment.

    SYNTAX

    Get-ExtractLocal [<CommonParameters>]
    

    DESCRIPTION
    When deploying the ControlUp Agent on a machine, the ExtractLocal property describes where agent files are extracted. If set to False, the files are extracted remotely, while True indicates that files are extracted on the local machine (%appdata%/temp). You can change the setting by using Set-ExtractLocal.

    Set-ExtractLocal

    NAME
    Set-ExtractLocal

    SYNOPSIS
    Sets the extract files mode for the ControlUp Agent deployment.

    Set-ExtractLocal [-EnableExtractLocal] <bool> [<CommonParameters>]
    

    EXAMPLES

    Example 1:

    Sets the extract mode to Local. The relevant agent files are extracted in the %appdata%/temp folder of the console machine.

    Set-ExtractLocal -EnableExtractLocal $true
    

    DESCRIPTION
    The cmdlets accepts True or False. See the description above for Get-ExtractLocal.


    Was this article helpful?